Tirsvad
a26a491737
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
93 lines
4.2 KiB
Markdown
93 lines
4.2 KiB
Markdown
<!-- Generated from guides/credentials.md by tools/build_wiki.py. Edit the source, not this page. -->
|
|
|
|
> This page is generated from [`guides/credentials.md`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/credentials.md). Changes made here are overwritten the next time the wiki is published.
|
|
|
|
English | [Dansk](Credentials.da) | [Bahasa Melayu](Credentials.ms)
|
|
|
|
# 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:
|
|
|
|
1. Both secrets exist and have the expected shape.
|
|
2. Gitea accepts the token and the repository is visible with it.
|
|
3. At most one GitHub push mirror is configured. With none, the run ends
|
|
successfully without syncing and the GitHub secret is not read.
|
|
4. 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](Troubleshooting). 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
|
|
|
|
1. Create the new token with the permissions above.
|
|
2. Replace the secret value in the repository or organization settings.
|
|
3. Run the workflow manually and wait for `Preflight passed`.
|
|
4. Revoke the old token.
|