How to Set Up Environments and Deployments in GitLab CI/CD

The environment keyword records each deploy against a named environment and surfaces its URL in the UI.

Add environment: with a name and url to a deploy job. GitLab logs the deployment, tracks the latest version, and links to the running app.

Steps

• Add environment:name to the deploy job.
• Set environment:url so the UI links to the live site.
• Use a per-branch name for parallel environments when needed.

Pipeline

deploy-staging:
  stage: deploy
  script: ./deploy.sh staging
  environment:
    name: staging
    url: https://staging.example.com
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

Gotchas

• A deployment is recorded only when the job runs, so a skipped job does not update the environment.
• Use environment:action: stop plus an on_stop job to tear down dynamic environments.

Related guides