GitHub PR Checks

UniTrack posts the quality-gate verdict back to GitHub so the result of a build shows up directly on the pull request. There are two levels, chosen by how you authenticate:

  • Personal access token (PAT) — UniTrack posts a commit status (a pass/fail dot with a one-line description).

  • GitHub App — UniTrack posts a richer check run: a markdown summary plus inline annotations on the PR’s changed lines (newly-uncovered coverage lines and new test failures). The Checks API requires App auth, so this is the App-only upgrade over the status. When an App is configured it replaces the commit status; otherwise the status is the fallback.

1. What gets posted

After each ingest that carries a commit and a repoUrl, GitHubStatusService publishes a status against that commit:

  • state — success or failure, from the quality-gate verdict;

  • description — a short summary including the coverage delta vs the baseline;

  • context — unitrack/quality-gate by default;

  • target URL — a deep link to the run page on your UniTrack server.

2. Configuration

Enable and configure under unitrack.github (see Configuration):

Property Meaning

enabled

Master switch for status publishing.

token

A GitHub token with repo:status (or fine-grained commit-status) scope.

api-url

GitHub API base; change for GitHub Enterprise.

server-base-url

Public URL of this UniTrack server, used to build the target link.

context

The status context label shown on the PR. Default unitrack/quality-gate.

 
unitrack:
  github:
    enabled: true
    token: ${GITHUB_TOKEN}
    server-base-url: https://unitrack.example.com

These are global defaults. enabled, the status context, and pr-comment can each be overridden per project from its Settings page — e.g. enable GitHub for one repo only, or use a different status context. The token always stays global and is never set per project.

3. Authenticating as a GitHub App

Configure a GitHub App to unlock check runs (below) and short-lived, per-repository tokens instead of a single long-lived PAT. Create an App with Checks: write, Commit statuses: write, Pull requests: write and Contents: read permissions, install it on your repos, and set:

Property Meaning

app.app-id

The App’s numeric ID (App settings page).

app.private-key

The App private key in PKCS#8 PEM. GitHub downloads PKCS#1 (BEGIN RSA PRIVATE KEY) — convert once with openssl pkcs8 -topk8 -nocrypt -in app.pem -out app.pk8.

app.installation-id

Optional. Pin the installation; otherwise UniTrack resolves it per repo.

 
unitrack:
  github:
    enabled: true
    server-base-url: https://unitrack.example.com
    app:
      app-id: 123456
      private-key: ${UNITRACK_GITHUB_APP_PRIVATE_KEY}   # PKCS#8 PEM

UniTrack signs a short-lived App JWT, exchanges it for an installation token, and caches that token until just before it expires. When the App isn’t configured it uses token (the PAT) and posts the plain commit status. A repo the App isn’t installed on is skipped, never failing the ingest.

4. Check runs with inline annotations

With an App configured, UniTrack posts a check run named after the status context. Its output carries a summary (gate verdict, coverage delta, new-failure count, a link to the run) and up to 50 annotations placed on the PR’s changed lines:

  • Uncovered coverage — a line the PR added or changed that no test covers is flagged warning: This line is not covered by tests. Coverage line numbers come from JaCoCo / Cobertura per-line data. Coverage reports carry only a package-relative path (org/ex/Foo.java), so to match it to the PR’s repo-relative file UniTrack uses the repo-relative path resolved at upload time from the uploader’s source manifest (see the uploader), falling back to suffix-matching the coverage path against the PR’s changed files.

  • New test failures — a failing test whose source file the PR changed is flagged failure at the assertion line parsed from its stack trace.

Only lines in the pull request’s diff are annotated, so the check surfaces exactly the problems the change introduced. Formats without per-line coverage (LCOV, OpenCover) still get the summary; only the coverage annotations are skipped.

5. Pull-request comment

In addition to the commit status, UniTrack posts (and updates in place) a results-table comment on the pull request associated with the run’s commit — the Codecov-style summary developers see without leaving the PR:

## UniTrack — ✅ gate passed

| Metric | Value |
|---|---|
| Tests | 128 passed · 0 failed · 2 skipped (130 total) |
| Coverage | 84.3% (+1.2pp) |
| Quality gate | PASSED |

It resolves the PR from the commit SHA, and uses a hidden marker to update its own comment on later pushes instead of posting duplicates. New failures and slower tests (regression / perf regression) are added as rows when present. Disable with unitrack.github.pr-comment=false while keeping the commit status. Requires the token to have pull-request write (issues/pull_requests) permission.

When a load-test upload carries a commit on an open PR, a separate perf comment (its own marker, upserted independently of the test report) is posted with the run’s p95 latency, throughput, error rate and samples, plus the perf-gate verdict per rule vs the baseline:

## UniTrack — load test — ❌ perf gate failed

| Metric | Value |
|---|---|
| p95 latency | 210 ms |
| Throughput | 120.5 rps |
| Error rate | 0.00% |
| Samples | 300 |

### Gate vs baseline #41

| Rule | Status | Detail |
|---|---|---|
| latency-p95 | ❌ | p95 210ms vs baseline 100ms (+110.0%, max +15.0%) |
| error-rate | ✅ | 0.00% errors (max 1.00%) |

6. Requirements

  • The upload must include both commit and repoUrl so UniTrack knows which commit on which repository to annotate. The upload script sets these from the standard GitHub Actions environment variables.

  • The configured token must have permission to write commit statuses on the target repo.

7. GitLab

The same exists for GitLab merge requests. Set unitrack.gitlab.enabled=true and a token with api scope (UNITRACK_GITLAB_TOKEN); for self-hosted GitLab override unitrack.gitlab.api-url. When a project’s repo URL is a GitLab one, UniTrack posts a commit status (success/failed) and, when the run carries an MR number, a results note on that merge request — mirroring the GitHub commit status + PR comment.