GitLab CI "environment:" Deployment Errors - Invalid environment Config

environment: records a deployment to a named target. It fails when the name or URL is malformed, when an on_stop action points at a missing job, or when a dynamic name does not expand.

What this error means

Validation rejects the environment config, or a deploy job runs but the environment/deployment is wrong: a broken stop action, a dynamic name that resolved to a literal $VAR, or an invalid deployment_tier.

This GitLab CI configuration is invalid:
jobs:deploy:environment:on_stop 'stop_review' job is not defined

Common causes

on_stop names a missing job

environment:on_stop must reference a defined job (usually a manual stop_* job) that tears down the environment. A typo or missing stop job is invalid.

Dynamic name/URL does not expand

A review-app environment like review/$CI_COMMIT_REF_SLUG relies on variable expansion. If the variable is empty at that point, the name or URL is wrong.

Invalid deployment_tier or action

environment:deployment_tier must be one of the allowed values (production, staging, …), and environment:action must be a valid action (start, prepare, stop, verify, access).

How to fix it

Pair a deploy with a defined stop job

deploy_review:
  script: ./deploy.sh
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_COMMIT_REF_SLUG.review.example.com
    on_stop: stop_review

stop_review:
  script: ./teardown.sh
  when: manual
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop

Confirm the dynamic values resolve

1. Check $CI_COMMIT_REF_SLUG (or your chosen variable) is set for this pipeline source.
2. Use the same environment:name on both the start and stop jobs so they bind to one environment.
3. Set a valid deployment_tier if you rely on tier-based filtering.

How to prevent it

• Define a matching stop_* job whenever you set on_stop.
• Build dynamic environment names from variables that always exist for the source.
• Use only allowed deployment_tier and action values.

Related guides