Create a check run

POST/repos/{owner}/{name}/check-runs

Runs are grouped per reporter and commit into a check suite. A check run is a check: a required check of its name is met by it, a cancelled one failing. Needs the Write role; publishes check_run.created, and check_run.completed when it is created completed.

Start a run as queued or in_progress and complete it later with update_check_run, or create it completed. app names who reports it; by default it is your token’s name, and a g1t Actions job’s G1T_TOKEN reports as g1t Actions. Each reporter’s runs on a commit form one check suite. The run also stands as a status of its name, so a required check lint is met by it: success, neutral and skipped pass, any other conclusion fails. See the Checks guide.

• Authentication: Required. Send an access token as Authorization: Bearer.
• MCP tool: workflow with action create_check_run, and the same inputs
• Scope: An access token needs checks:write.

Path parameters

Name	Type	Required	Description
owner	string	Yes	The workspace that owns the repository.
name	string	Yes	The repository’s name.

Body parameters

Send a JSON object. Names are snake_case, as in responses; the camelCase spelling is accepted too.

Name	Type	Required	Description
name	string	Yes	The check’s name, at most 100 characters, such as lint or coverage.
head_sha	string	Yes	The commit’s full SHA (or a branch or tag, read as the commit it points to now).
app	string	No	Who reports it, shown with it and grouping its check suite: by default your token’s name.
status	string	No	Where it is: queued, in_progress or completed. One of queued, in_progress, completed.
conclusion	string	No	How it came out; giving one completes it. One of success, failure, neutral, cancelled, skipped, timed_out, action_required.
started_at	string	No	When it started, RFC 3339.
completed_at	string	No	When it completed, RFC 3339.
details_url	string	No	Your page for it, http or https.
external_id	string	No	Your id for it.
output	object	No	Its report: a title, a Markdown summary and text, and annotations on lines of files (at most 50 a request).
output.title	string	No
output.summary	string	No
output.text	string	No
output.annotations	array of objects	No
output.annotations[].path	string	Yes
output.annotations[].start_line	integer	Yes
output.annotations[].end_line	integer	Yes
output.annotations[].start_column	integer	No
output.annotations[].end_column	integer	No
output.annotations[].annotation_level	string	Yes	One of notice, warning, failure.
output.annotations[].message	string	Yes
output.annotations[].title	string	No
output.annotations[].raw_details	string	No
actions	array of objects	No	Up to 3 buttons on its page. Pressing one sends you check_run.requested_action with its identifier.
actions[].label	string	Yes	At most 20 characters.
actions[].description	string	Yes	At most 40 characters.
actions[].identifier	string	Yes	At most 20 characters.

Example request

curl -X POST https://api.g1t.sh/repos/flagon-io/hello/check-runs \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lint",
    "head_sha": "9f3c2a1b7e6d5c4b3a2918f7e6d5c4b3a2918f7e",
    "status": "completed",
    "conclusion": "failure",
    "details_url": "https://ci.example.com/builds/4821",
    "external_id": "4821",
    "output": {
      "title": "2 problems",
      "summary": "**2** problems in 1 file.",
      "annotations": [
        {
          "path": "src/parse.rs",
          "start_line": 42,
          "end_line": 42,
          "annotation_level": "warning",
          "message": "unused variable: `depth`"
        }
      ]
    },
    "actions": [
      {
        "label": "Fix this",
        "description": "Apply the suggested fixes",
        "identifier": "fix"
      }
    ]
  }'

Example response

A successful request answers 200 with:

{
  "id": "cr_01kq4b7c8d9e0f1g2h3j4k5m6n",
  "name": "lint",
  "head_sha": "9f3c2a1b7e6d5c4b3a2918f7e6d5c4b3a2918f7e",
  "status": "completed",
  "conclusion": "failure",
  "started_at": "2026-10-07T14:02:11.000Z",
  "completed_at": "2026-10-07T14:02:36.000Z",
  "details_url": "https://ci.example.com/builds/4821",
  "external_id": "4821",
  "html_url": "https://g1t.sh/flagon-io/hello/checks/cr_01kq4b7c8d9e0f1g2h3j4k5m6n",
  "output": {
    "title": "2 problems",
    "summary": "**2** problems in 1 file.",
    "text": null,
    "annotations_count": 2
  },
  "actions": [
    {
      "label": "Fix this",
      "description": "Apply the suggested fixes",
      "identifier": "fix"
    }
  ],
  "check_suite": {
    "id": "cs_01kq4b7c8d9e0f1g2h3j4k5m6p"
  },
  "app": {
    "slug": "buildkite",
    "name": "Buildkite"
  },
  "created_at": "2026-10-07T14:02:11.318Z"
}

Errors

A failed request answers with one of these statuses and a body like {"error": {"code": "not_found", "message": "Repository not found."}}. See errors.

Status	Code	When
401	unauthenticated	A token is required, or the one sent is not valid.
403	forbidden	The token is valid but not allowed to do this, such as a member-only change or an agent token outside its repository.
404	not_found	It does not exist, or you cannot see it.
409	conflict	The request conflicts with the current state.
422	invalid	The input is not valid. message says which field and why.