Files

T

TirsvadandClaude Sonnet 5.5 7dcb9c4dfc Add credential preflight, categorized errors and operations guides

Sync workflow: every failure is now reported as `ERROR: [category] message`
with the categories configuration, credentials (HTTP 401), permissions
(HTTP 403) and api (other HTTP errors, unreachable service); HTTP 404 is a
configuration error. Before changing anything the workflow checks that the
GitHub token can administer the mirror repository and stops with a
permissions error otherwise. No secret value is printed.

Guides: onboarding (with runner labels, prerequisites and offline runner
symptoms), credentials (minimum permissions, preflight, rotation) and
troubleshooting (every message mapped to a category and a fix). README
capability table updated. MIL-002 records the verification of scoped
workflow support: Gitea 1.27.3 runs the workflow in this repository;
delivery to other repositories is not yet verified.

Task: MIL-002#2
Task: MIL-002#3
Task: MIL-002#4
Task: MIL-002#5
Task: MIL-002#6
Task: MIL-002#7
Refs #9
Refs #10
Refs #11
Refs #12
Refs #13
Refs #14

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

2026-10-03 21:26:49 +08:00

3.6 KiB

Raw Blame History

Diagnosing a failed run

Open the run in Gitea (Actions) and read the last lines of the failing step. Every failure from the sync script is written as

ERROR: [<category>] <message>

The category tells you where to look. A failure outside the script (the job never starts, or stops before the step) is a runner problem.

Category	Meaning	First thing to check
`configuration`	A secret or a repository setting is missing or malformed	Secret names and format, push mirror setup
`credentials`	A service rejected the token (HTTP 401)	Token expired, revoked or mistyped
`permissions`	The token is valid but not allowed (HTTP 403, or no GitHub administration access)	Token scopes and repository access
`api`	Another HTTP error, or the service was unreachable	Service status, runner network
runner	No `ERROR:` line; the run waits, or the job fails before the script	Runner online, label, tools

Messages and fixes

Message (start)	Category	Cause and fix
`CREDENTIALS_FOR_GITHUB is missing or empty.`	configuration	Add the secret
`CREDENTIALS_FOR_GITHUB must contain valid JSON.`	configuration	The value must be JSON such as `{"GITHUB_PAT": "..."}`
`CREDENTIALS_FOR_GITHUB must be a JSON object.`	configuration	Use an object, not a list or string
`CREDENTIALS_FOR_GITHUB must contain a non-empty GITHUB_PAT.`	configuration	Add the `GITHUB_PAT` key with a token
`TOKEN_FOR_GITEA is missing or empty.`	configuration	Add the secret
`TOKEN_FOR_GITEA must contain a non-empty GITEA_TOKEN.`	configuration	The JSON form needs a `GITEA_TOKEN` key
`Could not determine the Gitea source repository.`	configuration	The run has no repository name; report as a defect
`Expected exactly one GitHub push mirror ... found 0`	configuration	Add a GitHub push mirror in the repository settings
`Expected exactly one GitHub push mirror ... found N`	configuration	Keep one GitHub push mirror
`Could not determine the GitHub owner and repository ...`	configuration	The mirror address must look like `https://github.com/<owner>/<repo>.git`
`Gitea API request failed with HTTP 401`	credentials	Create a new Gitea token and update `TOKEN_FOR_GITEA`
`GitHub API request failed with HTTP 401`	credentials	Create a new GitHub token and update `CREDENTIALS_FOR_GITHUB`
`... HTTP 403 ...` (Gitea)	permissions	Token needs `read:repository`, and its user needs administrator access to the repository
`... HTTP 403 ...` (GitHub)	permissions	Token needs Administration read and write on the mirror repository
`The GitHub token cannot administer <repo>`	permissions	Same as above; the token can read the repository but not edit it
`... HTTP 404 ...`	configuration	Repository not found, or the token cannot see it; check the mirror address and token repository access
`... HTTP 5xx ...`	api	Service problem; re-run later
`... API is unreachable ...`	api	Network, DNS or proxy problem on the runner

Not an error

WARNING: Gitea returned an invalid push mirror list; GitHub metadata was not synced. The run succeeds but nothing was synced. Check that the Gitea version supports the push mirror API and re-run.

Runner problems

See the Runners section. In short: if the run stays waiting, no online runner has the label; if the job fails before the script, the runner image is missing a tool.

Re-running

Use Run workflow (workflow_dispatch) after fixing the cause. The sync is safe to repeat: it overwrites the GitHub description and topics with the Gitea values.

3.6 KiB Raw Blame History