cicdgitlab ciPractitioner

Mastering Environments in GitLab CI/CD: Static vs. Dynamic

5 min read GitLab DocsSep 20, 2026Reviewed for accuracy

Practitioner — Hands-on experience recommended

Environments in GitLab CI/CD are essential for managing different stages of your application lifecycle. They allow you to deploy your application in various contexts, such as development, testing, staging, and production. By utilizing environments, you can streamline your deployment process and ensure that your code is tested in conditions that closely resemble production.

You can create static environments either through the GitLab UI or directly in your .gitlab-ci.yml file. For static environments, define a job in the deploy stage, specifying the environment name and URL. If the environment doesn’t exist when the pipeline runs, it will be created. For example, you might have a job like this:

chroma

1deploy_staging:
2  stage: deploy
3  script:
4    - echo "Deploy to staging server"
5  environment:
6    name: staging
7    url: https://staging.example.com

Dynamic environments, on the other hand, are typically created for review apps and are used for single deployments. They feature dynamic names based on CI/CD variables, making them flexible for testing branches or features. An example of a dynamic environment setup is:

chroma

1deploy_review_app:
2  stage: deploy
3  script:
4    make deploy
5  environment:
6    name: review/$CI_COMMIT_REF_SLUG
7    url: https://$CI_ENVIRONMENT_SLUG.example.com
8  rules:
9    - if: $CI_COMMIT_BRANCH == "main"
10      when: never
11    - if: $CI_COMMIT_BRANCH

In production, keep in mind that the state of an environment can be available, stopping, or stopped, depending on whether its stop job has run. Be cautious with dynamic environments; if the environment URL is invalid, it won’t update correctly. Also, remember that the stop_review job doesn’t generate a dotenv report artifact, which can lead to confusion if you try to reference environment variables that don’t exist in that context. Always ensure your scripts are accessible to the runners, especially when dealing with feature branches that may be deleted.

Key takeaways

→Create static environments by defining jobs in your `.gitlab-ci.yml` file with specific names and URLs.
→Utilize dynamic environments for review apps, leveraging CI/CD variables for naming.
→Be aware of environment states: available, stopping, and stopped, and how they affect your deployments.
→Ensure valid environment URLs to avoid issues with updates.
→Remember that `stop_review` jobs do not generate dotenv report artifacts.

Why it matters

Properly managing environments can significantly reduce deployment errors and streamline your CI/CD pipeline. This leads to faster feedback loops and more reliable releases.

Code examples

chroma

1deploy_staging:
2  stage: deploy
3  script:
4    - echo "Deploy to staging server"
5  environment:
6    name: staging
7    url: https://staging.example.com

chroma

1deploy_review_app:
2  stage: deploy
3  script:
4    make deploy
5  environment:
6    name: review/$CI_COMMIT_REF_SLUG
7    url: https://$CI_ENVIRONMENT_SLUG.example.com
8  rules:
9    - if: $CI_COMMIT_BRANCH == "main"
10      when: never
11    - if: $CI_COMMIT_BRANCH

chroma

1review:
2  script:
3    - DYNAMIC_ENVIRONMENT_URL=$(deploy-script)
4    - echo "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL" >> deploy.env
5  artifacts:
6    reports:
7      dotenv: deploy.env
8  environment:
9    name: review/$CI_COMMIT_REF_SLUG
10    url: $DYNAMIC_ENVIRONMENT_URL
11    on_stop: stop_review