Files

T

Tirsvad a26a491737 Use bare tokens: PAT_FOR_GITHUB replaces CREDENTIALS_FOR_GITHUB

The sync workflow reads secrets.PAT_FOR_GITHUB as clear text and
parse_github_token and parse_gitea_token only check that the value is not
empty. No secret is JSON any more; the wiki publisher follows. Update the
tests, the guides, the README, PP-001 UC candidate 2 and the wiki pages with
their Danish and Bahasa Malaysia translations.

Task: MIL-002#5

2026-10-10 10:42:04 +08:00

3.9 KiB

Raw Blame History

Workflow credentials

The sync workflow uses two secrets. Give each the least privilege that works, store it only as a Gitea secret, and rotate it when a person with access leaves.

Secret	Content	Used for
`TOKEN_FOR_GITEA`	The Gitea token, nothing else	Reading the repository (description, topics) and its push mirrors
`PAT_FOR_GITHUB`	The GitHub token, nothing else	Changing the description and topics of the GitHub mirror

Minimum permissions

These come from the Gitea and GitHub documentation and the API calls the workflow makes. They have not been confirmed with a minimal token on this instance yet; S05 should confirm them when the tokens are created.

Gitea token (a personal access token of a user, not a deploy key; deploy keys do not work for the REST API):

scope read:repository
the user must be allowed to read the repository's push mirrors, which Gitea limits to repository administrators

Calls made: GET /repos/{owner}/{repo} and GET /repos/{owner}/{repo}/push_mirrors.

GitHub token (fine-grained personal access token):

Resource owner: the owner of the mirror repository
Repository access: only the mirror repository
Repository permission: Administration: Read and write (no other permission)
Set an expiry date

Calls made: GET /repos/{owner}/{repo}, PATCH /repos/{owner}/{repo} (description) and PUT /repos/{owner}/{repo}/topics.

Format of PAT_FOR_GITHUB: only the token string (for example github_pat_...), as clear text. The workflow only checks that it is not empty; GitHub rejects a wrong value (HTTP 401).

What the workflow checks before it changes anything

The workflow runs a preflight and writes nothing to GitHub unless it passes:

Both secrets exist and have the expected shape.
Gitea accepts the token and the repository is visible with it.
At most one GitHub push mirror is configured. With none, the run ends successfully without syncing and the GitHub secret is not read.
GitHub accepts the token for the mirror repository and the token reports administration access to it.

On success the log says Preflight passed: Gitea and GitHub accepted the credentials. Failures start with a category such as [credentials] or [permissions]; see troubleshooting.md. No secret value is ever printed.

Wiki publishing secret

The workflow Publish wiki (this repository only) copies wiki/ to the Gitea wiki when a change to wiki/ is merged to main. It uses TOKEN_FOR_GITEA_WIKI when that secret exists and otherwise reuses TOKEN_FOR_GITEA.

Secret	Content	Used for
`TOKEN_FOR_GITEA_WIKI` (optional)	The Gitea token, nothing else	Writing the wiki pages of this repository

The token that is used needs scope write:repository, and its user needs write access to this repository. Gitea has no wiki-only scope.
TOKEN_FOR_GITEA is documented above with read:repository only. Reusing it for the wiki means raising its scope, which also gives the metadata sync write access. A separate TOKEN_FOR_GITEA_WIKI for a dedicated user keeps the sync token read-only. S05 decides which, and S03 stores the secret.
Calls made: GET /repos/{owner}/{repo}, GET /repos/{owner}/{repo}/wiki/pages, GET, POST and PATCH /repos/{owner}/{repo}/wiki/... and, for a page that no longer exists in wiki/, DELETE /repos/{owner}/{repo}/wiki/page/{name}.
The wiki must be enabled in the repository settings. The workflow refuses to run when it is not.
The wiki always equals wiki/: pages edited or added in the Gitea web UI are overwritten or removed on the next publish.

Rotating a token

Create the new token with the permissions above.
Replace the secret value in the repository or organization settings.
Run the workflow manually and wait for Preflight passed.
Revoke the old token.

3.9 KiB Raw Blame History