Report external checks

An external CI system or agent can report a check against a Change Request.

With the check runs API

Create a personal access token with checks:write and report against the commit you tested. The check belongs to that commit, so it shows on every Change Request version with that head commit, including ones opened later, and on pushes to any branch.

curl -X POST -H "Authorization: Bearer $UPSTREAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"build","head_sha":"'"$GIT_COMMIT"'","status":"in_progress"}' \
  https://api.upstream.codes/api/v3/repos/{owner}/{repository}/check-runs

Finish it with PATCH /api/v3/repos/{owner}/{repository}/check-runs/{id} and a conclusion. Commit statuses (POST statuses/{sha}) work the same way.

Pinning an exact version

To report against one Change Request version, use the native endpoint:

POST https://api.upstream.codes/v1/repos/{owner}/{repository}/changes/{number}/checks
Authorization: Bearer <token>
Content-Type: application/json

{
  "versionNumber": 3,
  "checkKey": "ci/build-and-test",
  "name": "Build and test",
  "status": "running",
  "summary": "Running 184 checks",
  "detailsUrl": "https://ci.example/runs/981"
}

Accepted statuses are pending, running, passed, failed, skipped and error. Send later states with the same check key; Upstream updates the same check so required-check gating and history stay consistent.

Include versionNumber when you can. Without it the check lands on the current version, which may have changed while your job ran.

Workspace keys

Workspace keys with the upstream.checks.write scope keep working with POST https://coline.app/api/v1/upstream/checks. New integrations should use a personal access token and the endpoints above.