Tirsvad
de2e28e637
Validate workflows / validate (pull_request) Successful in 16s
Describe the wiki/.publish marker and the prune word, the per-organisation TOKEN_FOR_GITEA_WIKI without fallback, and the new messages in the onboarding, credentials and troubleshooting guides and the README. Add the capability row and regenerate the five English wiki pages with their Danish and Bahasa Malaysia translations. Task: MIL-006#5
95 lines
4.8 KiB
Markdown
95 lines
4.8 KiB
Markdown
# 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](../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 | Verified on 2026-10-10: it ran, with no copy in the repository, in repositories of `TirSystem`, `TirSystem-BashScript`, `vl-staal` and `Tirsvad-Udemy-100-days-of-code` (for example `TirSystem/sqa-qc-checklists` and `TirSystem-BashScript/RepoFoundry`). The script it ran changed when this repository's changed. |
|
|
|
|
Delivery is automatic, so a repository needs no copy of the workflow. Secrets are not shared between organisations: each organisation needs its own (step 3).
|
|
|
|
## 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.md). The workflow runs in
|
|
every repository of an organization, so store the secrets once per
|
|
organization; a repository in another organization does not see them:
|
|
- `TOKEN_FOR_GITEA`
|
|
- `PAT_FOR_GITHUB` (the GitHub token only)
|
|
4. **Deliver the workflow:** scoped workflows apply to every repository on
|
|
this instance, so there is nothing to copy. Only where scoped delivery is
|
|
not set up, 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 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.md).
|
|
|
|
## Publish a wiki (optional)
|
|
|
|
The **Publish wiki** workflow copies the Markdown pages in `wiki/` to the
|
|
repository wiki when a change to `wiki/` is merged to `main`. It is delivered
|
|
like the sync workflow, but it writes only where a repository opts in.
|
|
|
|
1. Enable the wiki in the repository settings.
|
|
2. Add Markdown pages to `wiki/`. The file name is the page name: `Home.md` is
|
|
the home page.
|
|
3. Add the marker `wiki/.publish`. Leave it empty to create and update pages
|
|
only. Put the single word `prune` in it to also delete wiki pages that are
|
|
not in `wiki/`, so the wiki always equals the folder.
|
|
4. Store `TOKEN_FOR_GITEA_WIKI` as a secret of the repository's organization,
|
|
using the scope in [credentials.md](credentials.md).
|
|
5. Merge the change to `main`. The log must end with `Published <n> page(s) to
|
|
the wiki of <owner>/<repo>`.
|
|
|
|
A repository without `wiki/.publish` is skipped with the line `No
|
|
wiki/.publish marker in <owner>/<repo>`: nothing is written and no secret is
|
|
needed.
|
|
|
|
## 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 |
|