Tirsvad
d8dc35e88f
TirSystem/github-action: Publish wiki / publish-wiki (push) Skipped
TirSystem/github-action: Sync GitHub mirror metadata / sync-metadata (push) Skipped
Validate workflows / validate (pull_request) Successful in 16s
Task: MIL-005#3
148 lines
6.4 KiB
Markdown
148 lines
6.4 KiB
Markdown
# 🚀 TirSystem GitHub Actions
|
|
|
|
A collection of reusable Gitea Actions workflows for DevOps professionals and software engineers working on TirSystem projects.
|
|
|
|
## 📚 Table of Contents
|
|
|
|
- [Overview](#-overview)
|
|
- [Requirements](#-requirements)
|
|
- [Setup](#-setup)
|
|
- [Run](#-run)
|
|
- [Tests](#-tests)
|
|
- [License](#-license)
|
|
- [Links](#-links)
|
|
|
|
## 🧭 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`](.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 (the token only, no JSON)
|
|
- `PAT_FOR_GITHUB`: a GitHub personal access token allowed to edit the mirror repository (the token only, no JSON)
|
|
- `TOKEN_FOR_GITEA_WIKI` (only for repositories that publish a wiki, see the [onboarding guide](guides/onboarding.md)): a Gitea token that can write the wiki, stored as a secret of the repository's organization; there is no fallback to `TOKEN_FOR_GITEA`
|
|
|
|
## 🛠️ 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 scripts in `tools/` 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`](.gitea/workflows/validate-workflows.yml). They parse every workflow as YAML, check that none embeds Python, compile the scripts in `tools/`, require explicit job permissions, and test credential parsing, push mirror address parsing and the sync and publish flows 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.
|
|
|
|
## 🟢 Capabilities
|
|
|
|
Rows that say Implemented or Guides written exist today. The rest is planned and tracked in the [Project Plan](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](guides/credentials.md)) |
|
|
| Onboard a repository, manage runners, diagnose failures | Guides written ([onboarding](guides/onboarding.md), [troubleshooting](guides/troubleshooting.md)); scoped delivery to the repositories of all four organizations verified (MIL-002) |
|
|
| Publish a repository wiki from `wiki/` (opt-in, delivered to every organization) | Implemented in `.gitea/scoped_workflows/publish-wiki.yml`, with offline tests; a pilot in a second repository publishes its wiki (MIL-006) |
|
|
| Shared quality checks (Python and shell) | Implemented as the reusable workflow `.gitea/workflows/quality-checks.yml`, with offline tests and a trial in a second organization; adopted in RepoFoundry ([guide](guides/quality-checks.md)) |
|
|
| Versioned release and publishing | Release process, changelog and upgrade guide defined; the release workflow exists and `v1.0.0` is released (MIL-004) ([guide](guides/upgrading.md)) |
|
|
|
|
### 🔄 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
|
|
PAT_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
|
|
```
|
|
|
|
## 📄 License
|
|
|
|
Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See [LICENSE](LICENSE).
|
|
|
|
## 🔗 Links
|
|
|
|
- [Repository](https://git.tirsystem.com/TirSystem/github-action)
|
|
- [Documentation](https://git.tirsystem.com/TirSystem/github-action#readme)
|
|
- [Issue tracker](https://git.tirsystem.com/TirSystem/github-action/issues)
|