TirSystem/github-action
0
1
Fork 0
Code Issues 5 Pull Requests 1 Actions Packages Projects Releases 3 Wiki Activity

Generate the English wiki pages from README.md and guides/
Validate workflows / validate (pull_request) Successful in 13s
Details

Browse Source 
Add tools/build_wiki.py, which builds the five English wiki pages into
wiki/, rewrites links so they work inside the wiki and reports pages that
differ from their sources. Offline tests cover the conversion and assert
that the committed pages are current.

Task: MIL-005#3
This commit is contained in:
Tirsvad
2026-10-10 08:53:30 +08:00
parent bef58e75c7
commit 8d62ea0d56
7 changed files with 746 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
wiki/Capabilities.md
+81
View File
@@ -0,0 +1,81 @@
<!-- Generated from README.md by tools/build_wiki.py. Edit the source, not this page. -->
> This page is generated from [`README.md`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/README.md). Changes made here are overwritten the next time the wiki is published.
## Capabilities
Only the first row is implemented. The rest is planned and tracked in the [Project Plan](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/docs/project-plan.md), which also describes each use case.
| Capability | Status |
| --- | --- |
| Synchronize repository metadata (Gitea to GitHub mirror) | Implemented in `.gitea/scoped_workflows/`, with offline tests and a validation workflow |
| Configure and validate workflow credentials | Implemented for the sync workflow: preflight checks both tokens before any change ([guide](Credentials)) |
| Onboard a repository, manage runners, diagnose failures | Guides written ([onboarding](Onboarding), [troubleshooting](Troubleshooting)); scoped delivery to other repositories not yet verified; brief use cases open (MIL-002) |
| Shared quality checks | Planned (MIL-003) |
| Versioned release and publishing | Planned (MIL-004) |
### Sync GitHub metadata
Syncs the Gitea repository description and topics to the GitHub push mirror.
#### Cron
Daily at 03:17 UTC (`17 3 * * *`), plus every push to `main` and manual `workflow_dispatch`.
#### Workflow
```plantuml
@startuml
title Sync Gitea repository description and topics to GitHub
autonumber
actor "Push to main,\nmanual trigger, or schedule" as Trigger
participant "Gitea Actions\nsync-github-metadata" as Workflow
participant "Gitea REST API" as Gitea
participant "GitHub REST API" as GitHub
Trigger -> Workflow: Start workflow
activate Workflow
Workflow -> Workflow: Read and validate secrets
note right
TOKEN_FOR_GITEA
CREDENTIALS_FOR_GITHUB
end note
alt secret validation failed
Workflow --> Trigger: workflow failed
end
Workflow -> Gitea: GET /repos/{owner}/{repo}
Gitea --> Workflow: Description and topics
Workflow -> Gitea: GET /repos/{owner}/{repo}/push_mirrors
Gitea --> Workflow: Push mirror response
alt mirrors is not a list
Workflow --> Trigger: Log a warning and succeed\n(GitHub metadata not synced)
else mirrors is a list with no GitHub mirror
Workflow --> Trigger: Log that there is nothing to sync and succeed
else mirrors is a list
Workflow -> Workflow: Find GitHub owner and repo from remote_address
Workflow -> GitHub: PATCH /repos/{owner}/{repo}\n{description}
GitHub --> Workflow: Repository updated
Workflow -> GitHub: PUT /repos/{owner}/{repo}/topics\n{names}
GitHub --> Workflow: Topics updated
Workflow --> Trigger: Sync completed
else Gitea API denies access
Gitea --> Workflow: HTTP 403 Forbidden
Workflow --> Trigger: Workflow fails
else GitHub API denies access
GitHub --> Workflow: HTTP error
Workflow --> Trigger: Workflow fails
end
deactivate Workflow
@enduml
```
wiki/Credentials.md
+68
View File
@@ -0,0 +1,68 @@
<!-- 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.
# 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` | A bare token, a JSON string, or JSON with `GITEA_TOKEN` | Reading the repository (description, topics) and its push mirrors |
| `CREDENTIALS_FOR_GITHUB` | JSON object with a non-empty `GITHUB_PAT` | 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 `CREDENTIALS_FOR_GITHUB`:
```json
{"GITHUB_PAT": "<token>"}
```
## 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.
## 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.
wiki/Home.md
+56
View File
@@ -0,0 +1,56 @@
<!-- Generated from README.md by tools/build_wiki.py. Edit the source, not this page. -->
> This page is generated from [`README.md`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/README.md). Changes made here are overwritten the next time the wiki is published.
# TirSystem GitHub Actions
A collection of reusable Gitea Actions workflows for DevOps professionals and software engineers working on TirSystem projects.
## Overview
This repository is the central collection of reusable automation for TirSystem repositories. The primary repository lives at `git.tirsystem.com` (Gitea) and is push-mirrored to GitHub.
It currently contains the Gitea workflow [`sync-github-metadata.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/scoped_workflows/sync-github-metadata.yml), which copies the repository description and topics from Gitea to the GitHub mirror on every push to `main`, on manual dispatch, and daily at 03:17 UTC.
## Requirements
- A Gitea instance with Actions enabled and a runner providing `ubuntu-latest` with `python3`
- A configured GitHub push mirror on the Gitea repository (at most one; repositories without a mirror are skipped successfully)
- Repository secrets:
- `TOKEN_FOR_GITEA`: Gitea API token (plain string, or JSON with `GITEA_TOKEN`)
- `CREDENTIALS_FOR_GITHUB`: JSON object containing `GITHUB_PAT`, a GitHub personal access token allowed to edit the mirror repository
## Setup
No dependencies need to be installed; the workflow uses only the Python standard library.
1. Clone the repository:
```bash
git clone ssh://git@git.tirsystem.com:10022/TirSystem/github-action.git
```
2. Add the secrets listed under [Requirements](#requirements) to the repository settings in Gitea.
3. Configure the GitHub push mirror in the repository settings.
## Run
Workflows run automatically on push to `main` and on the daily schedule. To run manually, trigger **Sync GitHub mirror metadata** via `workflow_dispatch` from the Actions tab in Gitea.
## Tests
The workflow files and the Python embedded in them are validated by offline tests that need no network access and no secrets:
```bash
python3 -m venv .venv
source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -r tests/requirements.txt
python -m pytest -q tests
```
The same checks run on every pull request and push to `main` through [`validate-workflows.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/validate-workflows.yml). They parse every workflow as YAML, compile the embedded Python, require explicit job permissions, and test credential parsing, push mirror address parsing and the sync flow against a fake API.
After a change to the sync workflow, also trigger **Sync GitHub mirror metadata** manually in Gitea and compare the description and topics on the GitHub mirror.
wiki/Onboarding.md
+76
View File
@@ -0,0 +1,76 @@
<!-- Generated from guides/onboarding.md by tools/build_wiki.py. Edit the source, not this page. -->
> This page is generated from [`guides/onboarding.md`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/onboarding.md). Changes made here are overwritten the next time the wiki is published.
# 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](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/docs/project-plan.md)).
## 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
1. **Check the prerequisites** in the repository: Actions are enabled, and a
runner with the label `ubuntu-latest` and `python3` is online (see
[Runners](#runners)).
2. **Configure one GitHub push mirror** in the repository settings
(Settings, Repository, Mirror settings, Push mirror). The workflow fails
when there are several GitHub mirrors. With none, it succeeds without
syncing anything.
3. **Add the two secrets** in the repository (or organization) settings,
using the scopes in [credentials.md](Credentials):
- `TOKEN_FOR_GITEA`
- `CREDENTIALS_FOR_GITHUB` (JSON with `GITHUB_PAT`)
4. **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.
5. **Set a description and topics** on the Gitea repository, so there is
something to sync.
6. **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.
7. If it fails, use [troubleshooting.md](Troubleshooting).
## 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):
```bash
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 |
wiki/Troubleshooting.md
+68
View File
@@ -0,0 +1,68 @@
<!-- 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.
# 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 at most 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
`No GitHub push mirror configured for <repo>; nothing to sync.` 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.
## 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.