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.4 KiB

Raw Blame History

Onboarding a repository

How a DevOps professional makes a TirSystem repository use the shared Sync GitHub mirror metadata workflow, and which runners it needs. Only this workflow exists today; the quality-check and release workflows are planned (see the Project Plan).

What has been verified

Item	Status
Gitea version	1.27.3
`.gitea/scoped_workflows/sync-github-metadata.yml` runs in this repository	Verified: run 16, `workflow_dispatch`, succeeded
The same workflow applies to other repositories automatically	Not verified. Confirm how scoped workflows are delivered on the instance (admin or organization settings) before relying on it.

Until delivery is verified, onboard a repository by copying the workflow (below).

Steps

Check the prerequisites in the repository: Actions are enabled, and a runner with the label ubuntu-latest and python3 is online (see Runners).
Configure exactly one GitHub push mirror in the repository settings (Settings, Repository, Mirror settings, Push mirror). The workflow fails when there are zero or several GitHub mirrors.
Add the two secrets in the repository (or organization) settings, using the scopes in credentials.md:
- TOKEN_FOR_GITEA
- CREDENTIALS_FOR_GITHUB (JSON with GITHUB_PAT)
Deliver the workflow:
- If scoped workflows apply to the repository: nothing to copy.
- Otherwise: copy .gitea/scoped_workflows/sync-github-metadata.yml from this repository to .gitea/workflows/ in the target repository. Pin the copy to a reviewed version of this repository and re-copy when it changes.
Set a description and topics on the Gitea repository, so there is something to sync.
Run it once manually: Actions, Sync GitHub mirror metadata, Run workflow. The log must end with Synced description and topics to <owner>/<repo>. and the GitHub repository must show the same description and topics.
If it fails, use troubleshooting.md.

Runners

Item	Value
Label the workflow uses	`ubuntu-latest`
Labels offered by the runner on this instance	`ubuntu-latest`, `ubuntu-24.04`, `ubuntu-22.04`
Tools the workflow needs	`python3` (standard library only), outbound HTTPS to the Gitea API and `api.github.com`
Needed for `actions/checkout` (used by the validation workflow)	`git` and Node.js, normally in the runner image

Check that a suitable runner is online (needs permission to view runners):

curl -s -H "Authorization: token $GITEA_TOKEN" \
  https://git.tirsystem.com/api/v1/repos/<owner>/<repo>/actions/runners

For runners shared by the whole instance, an administrator uses /api/v1/admin/actions/runners. At the time of writing the repository and organization lists are empty and one instance-level runner (36cd20104923) is online.

Offline or incompatible runner

Symptom	Likely cause	Action
Run stays `waiting`	No online runner has the label in `runs-on`	Start the runner, or register one with the label
Job fails at the start with a missing command	Runner image lacks `python3`, `git` or Node.js	Use an image that has them
Job cannot reach the API	Runner has no outbound HTTPS	Fix runner network or proxy settings

3.4 KiB Raw Blame History

Onboarding a repository

What has been verified

Steps

Runners

3.4 KiB

Raw Blame History