Deployments

When you deploy a version of your code to an environment, you create a deployment. There is usually only one active deployment per environment.

GitLab:

• Provides a full history of deployments to each environment.
• Tracks your deployments, so you always know what is deployed on your servers.

If you have a deployment service like Kubernetes associated with your project, you can use it to assist with your deployments.

After a deployment is created, you can roll it out to users.

Configure manual deployments

You can create a job that requires someone to manually start the deployment. For example:

deploy_prod:
  stage: deploy
  script:
    - echo "Deploy to production server"
  environment:
    name: production
    url: https://example.com
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: manual

The when: manual action means the deploy_prod job does not run automatically. A user with permission to deploy must start it.

You can start a manual deployment from a merge request, an environment, or a pipeline:

Track newly included merge requests per deployment

GitLab can track newly included merge requests per deployment. When a deployment succeeds, the system calculates commit-diffs between the latest deployment and the previous deployment. You can fetch tracking information with the Deployment API or view it in the post-merge pipeline on the merge request page.

To enable tracking, configure your environment so that either:

• The environment name doesn’t use folders with / (long-lived or top-level environments).

• The environment tier is either production or staging.

  Here are some example configurations using the environment keyword in .gitlab-ci.yml:

  yaml

  # Trackable
  environment: production
  environment: production/aws
  environment: development
  
  # Non Trackable
  environment: review/$CI_COMMIT_REF_SLUG
  environment: testing/aws

Configuration changes apply only to new deployments. Existing deployment records do not have merge requests linked or unlinked from them.

Check out deployments locally

A reference in the Git repository is saved for each deployment, so knowing the state of your current environments is only a git fetch away.

In your Git configuration, append the [remote "<your-remote>"] block with an extra fetch line:

fetch = +refs/environments/*:refs/remotes/origin/environments/*

Archive old deployments

When a new deployment happens in your project, GitLab creates a special Git-ref to the deployment. Because these Git-refs are populated from the remote GitLab repository, you might find that some Git operations, such as git fetch and git pull, become slower as the number of deployments in your project increases.

To maintain the efficiency of your Git operations, GitLab keeps only recent deployment refs (up to 50,000) and deletes the rest of the old deployment refs. Archived deployments are still available, in the UI or by using the API, for auditing purposes. Also, you can still fetch the deployed commit from the repository by specifying the commit SHA (for example, git checkout <deployment-sha>), even after they’re archived.

Deployment rollback

When you roll back a deployment on a specific commit, a new deployment is created. This deployment has its own unique job ID. It points to the commit you’re rolling back to.

For the rollback to succeed, the deployment process must be defined in the job’s script.

GitLab runs only the deployment jobs. In cases where a previous job generates artifacts that must be regenerated on deploy, you must manually run the necessary jobs from the pipelines page. For example, if you use Terraform and your plan and apply commands are separated into multiple jobs, you must manually run the jobs to deploy or roll back.

Retry or roll back a deployment

If there is a problem with a deployment, you can retry it or roll it back.

To retry or roll back a deployment:

1. In the top bar, select Search or go to and find your project.
2. In the left sidebar, select Operate > Environments.
3. Select the environment.
4. To the right of the deployment name:
   • To retry a deployment, select Re-deploy to environment.
   • To roll back to a deployment, next to a previously successful deployment, select Rollback environment.

Related topics

• Environments
• Downstream pipelines for deployments
• Deploy to multiple environments with GitLab CI/CD (blog post)
• Review apps
• Track deployments of an external deployment tool

Troubleshooting

When you work with deployments, you might encounter the following issues.

Deployment refs are not found

GitLab deletes old deployment refs to keep your Git repository performant.

If you have to restore archived Git-refs on GitLab Self-Managed, ask an administrator to run the following command in the Rails console:

Project.find_by_full_path(<your-project-full-path>).deployments.where(archived: true).each(&:create_ref)