# Post a status on a commit

Let an external system report pass or fail on a commit, and make a pull request wait for it.

A deploy pipeline, a scanner or another CI reports on a commit the way GitHub's status API does.
`state` is `pending`, `success`, `failure` or `error`; `context` names the check (`default` when
left out), and a later status with the same `context` replaces the earlier one. `targetUrl`, when
given, must start with `https://`. The examples use the repository id
`5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60` and the commit `9fceb02d0ae598e95dc970b74767f19372d61af8`.

## Prerequisites

- Permission for `git:CreateCommitStatus`. Reading statuses needs `git:ListCommitStatuses`.
- The full 40-character id of a commit in the repository. For any other the API answers 404
  `No such commit in this repository`.

## Post it

**CLI**
```sh
dcloud git commit-statuses create 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
  9fceb02d0ae598e95dc970b74767f19372d61af8 --state success --context master-full \
  --description "Full suite passed" --target-url https://ci.example.com/run/42
```

**API**
```http
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/commits/9fceb02d0ae598e95dc970b74767f19372d61af8/statuses
{ "state": "success", "context": "master-full", "description": "Full suite passed", "targetUrl": "https://ci.example.com/run/42" }
```

## Result

Add the context to a branch protection rule's required checks, and a pull request waits for it:
pending waits, success passes, failure and error block. A pull request set to merge automatically
is checked again as soon as a status arrives. See [Protect a branch](protect-a-branch.md).

## From a tool built for GitHub

A tool built for GitHub can use GitHub's own call on the git host:
`POST https://git.<platform domain>/api/v3/repos/{org}/{repo}/statuses/{sha}` with `state`,
`context`, `description` and `target_url`, authenticated with a Deutsche Cloud git access token
(`Authorization: token …`). A `target_url` that is not `https://` is dropped rather than refused,
and a commit that is not in the repository answers 422 `No commit found for SHA: <sha>`. In a
workflow on a self-hosted runner of Deutsche Cloud CI, `GITHUB_API_URL` points at this host and the
job's `github.token` may write statuses on its own repository; see
[GitHub Actions](/docs/github-actions).

## Related

- `git.commit-statuses.create` · `dcloud git commit-statuses create`
