- Configure manual deployments
- Track newly included merge requests per deployment
- Check out deployments locally
- Archive old deployments
- Deployment rollback
- Related topics
- Troubleshooting
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:
- Exposes the Run () 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 () 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
orstaging
.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.
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.
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, 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.