Great question! Let’s break this down into practical, actionable steps to solve both parts of your problem—setting up branch-merge triggered cleanup (independent of prior CI stages) and properly leveraging environment:on_stop to avoid job expiration headaches.

1. Trigger Cleanup Automatically on Branch Merge (No Dependence on Prior CI Stages) #

You can create a standalone cleanup job that fires only when a branch is merged via a merge request using GitLab CI’s rules keyword. This job runs in a fresh, independent pipeline, so it won’t be affected by expired jobs from previous deployment pipelines.

Here’s a sample configuration:

cleanup_merged_branch_env:
  stage: cleanup
  script:
    - # Replace with your actual cleanup commands (e.g., delete cloud resources, purge DB entries)
    - echo "Cleaning up environment for merged branch: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"
    - ./scripts/cleanup-environment.sh $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
  rules:
    # Trigger automatically when a merge request is marked as merged
    - if: '$CI_MERGE_REQUEST_STATE == "merged"'
      when: always
  environment:
    name: review/$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
    action: stop

Key Details: #

• This job doesn’t rely on any prior stages or deployment jobs—it triggers as a separate pipeline the moment your merge request is finalized.
• Use $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME to target the exact environment tied to your merged feature branch.
• The environment: action: stop tag tells GitLab this job is responsible for terminating the environment, keeping your environment tracking organized.

2. Using environment:on_stop to Bypass Job Expiration #

The environment:on_stop config links your deployment job to a dedicated cleanup task, and crucially—this link is tied to the environment itself, not the original deployment pipeline. Even if your initial deployment pipeline expires, you can still trigger the cleanup job directly from GitLab’s Environments page, or set it to auto-run.

Here’s how to set it up correctly:

Step 1: Link Deployment to Cleanup Job #

deploy_review_env:
  stage: deploy
  script:
    - ./scripts/deploy-environment.sh $CI_COMMIT_BRANCH
  environment:
    name: review/$CI_COMMIT_BRANCH
    # Link this environment to the cleanup job below
    on_stop: cleanup_review_env
    # Optional: Auto-stop stale environments after X days (prevents resource waste)
    auto_stop_in: 7d
  rules:
    - if: '$CI_COMMIT_BRANCH != "main" && $CI_COMMIT_BRANCH != "master"'

Step 2: Define the Cleanup Job #

cleanup_review_env:
  stage: cleanup
  script:
    - ./scripts/cleanup-environment.sh $CI_COMMIT_BRANCH
  environment:
    name: review/$CI_COMMIT_BRANCH
    action: stop
  rules:
    # Auto-trigger on branch merge, plus allow manual trigger from Environments page
    - if: '$CI_MERGE_REQUEST_STATE == "merged"'
      when: always
    - if: '$CI_COMMIT_BRANCH != "main" && $CI_COMMIT_BRANCH != "master"'
      when: manual
      allow_failure: false

Why This Fixes Expiration Issues: #

• When you deploy the environment, GitLab creates a permanent association between the environment and the cleanup_review_env job.
• Even if the original deployment pipeline expires, you can still click the Stop button on the Environments page to trigger cleanup—GitLab will spin up a new pipeline just for this task.
• The auto_stop_in setting adds a safety net: it automatically triggers cleanup after the specified time, no manual intervention needed for abandoned branches.

Combined Workflow #

1. Push a feature branch, and the deploy_review_env job creates your dedicated environment.
2. Merge the branch via a merge request, and cleanup_merged_branch_env automatically runs to tear down the environment.
3. If the branch is abandoned, auto_stop_in triggers cleanup after 7 days.
4. At any time, you can manually trigger cleanup from the Environments page—even if the original deployment pipeline is long expired.

内容的提问来源于stack exchange，提问作者Michael Böckling