Deployments

DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

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:

Exposes the Run ({play}) button for the job in the GitLab UI, with the text Can be manually deployed to <environment>.
Means the deploy_prod job must be triggered manually.

You can find Run ({play}) in the pipelines, environments, deployments, and jobs views.

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 at a post-merge pipeline in merge request pages.

To enable tracking configure your environment so 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:

# 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. Since these Git-refs are populated from the remote GitLab repository, you could 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 with specifying the commit SHA (for example, git checkout <deployment-sha>), even after archive.

NOTE: GitLab preserves all commits as keep-around refs so that deployed commits are not garbage collected, even if it's not referenced by the deployment refs.

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.

Only the deployment jobs are run. 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:

On the left sidebar, select Search or go to and find your project.
Select Operate > Environments.
Select the environment.
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.

NOTE: If you have prevented outdated deployment jobs in your project, the rollback buttons might be hidden or disabled. In this case, see job retries for rollback deployments.

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, ask an administrator of your self-managed GitLab instance to execute the following command on Rails console:

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

GitLab might drop this support in the future for the performance concern. You can open an issue in GitLab Issue Tracker to discuss the behavior of this feature.