Troubleshooting

Everything below is a real message from redline, the gate, or the host. If you have a string, search it — ⌘K indexes the prose of every page and every rule id.

Start here: one command answers most of it

redline verify reads back what the host actually reports, not what a config file claims, and names every check that is wrong. Run it before reading further; the row it prints is the section you want.

$ npx redlinegate verify

Three different people act on those three answers, which is why they are three answers and not two.

The pull request says “Expected — waiting for status”, forever

The most common failure, and the most misleading: the branch rule requires a check name that nothing will ever report, so the pull request waits for a status that does not exist. It is not a slow gate. It will never resolve.

On GitHub the required context is built from two job ids — the caller job and the called job — so it is exactly redline-gate / gate, with the spaces. Rename either job and every pull request in the repository hangs.

redline verify catches this: it compares the required context against what the host reported on a real pull request. If you edited the gate yourself, see Adding a check of your own — renaming a job id is the first of the two traps there.

The gate is green, and I do not believe it

You are right to check. Two things produce a false green:

• A job that is not in the aggregate's needs:. It runs, it can go red, and the gate job never reads it — so it blocks nothing while looking like it does.
• A rung that is not what you think. At observe and warn the process checks report and never block. That is the default for a fresh repository and it is deliberate — see the enforcement ladder.

Do not reason about it — run the nine scenarios and watch the gate pass, block, and refuse to be waived.

partially onboarded, or a capability that says denied

This is the normal path, not a failure — onboarding covers why a run without admin rights still lands everything file-level. To clear it, have an administrator re-run with a token that has the rights:

$ npx redlinegate init --repair

--repair re-applies every capability and recomputes pendingAdmin from the fresh outcomes. It is not rm .redline.json: your recorded menu, rung and onboarding date survive it.

I applied redline-exempt and the gate still blocked

Two reasons, and they are different problems:

• The label on its own does nothing. It needs a ## Redline exemption block in the pull request body with a reason of at least 20 characters, an until date no more than 90 days out, and a scope. A label with no block is a label. See Exemptions.
• You exempted a security check. Dependency review and the secret scan are the security floor. They are not on the ladder and no label waives them at any rung — that is the one thing an exemption cannot do, on purpose.

An exemption downgrades the process checks — checklist, ADR, policy — for a reviewer who accepts the trade-off on the record. It does not delete the finding; it records who accepted it, why, and until when.

The checklist check fails and the boxes look ticked

The gate reads the checklist section of the pull request template by its heading. It fails loudly when the heading has been deleted — which is different from an unticked box, and is the failure people spend longest on because the body looks fine. Restore the heading from the template Redline installed, or from Templates & rulesets.

A rule is installed and never fires

Check the rule's own page first — /r/<rule-id>, or redline explain <rule-id> — for what it applies to:

• The globs. A rule scoped to **/*.ts will not fire in a .vue file, whatever the profile says.
• Added lines only. The deterministic tier judges what the change added. A pre-existing violation the diff merely moves past is not a finding — that is the noise rule, not a bug.
• A ticket reference silences some rules by design. core/untracked-todo and core/type-checker-suppression both pass when the line carries one.

If the rule genuinely cannot fire in your language — the checker knows no pattern your stack writes — that is a defect in Redline, not in your repository, and it is worth reporting. It has happened: the changelog has the case where a BLOCKER shipped to four languages it could not fire in.

A finding names a rule and gives me nothing to click

Set where your organisation publishes the standard, and every finding carries the address of the rule it cites:

$ npx redlinegate init --docs-url https://your-docs.example.com

It is recorded in .redline.json as docsBaseUrl and is empty by default. There is no default on purpose: a link to somebody else's copy of the standard is worse than no link, and an organisation running Redline internally wants findings pointing at its own.

Verify says the artifacts are stale and I did not touch them

The standard moved. standards/ is versioned, and a change there reaches every onboarded repository as a pull request — see Distribution & drift. Re-render locally with:

$ npx redlinegate init --no-commit

--no-commit writes the files into the working tree and stops: no host request, no branch, no pull request. It needs no credential and works offline, so it is the safe way to see what a re-render would do. Your own content above every REDLINE:BEGIN marker is never touched.

I want it off this repository

Close the onboarding pull request if it has not merged — nothing was changed. If it has, Removing Redline lists every file and host setting redline init created and how to take each one back out. Read the part about the security floor before you start: secret scanning and push protection are host settings that were probably worth having anyway.

Still stuck

redline status prints what this repository recorded, and redline verify --json gives the same checks in a form you can paste. Both are safe to share — neither includes a credential. Open an issue with the output rather than a description of it.