Operating the installed workflow

What to tell the user after the workflow is written, and the procedures for changing or undoing it later. Pull out the parts that apply to what they chose.

The token secret

The workflow reads a repository secret named TESSL_TOKEN and passes it to the Action as the tessl-token input. It authenticates the Tessl CLI. Without it the Action fails its input validation on the first run.

Create it from a Tessl API token:

gh secret set TESSL_TOKEN --repo <owner>/<repo>

An organization-level secret works too, as long as the repository is in its selected-repositories list.

The token is never placed in a command argument, a log line, an output, or an uploaded artifact.

The permissions, and why each one

permissions:
  contents: read
  checks: write
  issues: write
  pull-requests: write

Without checks: write the review still runs and is still published, a warning naming the missing permission is logged, and no check is reported. A gate has nothing to enforce in that state, so treat the permission as required rather than optional.

These apply to the automatic GITHUB_TOKEN, which the Action passes to the Tessl CLI for publication. Declaring the permissions block at all narrows the token to exactly this list, so do not widen it and do not remove it.

Branch protection, for gate mode

Enforce the gate with a required status check on the protected branch. The entry to require is Tessl Code Review, the check the Action reports against the head it reviewed.

Do not require the caller's job instead. A job status lands on the pull request only for a pull_request run, so requiring it leaves every comment-driven or dispatched round reporting nothing, and branch protection holds the pull request waiting for a status that will not arrive. The Action resolves the reviewed head itself, so its own check lands on that head whatever the trigger was, and the gate holds on all three cadences.

What the cadence still decides is when a fresh verdict arrives. On manual-only and ready-once, a head nobody has asked about carries no verdict yet, and the pull request waits until a requested round reviews it.

Do not enforce it through review-state protection instead. The Action's approval comes from GitHub Actions rather than a person, and a required-approvals rule that counts it is not the control anyone intends.

Approval additionally needs the repository or organization setting that allows GitHub Actions to create and approve pull requests (Settings, Actions, General, Workflow permissions). Without it GitHub refuses the review event. The review is not lost when that happens: it is published as a visible comment, the configuration problem is explained, and the gate fails.

What the check reports, once it is required

Four behaviors are worth stating before anyone relies on the check to hold a branch:

• The gate fails closed. A review that reaches no approval verdict fails the check rather than passing the head through. Only a verdict approves.
• A superseded run concludes neutral. If the head moves while the review is running, nothing is published for the head that was reviewed and nothing is asserted about the head that replaced it. The job fails so an unpublished review cannot read as a completed one, and the new head is reviewed by whatever run covers it.
• Neutral must not block. The conclusions above assume a neutral check does not hold a required status. Confirm that against the branch protection rule or ruleset the repository actually uses before requiring the check.
• A killed run leaves the check in progress. A job timeout or a lost runner ends the run before it can conclude its check, and a check stuck in progress holds every pull request that requires it. Re-run the workflow: a later check of the same name replaces the abandoned one.

Updating

Two things change over time, and they change independently.

The Action reference. A workflow on the major tag needs no update: the tag moves to each 1.x release, so a repository is on the newest one already. Nothing to do.

A workflow pinned to a commit SHA does need one. Resolve the target release with the lookup in the skill's proposal phase and replace the SHA on the uses: line. Keep it a full commit SHA rather than a branch name: a branch hands TESSL_TOKEN to whatever it currently points at, without the moving major tag's guarantee that what it points at is a release.

Either way the reference must name a release, never main: a pre-release revision does not carry the compatibility guarantees of a release.

The pin fixes the Action, not the Tessl CLI the Action installs. The Action installs the current CLI release on every run, so CLI changes reach a repository without any edit to its workflow.

The policy. Cadence is the on: block, the job if: guard, and cancel-in-progress. Blocking is the mode input. What the reviewer looks for is profile and lenses. Each is a small edit to the one caller workflow.

Re-running this skill against a repository that already has a caller performs an update: it keeps the runner, timeout, job name, extra steps, any input the interview does not decide, and any compatible triggers, and changes only the pinned SHA and whatever the interview decided. A re-run that finds nothing to change leaves the file untouched and says so.

This setup neither adds nor tunes an effort input; a repository that wants to tune how hard its lenses think sets effort in its profile instead. A caller that already carries the input keeps it.

Removing

1. Delete the caller workflow file.
2. Delete the TESSL_TOKEN repository secret if nothing else uses it.
3. If gate mode was enabled, remove the Tessl Code Review check from branch protection. A required check that nothing reports will block every pull request indefinitely, so do this before or with step 1.

Past reviews and comments stay on their pull requests. Nothing removes them.

When something is wrong