Deployment Checklist for Magento Teams Using GitLab as a Standard Process

1. Why a deployment checklist is not overhead

In many Magento teams a deployment checklist is seen as bureaucratic overhead, something for sluggish enterprise processes, not for an agile team. That view usually flips after the first undocumented incident. A checklist is not a sign of distrust in the team, it is the externalization of implicit knowledge. It makes visible what everyone already carries in their head but never wrote down, and that is exactly what reveals the gaps.

For Magento teams using GitLab a checklist is especially valuable because the deployment process has many moving parts: repository rules, CI/CD variables, runner configuration, build artifacts, release structure, shared paths, Magento specific steps, verify jobs and rollback paths. Each of these areas has prerequisites that must be met for the deployment to work. A checklist makes these dependencies explicit and lets the team onboard new members quickly.

There is another benefit: a completed checklist is documentation after the deployment. Anyone who later needs to reconstruct what changed and when, and whether every step was carried out correctly, has a starting point for the post-incident analysis. This matters most when a problem only surfaces hours or days after the deployment.

2. Repository foundation: branches, tags and protection mechanisms

The first checklist category concerns the repository itself. Without properly configured branch protection and tag rules, any developer with repository access can trigger an unintended production deployment. Magento projects need at least the following settings: main and every release/* branch configured as protected branches, so pushes are only possible through merge requests. Protected tags with the pattern v*, so only authorized roles can create release tags.

Merge request settings should require at least one reviewer and only allow merging once the pipeline is green. That guarantees no code lands on main without passing the CI checks. Environment scopes for variables must be set so that staging secrets are never available in production jobs, and vice versa.

# GitLab repository governance checklist
# Verify these settings before first production deploy

# 1. Protected branches: only MR-based merges allowed
protected_branches:
  - name: main
    push_access_level: no_one
    merge_access_level: maintainer
  - name: "release/*"
    push_access_level: developer
    merge_access_level: maintainer

# 2. Protected tags: only maintainers can create v* tags
protected_tags:
  - name: "v*"
    create_access_level: maintainer

# 3. Merge request requirements
merge_request_settings:
  approvals_required: 1
  pipelines_must_succeed: true
  prevent_secrets: true

3. CI/CD variables: the pipeline's configuration contract

CI/CD variables are the configuration contract between the GitLab project and its pipelines. Without variables that are set completely and correctly, every deploy job fails, or worse, it runs through but uses the wrong values. For Magento you need at minimum an SSH key, target server address, deploy path and Composer auth token. Every variable must be assigned to the correct environment scope.

Protected variables must only be available in pipelines running on protected branches or tags. That prevents a merge request from a fork from reading out production secrets. Masked variables hide the value in pipeline logs, which is mandatory for SSH keys and API tokens. The distinction between file variables (for multiline values such as SSH keys or env.php content) and plain string variables should be made explicit.

4. Runner configuration and security prerequisites

The GitLab runner is the executing system of the pipeline and must be configured and secured accordingly. For Magento deployments a dedicated, self-hosted runner is almost always preferable: it gives you control over the installed tools, avoids sharing build artifacts with other projects and enables direct access to internal network resources. Shared runners on GitLab.com are fine for the build, but should never have SSH access to production servers.

Runner tags in .gitlab-ci.yml ensure that deploy jobs only run on the runner designated for them. Concurrency settings prevent two deployments from accessing the same server at the same time. The runner shell or the Docker image used must include PHP, Composer, Node.js, rsync and an SSH client in compatible versions.

# Runner configuration checklist: config.toml excerpt
# Self-hosted runner for Magento deployments

[[runners]]
  name = "magento-deployer"
  url = "https://gitlab.com/"
  executor = "docker"
  # Limit concurrent deploys: prevents race conditions
  limit = 1

  [runners.docker]
    image = "php:8.4-cli"
    # Mount composer cache for faster builds
    volumes = ["/cache/composer:/root/.composer:rw"]
    # Never use privileged mode for deploy jobs
    privileged = false

# deploy:production job uses this runner via tags
# In .gitlab-ci.yml:
# deploy:production:
#   tags:
#     - magento-deployer

5. Build checklist: artifacts before deployment

The build phase is the first and most important quality gate. This is where you find out whether the code is even deployable, before a single byte is transferred to the production server. For Magento the build checklist covers: Composer install without dev dependencies (--no-dev), NPM install and frontend build with Tailwind CSS, DI compilation (setup:di:compile), PHPStan analysis at level 5 or higher, and PHPUnit tests for critical modules.

The build artifact must contain every required file: vendor/, generated/, compiled Tailwind CSS files and all static content assets. The artifact size should be monitored: a suddenly larger artifact can indicate accidentally included dev dependencies or build outputs that should never be deployed.

6. Server prerequisites: release structure and shared paths

Before the first deployment happens, the directory structure on the target server must be prepared. This preparation is a one-time task, but it is a prerequisite for every deployment that follows. The directory structure consists of a releases/ directory for the individual release states, a shared/ directory for persistent data, and a current symlink that points to the active release.

All persistent files and directories must already exist inside shared/: app/etc/env.php with the production database connection, pub/media/ with the current media state, var/log/ for application logs and var/session/ for sessions. This content is never deployed with the code, it persists across every release and is linked in via symlink.

# Server preparation checklist: run once before first deploy
# Execute via SSH on target server

# 1. Create base directory structure
mkdir -p /var/www/magento/{releases,shared}
mkdir -p /var/www/magento/shared/app/etc
mkdir -p /var/www/magento/shared/pub/media
mkdir -p /var/www/magento/shared/var/{log,session,cache}

# 2. Place env.php in shared directory (never in releases)
# scp app/etc/env.php deploy@server:/var/www/magento/shared/app/etc/

# 3. Set correct ownership for web server user
chown -R www-data:www-data /var/www/magento/shared

# 4. Verify Nginx/Apache points to /var/www/magento/current/pub
# document root = /var/www/magento/current/pub

7. Deploy phase: symlink switch and Magento steps

The deploy phase is the most critical phase of the entire process. It begins with transferring the build artifact into a new release directory and ends with the atomic switch of the current symlink. Between those two points every Magento specific step must run in the right order: set up shared symlinks, run setup:upgrade (when migrations exist), deploy static content if it was not shipped as part of the artifact, enable maintenance mode only when unavoidable, and finally flush the cache.

Maintenance mode should be treated as a last resort, not a default step. For deployments without database migrations, or with backward compatible migrations (expand/contract), maintenance mode is not needed at all. The symlink switch itself is atomic from the web server's point of view, since it only changes a symlink pointer, not the underlying file state.

8. Verify checklist after deployment

Defined verification steps must run after every deployment. These steps are not a nice-to-have, they are part of the process itself: a deployment is only considered complete once the verify job is green. The minimum requirements are: an HTTP 200 response on the health endpoint, HTTP 200 on the homepage, no critical error in var/log/exception.log within the first two minutes after the deploy, and a Magento cache status without critical errors.

For high traffic shops, additional smoke tests for the most important customer journeys are worth the investment: loading a category page, loading a product detail page, checking the cart endpoint. These tests can be built with simple curl calls or a lightweight test framework like Playwright or Cypress, and configured directly as GitLab CI jobs.

9. Rollback checklist: documenting and practicing the way back

The rollback checklist is the most frequently neglected item, and at the same time the most important. A rollback process that only exists in theory is not a rollback process. It must be documented, tested, and run through completely on staging at least once before it is ever needed for real. For Magento with GitLab this means: a dedicated rollback job in the pipeline that can be triggered manually or automatically on verify failure.

The rollback job switches the current symlink back to the last stable release and flushes the cache. It must log the rollback action in the pipeline logs, so it is traceable when and why a rollback happened. After a rollback the verify job must run again, to confirm that the previous state is actually working again.

# rollback:production job: manual trigger or auto on verify failure
rollback:production:
  stage: rollback
  image: php:8.4-cli
  when: manual
  environment:
    name: production
    action: stop
  script:
    - apt-get update -qq && apt-get install -y -qq openssh-client
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh && echo "$SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
    # List available releases and switch to the previous one
    - |
      ssh "$DEPLOY_USER@$DEPLOY_HOST" '
        set -euo pipefail
        PREV=$(ls -1t '"$DEPLOY_PATH"'/releases/ | sed -n "2p")
        if [ -z "$PREV" ]; then echo "[ERROR] No previous release found"; exit 1; fi
        ln -sfn "'"$DEPLOY_PATH"'/releases/$PREV" "'"$DEPLOY_PATH"'/current"
        cd "'"$DEPLOY_PATH"'/current"
        php bin/magento cache:flush
        echo "[OK] Rolled back to: $PREV"
      '
  needs: ["verify:production"]

10. Summary

A deployment checklist for Magento teams using GitLab is not a bureaucratic document, it is the team's implicit knowledge made explicit. It covers repository governance with protected branches and tags, fully configured CI/CD variables with correct environment scopes, a configured and secured runner, reproducible build artifacts without dev dependencies, a prepared release structure with shared paths on the server, a defined deploy sequence for Magento specific steps, automated verify jobs after the symlink switch, and a tested rollback path.

What matters most is not that every point gets implemented at once, but that the team shares a common understanding of which points are covered and which are not. An honest gap analysis against this checklist shows where the deployment process actually stands, not where you would like it to be.

11. FAQ: Deployment Checklist for Magento Teams with GitLab

A living deployment checklist is not a bureaucratic document, it is the team's memory. It grows with every incident and makes recurring mistakes visible before they ever reach production.