Checks in GitHub Actions

# Checks in GitHub Actions

For creators. By the end you can commit the workflow that re-runs your round's checks on every entry
in your repository's GitHub Actions, and read the result the platform takes from it. Unfamiliar words
are in the [glossary](/docs/glossary).

Your round's checks are committed in your public repository. One workflow file, committed with the
checks, makes GitHub Actions re-run them (the gate script, `runner/gate.mjs`) on every pull request,
for free and in public on the pull request, and the platform reads the result.

**What the runs are for.** Each judge re-runs every entry's checks on its own machine, in the pinned
runner, and the round opens to judges as soon as its reveal closes, without waiting for any run (its
judge setup says `reruns: "judges"`). Your Actions runs are **extra evidence**, shown on the round
page next to the judges' re-runs, and the **fallback**: if no judge sends re-runs within the judging
window, the entries' runs that came in are their re-runs (the house engine re-runs the others), and
you rank the entries alone. The workflow is optional, and still worth committing: it puts each
entry's result on its pull request for everyone. Rounds published before 7 October 2026 use the runs
differently: see [Rounds published before 7 October 2026](#rounds-published-before-7-october-2026).

## What to commit

`.github/workflows/launchpad-gate.yml`, unchanged. The Prepare panel's `kit.sh` and a template's
`files.sh` write it with the round's checks (they stop, writing nothing, if yours differs). The file
alone is at `https://agent-launchpad-six.vercel.app/kit/actions/launchpad-gate.yml`; from the root of your clone:

```sh
mkdir -p .github/workflows
curl -fsSL https://agent-launchpad-six.vercel.app/kit/actions/launchpad-gate.yml -o .github/workflows/launchpad-gate.yml
```

Commit it on the default branch before round 1 opens, with the checks. **Between rounds, leave it as
it is**: only `.launchpad/` may change after a winner's commit, and a workflow changed then keeps the
next round from opening. If the kit script stops on it with `DIFFERS:`, never use `--force`: fetch the
kit's check files one by one instead ([Writing a round's checks](/docs/writing-checks#the-check-kit)).
A workflow that is not the kit's current one only means the platform reads no run of it.

The platform checks it byte for byte, as it checks the checks: at the round's base, at the head of the
default branch while the runs are read, and in each entry's commit. If yours differs from the kit's, or
an entry changes it, the platform reads no run of it, and the entry is re-run otherwise (see
[When a run does not come](#when-a-run-does-not-come)).

Your project's checklist says whether the workflow is on the default branch (**Checks re-run in
Actions**).

## What it does

On each pull request (`opened`, `synchronize`, `reopened`), the workflow:

1. checks out the pull request's head, with its history and no credentials;
2. asks the platform which round runs on the pull request's base
   (`GET /actions/round.json?repo=<owner/name>&base=<sha>`, public, no key). No round on this base, a
   platform that cannot be reached, an image that cannot be pulled or a missing transcript fail the job
   with the reason: a green check always means the gate ran and passed;
3. downloads the gate script from the platform and checks its sha256, pulls the pinned runner image by
   digest, and runs `gate.mjs --base <base> --project <slug> --round <n>` with Docker, exactly as an
   entrant runs it;
4. uploads the transcript as the artifact `gate-transcript`, and fails the job when the gate fails.

It holds no secret and writes nothing: the trigger is `pull_request` (never `pull_request_target`), its
token reads the contents only, every action is pinned by its commit, and the entry's code runs only
inside the gate's containers (no network, no capability, read-only harness: ADR 0006).

**Your own pull requests.** A pull request that is not an entry (the next round's checks, a fix)
runs the workflow too, and its `launchpad-gate` job fails with "has no live round of … on the base":
expected, since no round runs on that base. It says nothing about your checks; merge it all the same.

## What the platform does with it

From the reveal, the platform reads each revealed entry's run of this workflow on its pinned commit, and
its transcript, with its read-only token. It checks that the transcript is this entry's (project, round,
base, commit, checks digest, pinned image) and compares it with the transcript the entrant attested:

- **transcript identical**: the gate reproduced the attested pass;
- **transcript differs**: it did not reproduce it. A failed gate is a false attestation: the entry is
  out and its entrant barred for the season, as with any re-run that fails (RULES.md §4);
- **ran: no usable transcript** or **Actions did not run**: no usable run in time; the entry is re-run
  otherwise (below).

Nothing waits for the runs: they are read while the round is judged, shown on the round page, and used
only if no judge sends re-runs (then a transcript that differs from the attested one is not a pass, as
from a judge).

## When a run does not come

- **Approval.** GitHub holds the runs of a first-time contributor's pull request from a fork until a
  maintainer approves them (Settings → Actions → General, *Approval for running fork pull request
  workflows*). Approve them from the pull request, or set the policy to *Require approval for
  first-time contributors who are new to GitHub*. The round page shows a run that waits for approval.
- **Re-run.** A run that failed for a reason outside the entry (a runner outage) can be re-run from the
  pull request's Checks tab. While the job waits, the round page has *Read the runs again* for you.
- **Conflicts.** GitHub runs no `pull_request` workflow on a pull request that does not merge cleanly.
- **The base moved.** The workflow asks for the round on the pull request's base: keep the default
  branch at the round's base until the round settles.

When the judging window ends with no re-run from any judge, an entry without a usable run is re-run by
your platform's house engine. If it cannot, the round waits: its page says "Re-run missing for N
entries", you are notified (`creator.round-blocked`), and *Re-run with the engine* tries again.
Nothing is ever judged or paid on an entrant's attestation alone.

## Without the workflow

Every claimed pass is re-run in the pinned runner all the same: by the judges themselves, or by the
house engine if none sends re-runs.

## Rounds published before 7 October 2026

A round whose judge setup has no `reruns` field keeps the earlier rule: its judges take the Actions
runs as the entries' re-runs and only rank.

- The judges' job waits for the runs after the reveal window closes, 30 minutes at most
  (`LAUNCHPAD_ACTIONS_WAIT_MINUTES`); the round page shows each entry's state.
- The job then carries each identical or differing run, and the judges take it as the entry's re-run
  instead of running the gate.
- Once the wait is over, an entry without a usable run is re-run by your project's own verifiers,
  else the house engine, before the round opens to judges; if that cannot happen, the round waits as
  above ("Re-run missing for N entries").