In a GitLab CI job, what does the `environment:` keyword do, and what do its `name` and `url` fields control?

## What the keyword is, and what it is not `environment:` is **job-level metadata** in `.gitlab-ci.yml`. Adding it does not make GitLab deploy anything, and removing it does not stop a deployment: the job's `script:` is what runs `kubectl`, `helm`, `scp`, `aws s3 sync` or whatever else. What the keyword changes is GitLab's *bookkeeping*. When a job carrying `environment:` starts, GitLab creates the named environment if it does not exist, and records a **deployment** — an entry tying that environment to the commit SHA, the pipeline, the job, the user who triggered it, and a status (running, success, failed). That record is the whole point. Everything GitLab offers around delivery is built on it: the Environments page listing what is currently live where, per-environment deployment history, the re-deploy and rollback buttons, the merge request widget showing that this branch is deployed, environment-scoped CI/CD variables, and protected environments. ```yaml deploy_staging: stage: deploy script: - ./deploy.sh staging environment: name: staging url: https://staging.example.com ``` ## `name` `name` is the identifier, and it is unique per project: two jobs using `name: staging` update the *same* environment, which is exactly what you want — the second deployment appends to the first one's history rather than creating a rival entry. The name may contain CI/CD variables, which is how dynamic environments work (`name: review/$CI_COMMIT_REF_SLUG`). A slash in the name has one extra meaning: GitLab groups environments whose names share a prefix before the slash into a **folder** in the UI. With hundreds of merge requests open, `review/add-login`, `review/fix-navbar` and friends appear as one collapsible `review` folder rather than hundreds of top-level rows. Inside the job, GitLab exposes `CI_ENVIRONMENT_NAME` (the name as written, after variable expansion) and `CI_ENVIRONMENT_SLUG` — a shortened, lowercased, DNS-safe version of the name that is safe to use as a hostname label or a Kubernetes namespace. ## `url` `url` is the address at which the deployed application can be reached. GitLab does not check it, ping it, or route to it; it renders it as a link. That link appears in three useful places: an "Open live environment" button on the environment, a link on the job page, and — for an environment attached to a merge request's branch — a "View app" button in the merge request widget, which is what makes review apps usable by a reviewer who has never opened a terminal. The value may be built from variables (`url: https://$CI_COMMIT_REF_SLUG.review.example.com`), and it is exposed to the job as `CI_ENVIRONMENT_URL`, so a smoke-test step can curl the thing it just deployed without repeating the hostname. When the URL is only known *after* the job runs — a platform that hands you a generated hostname — you can leave `url` out of the static config and have the script write the value into a `dotenv` report artifact, which GitLab reads back and attaches to the deployment. ## `action` `environment:action` says what this job does to the environment. The default is `start`, which is the recording behaviour described above. `stop` marks the environment stopped (see teardown of review apps). `prepare` attaches the job to the environment — making environment-scoped variables available — **without** recording a deployment, which is what you want for a plan or dry-run job that must read production credentials but is not deploying. `verify` and `access` are similar non-deploying variants used for verification and access-only jobs. ## Where teams get this wrong The most common mistake is simply never adding `environment:`, so deploys are invisible: GitLab's Environments page is empty, nobody can tell which commit is on staging, and there is no rollback button to press during an incident. The second is expecting the keyword to *perform* something — candidates sometimes claim `url` makes GitLab route traffic or health-check the app. It does neither. The third is giving each pipeline a unique environment name for a fixed environment (`staging-$CI_PIPELINE_ID`), which destroys the deployment history the feature exists to give you.