Skip to content

Publish checks from any CI

Use POST /api/v1/ci/checks to publish a CodeCharter check run and PR comment on GitHub from any CI system.

Updated on 2026-06-10

The portal endpoint POST /api/v1/ci/checks publishes an analysis result as a branded CodeCharter check run — and optionally a sticky pull request comment — on a GitHub repository. The GitHub Action uses this endpoint internally, but it is a regular API-key-authenticated API: you can call it from Jenkins, TeamCity, Azure DevOps, GitLab, or a plain shell script just as well.

Two things to keep apart:

  • Where the code is built can be any CI system.
  • Where the check appears is always GitHub — the endpoint posts a check run to a GitHub repository through the CodeCharter app. If your repository is not hosted on GitHub, this endpoint has nothing to post to.

Prerequisites

  1. The CodeCharter GitHub App is installed on the GitHub account or organization that owns the repository, and the installation is linked to your portal account.
  2. A portal API key (generate one under API Keys; store it as a secret, see API keys in secrets).
  3. An active subscription on the account that owns the API key.

Request

POST https://codecharter.tools/api/v1/ci/checks
Authorization: Bearer <your API key>
Content-Type: application/json
Field Type Required Description
repository string yes Full repository name in owner/repo form.
headSha string yes Commit SHA the check run is reported against.
checkName string no Display name of the check run. Defaults to CodeCharter. Must not be empty if you set it.
conclusion string no success, failure, or neutral (default). Any other value is treated as neutral.
title string no Title of the check run output.
summary string no Markdown body, used both as the check summary and as the PR comment body.
annotations array no Inline annotations, see below.
pullNumber number no Pull request number for the comment. Omit on push builds.
comment boolean no true to post or update a sticky PR comment. Defaults to false; has no effect without a positive pullNumber.
commentKey string no Discriminator for the sticky comment, see below.

Each entry in annotations mirrors GitHub's check annotation shape:

Field Type Description
path string Repository-relative file path.
startLine number First line of the annotated range (1-based).
endLine number Last line of the annotated range (1-based).
level string failure, warning, or notice (default). Any other value is treated as notice.
title string Short title, typically the rule name.
message string Human-readable finding message.

Example

curl -X POST https://codecharter.tools/api/v1/ci/checks \
  -H "Authorization: Bearer $CODECHARTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "acme/acme-web",
    "headSha": "0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b",
    "pullNumber": 42,
    "conclusion": "failure",
    "title": "3 findings (1 error)",
    "summary": "## CodeCharter\n\n| Rule | Severity | Count |\n|---|---|---|\n| no-console-write | error | 1 |",
    "comment": true,
    "commentKey": "acme-web-main",
    "annotations": [
      {
        "path": "src/Web/Program.cs",
        "startLine": 12,
        "endLine": 12,
        "level": "failure",
        "title": "no-console-write",
        "message": "Console.WriteLine is not allowed in production code."
      }
    ]
  }'

Responses

Status Meaning
200 Published. Body: {"status":"published"}.
400 Validation failed: repository (in owner/repo form), headSha and checkName are required and must be non-empty.
401 Missing, invalid, or expired API key.
402 Your subscription is not active.
409 The CodeCharter GitHub App is not installed on the repository owner's account, or the installation is not linked to your portal account.
502 The portal could not publish the check to GitHub (relay failure). Retry later; if it persists, check the app installation on GitHub.

Error responses (400, 402, 409, 502) carry a problem-details JSON body whose detail field describes the cause.

Behavior

  • Check runs are upserted. If a check run with the same checkName already exists on the same commit, it is updated instead of duplicated. The published check run is always in the completed state.
  • At most 50 annotations are attached per publish; additional entries are dropped silently. Put the full finding list into summary if you need it.
  • The PR comment is sticky. When comment is true and pullNumber is set, the portal looks for an existing comment carrying a hidden marker derived from commentKey and updates it in place; otherwise it creates one. Calls with the same commentKey therefore keep updating one comment, while different keys maintain separate comments (useful when several jobs report into the same pull request). Omitting commentKey behaves like one shared default key.

See also