Working with Environments and Deployments

1. Defining Environments

Property	Description	Example
environment.name	Name of the environment	`staging`
environment.url	URL where the environment is accessible	`https://staging.example.com`
environment.auto_stop_in	Time after which environment is automatically stopped (e.g., `1h`, `2d`)	`1h`
environment.kubernetes.namespace	Kubernetes namespace to deploy to (if using Kubernetes)	`staging-ns`
environment.external_url	External URL for the environment (useful for environments not directly accessible via GitLab)	`https://myapp.example.com`

Example: Defining a staging environment in a job

deploy_staging:
  stage: deploy
  script:
    - echo "Deploying to staging"
  environment:
    name: staging
    url: https://staging.example.com
    auto_stop_in: 1h

2. Setting Environment URLs

Property	Value	Description
environment.url	`https://app.example.com`	URL of the deployed environment
environment.external_url	`https://staging.example.com`	External URL for the environment (optional)

Example: Setting Environment URL in CI/CD

deploy_staging:
  stage: deploy
  script:
    - echo "Deploying to staging environment"
  environment:
    name: staging
    url: https://staging.example.com

Note: The url field is required for environment deployment tracking.

3. Using Dynamic Environments

Property	Description	Example
environment.name	Name of the environment	`staging`
environment.url	URL where the environment is accessible	`https://staging.example.com`
environment.auto_stop_in	Time after which environment is automatically stopped	`1h`
environment.kubernetes.namespace	Kubernetes namespace to deploy to	`staging-namespace`

Example: Deploy to Dynamic Environment

deploy_staging:
  stage: deploy
  script:
    - echo "Deploying to staging environment"
  environment:
    name: "staging"
    url: "https://staging.example.com"
    auto_stop_in: "1h"

Note: Dynamic environments are automatically created when a job runs with an environment defined, and can be configured to auto-stop after a specified time.

4. Configuring Deployment Jobs

Property	Description	Values
environment	Name of the environment to deploy to	`production`, `staging`, `development`
environment.url	URL where the deployed application is accessible	`https://app.example.com`
environment.on_stop	Job to run when environment is stopped	`cleanup`
environment.action	Deployment action to perform	`start`, `stop`

Example: Basic Deployment Job Configuration

deploy:
  stage: deploy
  script:
    - echo "Deploying to production"
  environment:
    name: production
    url: https://app.example.com

Example: Environment with Stop Action

stop_production:
  stage: cleanup
  script:
    - echo "Stopping production environment"
  environment:
    name: production
    on_stop: cleanup_job

cleanup_job:
  stage: cleanup
  script:
    - echo "Cleaning up resources"

5. Using Environment Tiers

Tier	Description	Use Case	Examples
Development	Initial environment for development and testing	Continuous integration, feature branch deployments	`feature-branch-deployment`, `staging`
Staging	Pre-production environment mirroring production	Final testing before release to production	`staging-env`, `beta`
Production	Live environment where users interact with the application	Production deployments and monitoring	`prod`, `live`

Example: Environment Tier Configuration

deploy:
  stage: deploy
  environment:
    name: $CI_ENVIRONMENT_NAME
    tier: $CI_ENVIRONMENT_TIER
  script:
    - echo "Deploying to environment: $CI_ENVIRONMENT_NAME"

Note: Environment tiers help organize and manage deployments across different stages of the CI/CD pipeline.

6. Creating Review Apps

Review Apps in GitLab CI/CD automatically deploy your code to a temporary environment for each merge request or branch, allowing teams to preview changes before merging.

Property	Description	Default
review_app	Enables or disables the creation of review apps for a job.	`false`
environment.name	Name of the environment to deploy to.	Generated from branch name
environment.url	URL where the review app will be accessible.	Generated from environment name

Example: Enable Review App for a Job

deploy_review:
  stage: deploy
  script:
    - echo "Deploying to review app"
  environment:
    name: review/$CI_COMMIT_REF_NAME
    url: https://review.$CI_COMMIT_REF_NAME.example.com
  review_app: true

Note: Review apps are only created for jobs that run on branches or merge requests.

Warning: Ensure proper cleanup of review apps to avoid resource leaks.

Environment Variable	Description	Usage
CI_COMMIT_REF_NAME	Name of the branch or tag for which the job is running.	Used to generate environment name and URL
CI_ENVIRONMENT_NAME	Name of the environment being deployed to.	Used for logging or custom deployment logic
CI_ENVIRONMENT_URL	URL of the deployed environment.	Used to access the review app

7. Stopping Environments

Option	Values	Notes
environment.stop	`string`	URL to stop the environment
environment.auto_stop_in	`string`	Time after which environment is automatically stopped (e.g., `1d`, `2h`)

Example: Stopping an Environment

staging:
  environment:
    name: staging
    url: https://staging.example.com
    auto_stop_in: 1d
  script:
    - echo "Deploying to staging"

Note: Environments can be stopped manually via the GitLab UI or using the API endpoint /projects/:id/environments/:environment_id/stop.

8. Auto-Stopping Inactive Environments

GitLab CI/CD allows you to automatically stop environments that have been inactive for a specified period. This helps reduce costs and resource usage.

Setting	Description	Default Value	Notes
auto_stop_in	Duration after which an environment is automatically stopped	`1d`	Can be specified in days, hours, or minutes (e.g., `2h`, `30m`)
environment.stop	Environment name to stop when inactive	None	Must match the environment name defined in the `environment` block

Example: Configure auto-stop for an environment

deploy_staging:
  stage: deploy
  environment:
    name: staging
    auto_stop_in: 1d
  script:
    - echo "Deploying to staging"

Note: The auto_stop_in setting is only available for environments that are not protected. Protected environments must be manually stopped.

9. Protecting Environments

Property	Description	Default	Notes
environment.protect	Enables protection for the environment	`false`	When set to `true`, prevents deployments to the environment unless explicitly allowed
environment.unprotectable	Prevents the environment from being unprotected	`false`	Set to `true` to make the environment always protected

Example: Protecting an Environment

staging:
  environment:
    name: staging
    protect: true

Note: Protected environments can only be deployed to by users with the maintainer or owner role.

Warning: Once an environment is protected, it cannot be unprotected without manual intervention via the GitLab UI or API.

10. Tracking Deployments

Field	Description	Example
deployment_status	Status of the deployment (e.g., success, failed, running)	`success`
environment_name	Name of the environment being deployed to	`staging`
deployment_time	Timestamp of when the deployment occurred	`2025-04-01T12:30:00Z`
deployed_by	User or service that initiated the deployment	`john.doe@example.com`

Example: Deployment Tracking in GitLab CI

deploy_staging:
  stage: deploy
  script:
    - echo "Deploying to staging environment"
    - |
      curl --request POST "https://gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/deployments" \
           --header "PRIVATE-TOKEN: ${DEPLOY_TOKEN}" \
           --form "status=success" \
           --form "environment_name=staging" \
           --form "deployed_by=${GITLAB_USER_EMAIL}"