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.

Check suites

Check runs an installed app reports with its installation token belong to that app's check suite for the commit. A suite is queued until a run starts, in_progress while runs are open and completed when they have all finished.

Method	Path	Does
GET	/repos/{owner}/{repository}/commits/{ref}/check-suites	Lists the suites on a commit. Filter with app_id or check_name.
GET	/repos/{owner}/{repository}/check-suites/{id}	Gets one suite.
GET	/repos/{owner}/{repository}/check-suites/{id}/check-runs	Lists the suite's runs.
POST	/repos/{owner}/{repository}/check-suites/{id}/rerequest	Re-runs the suite.
POST	/repos/{owner}/{repository}/check-runs/{id}/rerequest	Re-runs one finished run.
POST	/repos/{owner}/{repository}/check-suites	Creates a suite for head_sha. Installation tokens only.

A re-run sets the suite back to queued and sends the app a check_suite or check_run event with the rerequested action. The app reports the runs again. Runs reported with a personal access token don't belong to a suite and can't be re-run. See Run CI from your app.

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.