TirsvadandClaude Sonnet 5.5
4de5438a88
Adopt the SQA/QC framework as a submodule and plan the project before any further code: Business Case, Stakeholder Analysis (S01-S05), Project Plan with use case candidates and prioritisation, and milestones MIL-001..MIL-004 (24 tasks, synced to Gitea as milestones 18-21 and issues #1-#24). README now separates implemented from planned capabilities, has an English sequence diagram and points at the scoped workflow. The workflow file moves out of the repository root and out of .gitea/workflows/; the scoped copy is unchanged in behaviour here and still contains the known `exit 0` syntax error, which MIL-001 fixes. Refs #1 Refs #2 Refs #3 Refs #6 Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
133 lines
4.7 KiB
Markdown
133 lines
4.7 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 (exactly one)
|
|
- 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
|
|
|
|
There are no automated tests yet (planned in MIL-001). `tests/test_.ps1` is a manual probe, not a test. Verify changes by running the workflow manually and checking the description and topics on the GitHub mirror.
|
|
|
|
## 🟢 Capabilities
|
|
|
|
Only the first row is implemented. 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/`; the script there currently has a syntax error (`exit 0`) that MIL-001 fixes |
|
|
| Configure and validate workflow credentials | Partial: secrets are checked for format only |
|
|
| Onboard a repository, manage runners, diagnose failures | Planned (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: Workflow fails\n"Gitea returned an invalid push mirror list."
|
|
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)
|