Tirsvad
aa88ea6f8b
TirSystem/github-action: Publish wiki / publish-wiki (push) Skipped
TirSystem/github-action: Sync GitHub mirror metadata / sync-metadata (push) Skipped
Validate workflows / validate (pull_request) Successful in 14s
Task: MIL-001#1
80 lines
5.0 KiB
Markdown
80 lines
5.0 KiB
Markdown
<!-- Generated from guides/troubleshooting.md by tools/build_wiki.py. Edit the source, not this page. -->
|
|
|
|
> This page is generated from [`guides/troubleshooting.md`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/troubleshooting.md). Changes made here are overwritten the next time the wiki is published.
|
|
|
|
English | [Dansk](Troubleshooting.da) | [Bahasa Melayu](Troubleshooting.ms)
|
|
|
|
# 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 |
|
|
| --- | --- | --- |
|
|
| `PAT_FOR_GITHUB is missing or empty.` | configuration | Add the secret |
|
|
| `TOKEN_FOR_GITEA is missing or empty.` | configuration | Add the secret |
|
|
| `Could not determine the Gitea source repository.` | configuration | The run has no repository name; report as a defect |
|
|
| `Expected at most one GitHub push mirror ... found N` | configuration | Keep one GitHub push mirror |
|
|
| `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Wiki publishing only: the repository opted in with `wiki/.publish` but its organization has no such secret; store it (see [credentials.md](Credentials)) |
|
|
| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Wiki publishing only: leave the marker empty, or put only the word `prune` in it |
|
|
| `... HTTP 403 ...` while publishing the wiki | permissions | Wiki publishing only: the token needs `write:repository` and write access to this repository |
|
|
| `The wiki is not enabled on <repo>` | configuration | Wiki publishing only: enable the wiki in the repository settings |
|
|
| `The wiki source directory ... has no Markdown pages` | configuration | Wiki publishing only: `wiki/` is empty or missing; nothing was changed |
|
|
| `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 `PAT_FOR_GITHUB`; the value must be the token only (no name, quotes or JSON) |
|
|
| `... 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
|
|
|
|
`No GitHub push mirror configured for <repo>; nothing to sync.` followed by
|
|
`Skipped`. The run succeeds. Not every Gitea repository has a GitHub mirror, so
|
|
this is expected for those. If the repository should have one, add it in the repository
|
|
settings.
|
|
|
|
`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.
|
|
|
|
`No wiki/.publish marker in <owner>/<repo>; wiki publishing is not enabled for
|
|
this repository.` The Publish wiki run succeeds and writes nothing. The
|
|
repository has not opted in; add `wiki/.publish` if it should publish.
|
|
|
|
`<n> page(s) are in the wiki but not in wiki/ and were kept; put the word
|
|
'prune' in wiki/.publish to delete them.` The run succeeds. Pages that exist
|
|
only in the wiki are left alone unless the marker contains `prune`.
|
|
|
|
## Runner problems
|
|
|
|
See the [Runners](Onboarding#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.
|