Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 36 ยท Environments and Deployments

Deployment Strategies and Rollbacks

Compare rolling, blue-green and canary releases, then use GitLab rollbacks, protected environments, deployment approvals and deploy freezes to ship safely.

Deploying is the moment code meets real users, so how you do it decides how much a bug costs. A good strategy limits the number of users who see a defect, and a good recovery plan means you can undo the release in minutes. This lesson compares common release strategies and then shows the GitLab features that support them: rollbacks, protected environments, deployment approvals and deploy freezes.

GitLab does not run your servers. Your scripts, Kubernetes or a cloud service perform the release; GitLab orchestrates the pipeline, records the history and controls who may deploy. The examples are stand-ins in JavaScript that model the decisions.

Release strategies

Strategy How it works Good for Watch out for
Recreate Stop the old version, start the new one Small apps, maintenance windows Downtime
Rolling Replace instances a few at a time Most stateless services Two versions run side by side briefly
Blue-green Run a full second copy, then switch traffic Instant switch and instant switch back Double the capacity, database changes
Canary Send a small share of traffic to the new version first Risky changes, large audiences Needs metrics and traffic control
Feature flags Ship code switched off, enable it later Decoupling deploy from release Old flags must be removed
flowchart LR
  U["users"] --> LB["load balancer"]
  LB -->|"95%"| OLD["version 1"]
  LB -->|"5%"| NEW["version 2 (canary)"]
  NEW --> M{"error rate OK?"}
  M -->|"yes"| UP["raise to 25%, 50%, 100%"]
  M -->|"no"| RB["send all traffic to version 1"]

A canary release grows in steps and retreats when metrics look bad.

In a GitLab pipeline, a canary or staged rollout is often a chain of manual jobs, each raising the share:

YAML
rollout_10:
  stage: deploy
  script: ./scripts/set-weight.sh 10
  environment: production
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual

rollout_50:
  stage: deploy
  script: ./scripts/set-weight.sh 50
  environment: production
  needs: [rollout_10]
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual

rollout_100:
  stage: deploy
  script: ./scripts/set-weight.sh 100
  environment: production
  needs: [rollout_50]
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual

The person pressing play looks at dashboards between steps. set-weight.sh is your own script, for example a change to a Kubernetes service or load balancer. A Kubernetes setup with an ingress controller or a service mesh does the splitting, not GitLab.

Rolling back

When a release goes wrong, the fastest fix is usually to deploy the last version that worked. GitLab supports this because every deployment keeps the job that created it. On the environment page, each older deployment has a Rollback button (a "Re-deploy" button on the newest). Pressing it runs the old deployment job again, with the old commit and the variables that were stored for that job.

Rolling back works well when:

  • the deploy job is idempotent: running it again for the same commit produces the same state;
  • artifacts needed by the job still exist (they may have expired, so set expire_in generously for deploy artifacts);
  • database changes are backward compatible, so the old code can still read the new schema.

A rollback does not undo a database migration or sent e-mails. The safe habit is the "expand and contract" pattern: add new columns first, ship the code that uses them, and remove the old columns in a later release. Also decide in advance how long a rollback takes; the answer should be minutes, not an afternoon of reading logs.

Who may deploy: protected environments

By default, anyone who can run a pipeline job could run a deploy job. Protected environments limit this. In Settings > CI/CD > Protected environments you choose which roles, users or groups may deploy to production. Developers can still push code and see the pipeline, but the deploy job stays blocked for them unless they are on the list.

Premium and Ultimate add deployment approvals: a deployment to a protected environment waits until a set number of approvers (or approvals from specific groups) agree. This gives you the four-eyes principle for production without leaving GitLab. The approval is recorded in the deployment history, which also helps audits (see Compliance, Audit Events and Approvals).

Deploy freezes

Sometimes you do not want any deployments: during a holiday, a major sales event or an audit window. A deploy freeze is a time window, configured in Settings > CI/CD > Deploy freezes with a cron expression and a time zone. While it is active, GitLab sets the variable CI_DEPLOY_FREEZE in pipelines, and deploy jobs that check it can refuse to run:

YAML
deploy_production:
  script: ./scripts/deploy.sh production
  environment: production
  rules:
    - if: $CI_DEPLOY_FREEZE != null
      when: never
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual

The freeze is a convention enforced by your rules, so jobs that do not test the variable are not stopped. Always include the check in every job that deploys to a frozen environment.

Stand-in: a canary controller

The first example simulates a canary rollout. At each step it measures an error rate (fixed numbers, so the output is repeatable) and either promotes the canary or rolls back.

JS Canary promotion

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second example models the decision of a deploy job: is the person allowed, is a freeze active, and are enough approvals in?

JS May this deployment run?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which strategy keeps a complete second copy of the application and switches traffic between them?

    Blue-green runs two full environments. Switching traffic is instant, and so is switching back, at the price of double capacity.
  2. 2. A rollback in GitLab runs which job?

    Each deployment keeps its job. The Rollback button re-runs it, so the previous commit is deployed again.
  3. 3. Why can a rollback still fail to restore a working system?

    Rolling back code does not undo schema changes. Backward compatible migrations (expand and contract) keep the old version working.
  4. 4. What does a protected environment control?

    You choose the roles, users or groups allowed to deploy; other people can still see the pipeline but cannot run the deploy job.
  5. 5. How do deploy jobs notice a deploy freeze?

    GitLab only sets a variable during the window. Your job rules must check it, for example with when: never.

Summary

  • Choose a strategy by risk: recreate and rolling are simple, blue-green gives instant switching, canary limits the blast radius.
  • A staged rollout is a chain of manual jobs; the traffic split is done by your platform, not by GitLab.
  • Rollback re-runs an earlier deployment job; keep deploy jobs idempotent and migrations backward compatible.
  • Protected environments and deployment approvals control who may release; deploy freezes pause releases through CI_DEPLOY_FREEZE.

Next: Roles, Permissions and Protected Branches