CI and deployments
What a pipeline reports about a deployment, how it shows on the environment with the version now running, the statuses a deployment moves through, who is told when one fails or reaches production, and the GitHub deployments that arrive on their own.
By the end of this page every deployment your pipelines make will be on record: which version went into which environment, from which commit, how it went and how long it took. You will read the deployments on an environment's flyout, know the statuses a deployment moves through and where a record can come from, know who is told when a deployment fails or reaches production, and know how to let GitHub's own deployments report themselves. Setting the pipeline up is on the CI/CD ingestion page, with ready-made steps for GitHub Actions and GitLab CI.
A deployment is one version put into one environment. The record names the environment, and the component follows from it; carries the version, the commit and the branch it came from; says where the record came from and where the pipeline run can be read; and moves from queued through running to one of the final statuses. A deployment that succeeds tells its environment which version runs there and which deployment put it there, so an environment's Current Version is always the last success. Releases will name the deployments that ship them, promote through protected environments with an approval and roll back; until then the record is the pipeline's own account, kept where everyone can read it.
Before you begin
| To | You need |
|---|---|
| Read the deployments on an environment | deployment:view-any on the project; staff only, never a client guest. |
| Let a pipeline report | A token with ci:deploy, confined to the project; see CI/CD ingestion. |
| Record a deployment by hand or as an agent | deployment:record on the project. |
| Let GitHub deployments report themselves | The GitHub App installed for the team and the repository picked from it; see Integrations. |
Read the deployments on an environment
Open an environment's flyout on the Environments page and find Deployments, under the health and the freeze. The last five deployments into the environment are listed, the newest first, one line each:
| On the line | What it shows |
|---|---|
| Status badge | Queued, Running, Succeeded, Failed, Rolled back or Cancelled, coloured by outcome. |
| Version | What was deployed, as the pipeline names it, with the short commit beside it when one was reported. |
| Source and who | Pipeline, GitHub deployment, By hand or Rollback, then the person the record was written as when there was one. |
| When | How long ago it ended, or started, or was recorded. |
| Pipeline | A link to the pipeline run, when the pipeline sent one. |
The environment's Current Version above the list is what the last succeeded deployment left running, or what someone typed by hand before any deployment succeeded. An environment with no deployment yet says so in a line; the section is not shown to a client guest at all.
How a deployment moves
A deployment is recorded in one of the open statuses and finished, or recorded already final:
| Status | Meaning |
|---|---|
| Queued | Reported but not started: waiting for a runner, or for a hand. The environment is untouched. |
| Running | Under way; the pipeline will report how it ended. |
| Succeeded | Finished and live; the environment now carries the version and the deployment. |
| Failed | Ended in failure; the environment keeps what ran before. |
| Cancelled | Stopped before it finished, by a person or by the pipeline. |
| Rolled back | Undone by a later rollback, which the release module writes. |
A queued deployment moves to running or straight to an end; a running one moves to an end; a finished one is never moved again, so a late report changes nothing. The time from running to the end is kept as the duration. The full list, with colours, is in the status reference.
Where a record comes from
| Source | How the record was written |
|---|---|
| Pipeline | A pipeline reported it over the API under an ingestion token; the person the token belongs to is recorded as who. |
| GitHub deployment | GitHub reported it through the App's own deployment events, with no step in the pipeline; nobody is recorded as who. |
| By hand | A person recorded it over the API after a deployment done by hand. |
| Rollback | The release module's rollback wrote it; not yet in use. |
Report from a pipeline
A pipeline reports in one call after the fact, or in two as it goes: a first call that opens the
deployment as running when the job starts, and a second that finishes it as succeeded, failed or
cancelled when the job ends, whichever way it ended. The pipeline's run id is the idempotency key,
so a retried step records nothing twice. The token it uses carries ci:deploy and nothing else,
confined to the project, so a leaked pipeline credential can record deployments and read nothing.
The calls, the fields and the snippets are on CI/CD ingestion.
Let GitHub report for you
A workflow that uses GitHub's own deployments, through the Deployments API or an action that
creates one, needs no step at all: the App hears each deployment created and each status it is
given, and records them on the project of the repository the deployment belongs to. The
environment is matched by its name as GitHub spells it, the repository's own component first, then
one that serves the whole project; a name no environment carries records nothing, so name your
environments here the way your workflows name them. The version is the deployment's version
payload field when the workflow sets one, else the branch or tag deployed, else the short commit.
An inactive status, which GitHub writes when a newer deployment supersedes one, is not read.
Match the names, not the kinds
GitHub knows nothing of kinds. A deployment to an environment GitHub calls
production lands on the environment named Production here, whatever its
kind; name the environments the way the workflows do and the match is exact.
What happens next
- Every recorded deployment and every move is written to the deployment's activity history, as the token's owner, the person, or the application acting for GitHub.
- The
deployment.queued,deployment.started,deployment.succeeded,deployment.failedanddeployment.cancelledevents go out to every endpoint subscribed to them, with the version, the environment's name and kind and the timing; see thedeployment.*events. - A failed deployment, anywhere, tells the project manager and the lead developer under the Deployments alert class, through the channels each of them chose in their notification settings; a deployment that reached production, well or badly, tells the lead tester too.
- A succeeded deployment writes its version onto the environment and records itself as the environment's current deployment; nothing else on the environment changes.
- Releases will read the deployments to say which version shipped where; the readiness score and the rollback build on them.
Heimdall on this page
Heimdall reads the deployments and the environments through the same tools an agent uses, and records a deployment when you tell it one happened by hand.
From the API and MCP
Deployments API
List a project's deployments and an environment's recent ones, read one, record a deployment and finish it over REST.
CI/CD ingestion
The pipeline's view: the ingestion token, the two calls, the idempotency key and the snippets.
get_environment_status
An agent reads what runs on an environment, the deployment that put it there and the recent ones.
record_deployment and list_deployments
An agent records a deployment the way a pipeline does, and reads a project's deployments with their filters.
Permissions
| Action | Permission |
|---|---|
| Read the deployments | deployment:view-any; staff only |
| Read one deployment over the API | deployment:view; staff only |
| Record or finish a deployment | deployment:record, or ci:deploy on a pipeline token whose owner has it |
| Let GitHub deployments report | The repository picked from the team's installation; no permission per delivery |
Frequently asked
Related
- CI/CD ingestion: the token, the calls and the snippets.
- GitHub Actions: a composite action that reports as the job starts and ends.
- GitLab CI: the same from a GitLab pipeline, and from any other.
- Environments: where the deployments show, and the flags they will obey.
- Status reference: every status and source.
deployment.*webhook events
How is this guide?
Last updated on
Pull request flow
What the repository's webhook does to an item when a pull request naming it opens, turns into a draft, merges or closes: the moves the project's two switches allow, the statuses they start from, the kinds that finish on a merge, the gates that can refuse a move, and what is announced.
Documents
The documents a project generates from the record its team wrote once: the business requirements document the client signs and the software requirements specification the team builds against, each rendered, reviewed, approved and shared from one page.