Merge pull request 'MIL-008: publish the wiki through a reusable workflow; this wiki moves to docs/wiki' (#129) from wiki-in-docs-wiki into main
Publish accepted milestones / publish (push) Successful in 43s
Validate workflows / validate (push) Successful in 24s
TirSystem/github-action: Publish wiki / publish-wiki (push) Successful in 6s
TirSystem/github-action: Sync GitHub mirror metadata / sync-metadata (push) Successful in 6s
Publish wiki / publish-wiki (push) Successful in 18s
Publish own wiki / wiki (push) Successful in 18s
Publish accepted milestones / publish (push) Successful in 43s
Validate workflows / validate (push) Successful in 24s
TirSystem/github-action: Publish wiki / publish-wiki (push) Successful in 6s
TirSystem/github-action: Sync GitHub mirror metadata / sync-metadata (push) Successful in 6s
Publish wiki / publish-wiki (push) Successful in 18s
Publish own wiki / wiki (push) Successful in 18s
Reviewed-on: #129
This commit was merged in pull request #129.
This commit is contained in:
@@ -0,0 +1,93 @@
|
||||
# ADR-0009: Wiki publishing as a reusable workflow
|
||||
|
||||
## Metadata
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | ADR-0009 |
|
||||
| CrossReference | [MIL-008], [ADR-0003], [ADR-0004], [ADR-0005], [ADR-0006] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-13 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | [01b9c29] |
|
||||
|
||||
Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
[ADR-0004] chose a scoped workflow to publish wikis: Gitea runs it in every
|
||||
repository of an organisation, and a marker file `wiki/.publish` is the opt-in.
|
||||
That avoids a copy of the workflow, but it runs where nobody asked for it and
|
||||
needs a safety gate for that reason; its trigger path (`wiki/**`) and the
|
||||
version of the script (`v1`) are fixed centrally. The framework now prescribes
|
||||
the wiki in `docs/wiki/` with English and the PO language as a minimum, and
|
||||
repositories need to say where their wiki is.
|
||||
|
||||
Options:
|
||||
|
||||
1. **Keep the scoped workflow and read both folders.** No file in consumers,
|
||||
but the central trigger lists every location and the gate stays.
|
||||
2. **A reusable workflow (`workflow_call`) that each repository calls.** One
|
||||
source in this repository, called as `uses: ...@v1` the way
|
||||
`quality-checks` and `release` already are ([ADR-0005], [ADR-0006]). The
|
||||
caller sets its own trigger paths and the folder.
|
||||
|
||||
## Decision
|
||||
|
||||
Wiki publishing is the reusable workflow `publish-wiki-pages.yml`, called by
|
||||
each repository that wants a published wiki; the caller file is the opt-in and
|
||||
`docs/wiki/` is the default folder. The scoped `publish-wiki.yml` and the
|
||||
`wiki/.publish` marker are deprecated and stay until every publishing repository
|
||||
has a caller; they are then removed in a later major release.
|
||||
|
||||
The rules that follow from it:
|
||||
|
||||
- Inputs: `wiki_dir` (default `docs/wiki`), `prune` (default `false`) and
|
||||
`tools-ref` (default `v1`). The secret `TOKEN_FOR_GITEA_WIKI` is declared and
|
||||
passed by the caller; there is no fallback to another token.
|
||||
- With the reusable workflow the marker is not read: the script treats the
|
||||
`prune` input as the setting, and a missing folder is a configuration error
|
||||
rather than a skip, because the caller asked for it.
|
||||
- The script, the page-title rules, the empty-folder protection and the error
|
||||
categories of [ADR-0004] and [ADR-0003] are unchanged.
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive:**
|
||||
|
||||
- A repository states its own folder and trigger paths, so the wiki can move
|
||||
to `docs/wiki/` one repository at a time.
|
||||
- Opting in is a file in the repository, reviewed in a pull request, and a
|
||||
repository without a caller is never written to.
|
||||
- One call convention for every shared workflow of this repository.
|
||||
|
||||
**Negative:**
|
||||
|
||||
- Every publishing repository needs a caller file, and the removal of the
|
||||
scoped workflow stops publishing in any repository that still relies on the
|
||||
marker; the list of those repositories is taken before the removal.
|
||||
- Eight repositories still publish through the scoped workflow (checked on
|
||||
2026-10-13), so it is deprecated and not removed here; removing it is a
|
||||
breaking change under [ADR-0006] and belongs to a follow-up milestone with
|
||||
their migrations.
|
||||
- The owner chose a patch release (1.2.2) for this change although a new
|
||||
workflow is a minor one under [ADR-0006]; the changelog states the deviation.
|
||||
- Passing a declared secret through `workflow_call` is not yet verified on this
|
||||
Gitea instance; it is checked by the first call, in this repository.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- [MIL-008] — the plan this decision belongs to.
|
||||
- [ADR-0004] — its scoped delivery and marker parts are replaced once the
|
||||
scoped workflow is removed; its token and safety rules stand.
|
||||
|
||||
---
|
||||
|
||||
[MIL-008]: ../milestones/mil-008-wiki-reusable-workflow.md
|
||||
[ADR-0003]: ./adr-0003-wiki-publish-token.md
|
||||
[ADR-0004]: ./adr-0004-shared-wiki-publishing-opt-in.md
|
||||
[ADR-0006]: ./adr-0006-release-process-and-version-pinning.md
|
||||
[ADR-0005]: ./adr-0005-quality-check-contract.md
|
||||
[01b9c29]: https://git.tirsystem.com/TirSystem/github-action/commit/01b9c2972b4317bcc590540010aea0eaf7f30014
|
||||
@@ -10,10 +10,10 @@ each document lives in *this* project and the next version to use.
|
||||
| BC | Business Case | docs/business-case.md | 002 |
|
||||
| SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 |
|
||||
| PP | Project Plan | docs/project-plan.md | 002 |
|
||||
| MIL | Milestone / Gateway | docs/milestones/*.md | 008 |
|
||||
| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 060 |
|
||||
| MIL | Milestone / Gateway | docs/milestones/*.md | 009 |
|
||||
| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 062 |
|
||||
| TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
|
||||
| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0009 |
|
||||
| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0010 |
|
||||
| UCD | Use Case Diagram | docs/use-case-diagram.md | 002 |
|
||||
| US | User Story | docs/user-stories.md | 002 |
|
||||
| UC | Use Case | docs/uc-NNN/uc.md | 008 |
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
# MIL-008: Wiki publishing as a reusable workflow
|
||||
|
||||
## Metadata
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | MIL-008 |
|
||||
| CrossReference | [BC-001], [MIL-006], [ADR-0004], [RC-060], [RC-061] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-13 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version; reviewed (RC-060) | [01b9c29] |
|
||||
| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | S01 | Task 5 changed to deprecate the scoped workflow (8 repositories still use it); reviewed (RC-061) | [01b9c29] |
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
Decide whether the wiki can be published by a reusable workflow that each
|
||||
repository calls, from `docs/wiki/` (the location `process/wiki.md` of the
|
||||
framework prescribes), instead of a scoped workflow that runs in every
|
||||
repository of the organisation and reads `wiki/`.
|
||||
|
||||
## Deliverable
|
||||
|
||||
A reusable workflow `publish-wiki-pages.yml` in `.gitea/workflows/` with a
|
||||
`wiki_dir` input, a caller template for projects, offline tests, a superseding
|
||||
ADR, updated guides and wiki pages, this repository publishing its own wiki
|
||||
from `docs/wiki/` through it, the scoped workflow marked deprecated (not
|
||||
removed), and a release that projects can pin.
|
||||
|
||||
## Go / No-Go Criteria
|
||||
|
||||
| # | Criterion (objectively checkable) | Go | No-Go |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | The reusable workflow publishes the folder named by `wiki_dir` (default `docs/wiki`), and a repository that has no caller workflow is never written to | Offline tests pass; no caller means no run | Any write without a caller |
|
||||
| 2 | An empty or missing folder never deletes pages, the failure names its category, and the secret is passed explicitly (criteria 1 and 4 of MIL-006 still hold) | Existing tests pass unchanged | A regression |
|
||||
| 3 | This repository publishes its own wiki from `docs/wiki/` through a caller that uses the reusable workflow, and the pages on the host equal the folder | 0 differences read back through the API | Pages differ or the run fails |
|
||||
| 4 | A caller template exists for projects, with the trigger `docs/wiki/**` and the secret named | File exists and is linted (QC-WF-001) | Missing |
|
||||
| 5 | The scoped `publish-wiki.yml` is marked deprecated in its header, the README and ADR-0009, and the repositories that still use it are listed; it is not removed here | Notice present and the list recorded (8 repositories on 2026-10-13) | No notice, or the workflow was removed while a repository still depends on it |
|
||||
| 6 | The change is released as patch 1.2.2 and the moving major tag points at it | `v1` includes the change | Not released |
|
||||
|
||||
## Dependencies
|
||||
|
||||
| Depends on | Reason |
|
||||
| --- | --- |
|
||||
| MIL-006 | The publisher script, the prune rule and the safety limits come from it |
|
||||
| `TirSystem/sqa-qc-framework` `process/wiki.md` | Defines `docs/wiki/` and the English plus PO language minimum; unmerged when this was written |
|
||||
|
||||
## Traceability
|
||||
|
||||
| Business Case objective / KPI / user story | Reference |
|
||||
| --- | --- |
|
||||
| O2, O3 | [BC-001] |
|
||||
|
||||
## Ownership
|
||||
|
||||
| Role | Stakeholder ID (SA) |
|
||||
| --- | --- |
|
||||
| Owner | S05 |
|
||||
| Approving reviewer | S01 |
|
||||
|
||||
## Target Date
|
||||
|
||||
2026-11-15 — the Business Case sets no deadline.
|
||||
|
||||
## Tasks
|
||||
|
||||
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | Record the decision | An ADR that supersedes the scoped-delivery part of ADR-0004: publishing is a reusable workflow called by each repository; the caller file is the opt-in, so `wiki/.publish` is no longer a gate; the `prune` setting becomes an input. Keep the rest of ADR-0004 (secret handling) as it stands. | No | |
|
||||
| 2 | Add the reusable workflow | `.gitea/workflows/publish-wiki-pages.yml` with `on: workflow_call`, inputs `wiki_dir` (default `docs/wiki`) and `prune`, and the token as a declared secret. It runs `tools/publish_wiki.py` with `WIKI_DIR` and the prune setting from the inputs. Update the script and its tests: the marker is no longer required. | No | |
|
||||
| 3 | Add the caller template | A `publish-wiki.yml` caller for projects (`uses: TirSystem/github-action/.gitea/workflows/publish-wiki-pages.yml@v1`, `paths: docs/wiki/**`, `secrets:` mapped). Proposed in `sqa-qc-framework` under `templates/ci/` once this is released. | No | |
|
||||
| 4 | Move this repository's wiki and call the workflow | `git mv wiki docs/wiki`, check the links and the translation hash comments, add the caller, publish, read the pages back. | No | |
|
||||
| 5 | Deprecate the scoped workflow | Do not remove it: on 2026-10-13, 8 repositories still publish through it with `wiki/.publish` (`sqa-and-qc`, `sqa-qc-framework`, `sqa-qc-checklists`, `github-action`, `repo-foundry` and three of `Tirsvad-Udemy-100-days-of-code`), and none calls the reusable workflow yet. Add a deprecation notice to its header, the README table and ADR-0009, and record the list. The migrations and the removal are a follow-up milestone after this release (ADR-0006: a removed workflow is a new major). | No | |
|
||||
| 6 | Update guides and wiki pages | Describe the caller, `docs/wiki/` and the removed marker in the onboarding and credentials guides and in the English, Danish and Bahasa Malaysia pages (rule 8 of `AGENTS.md`). | No | |
|
||||
| 7 | Release | Release as a patch, 1.2.1 to 1.2.2, as the owner instructed: changelog entry and a release through the release workflow; the `v1` tag moves with it. ADR-0006 classes a new workflow as minor, so the changelog entry states the deviation and the reason. Nothing is removed, so no consumer breaks. | No | |
|
||||
|
||||
---
|
||||
|
||||
[BC-001]: ../business-case.md
|
||||
[MIL-006]: ./mil-006-shared-wiki-publishing.md
|
||||
[ADR-0004]: ../adr/adr-0004-shared-wiki-publishing-opt-in.md
|
||||
[RC-060]: ../sqa/reviews/rc-060-mil-008-plan.md
|
||||
[RC-061]: ../sqa/reviews/rc-061-mil-008-task-5-deferred.md
|
||||
[01b9c29]: https://git.tirsystem.com/TirSystem/github-action/commit/01b9c2972b4317bcc590540010aea0eaf7f30014
|
||||
@@ -0,0 +1,54 @@
|
||||
# Review Record: MIL-008
|
||||
|
||||
## Metadata
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | RC-060 |
|
||||
| CrossReference | [MIL-008], [QC-MIL-001] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | [01b9c29] |
|
||||
|
||||
---
|
||||
|
||||
## Artifact Under Review
|
||||
|
||||
- Instance reviewed: [MIL-008]
|
||||
- Checklist used: [QC-MIL-001]
|
||||
- Scope: full review
|
||||
- Language and domain: n/a (technical type)
|
||||
- Language reviewer: none
|
||||
- Mode: supervised (S01, the user, accepted the plan in chat on 2026-10-13; the AI prepared the record)
|
||||
|
||||
## Checklist Results
|
||||
|
||||
| # | Criterion | Status | Evidence/Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | A concrete deliverable is defined for every gate | Pass | The Deliverable section names the reusable workflow, the caller template, tests, the superseding ADR, the moved wiki and the release. |
|
||||
| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Six criteria, each with a checkable Go and No-Go (tests, a read-back with 0 differences, the `v1` tag). |
|
||||
| 3 | Dependencies on other milestones are explicitly mapped | Pass | MIL-006, and the framework's `process/wiki.md`, which is still unmerged and is named as such. |
|
||||
| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | O2 and O3 of [BC-001], as for MIL-006. |
|
||||
| 5 | Milestone owner and approving reviewer are identified | Pass | Owner S05, approving reviewer S01. |
|
||||
| 6 | Milestone has a defined target date consistent with project constraints | Pass | 2026-11-15; the Business Case sets no deadline and the plan's last decision is 2026-12-26. |
|
||||
|
||||
## Overall Verdict
|
||||
|
||||
Go - all six criteria pass. The release is a patch (1.2.1 to 1.2.2) by the owner's decision, although ADR-0006 classes a new workflow as minor and a removed one as breaking; task 7 records the deviation in the changelog, and S01 chose it over a minor release and over keeping the scoped workflow.
|
||||
|
||||
## Action Items
|
||||
|
||||
| Action | Owner | Due |
|
||||
| --- | --- | --- |
|
||||
| Add MIL-008 to the Project Plan (milestone table, CrossReference, dependency graph) and review it | S05 | before the pull request |
|
||||
| Merge `process/wiki.md` in `sqa-qc-framework` before this repository pins it | S05 | before task 3 ships |
|
||||
| List the repositories that publish through the scoped workflow before task 5 removes it | S05 | before task 5 |
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
[MIL-008]: ../../milestones/mil-008-wiki-reusable-workflow.md
|
||||
[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
|
||||
[01b9c29]: https://git.tirsystem.com/TirSystem/github-action/commit/01b9c2972b4317bcc590540010aea0eaf7f30014
|
||||
@@ -0,0 +1,54 @@
|
||||
# Review Record: MIL-008 (task 5 deferred)
|
||||
|
||||
## Metadata
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | RC-061 |
|
||||
| CrossReference | [MIL-008], [QC-MIL-001], [RC-060] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | [01b9c29] |
|
||||
|
||||
---
|
||||
|
||||
## Artifact Under Review
|
||||
|
||||
- Instance reviewed: [MIL-008] after the amendment of 2026-10-13: task 5 changed from removing the scoped workflow to deprecating it, with the criterion that follows from it
|
||||
- Checklist used: [QC-MIL-001]
|
||||
- Scope: delta re-review of the amended task 5, criterion 5 and the Deliverable; the earlier record is [RC-060]
|
||||
- Language and domain: n/a (technical type)
|
||||
- Language reviewer: none
|
||||
- Mode: supervised (S01, the user, chose option 1, defer the removal, in chat on 2026-10-13; the AI prepared the record)
|
||||
|
||||
## Checklist Results
|
||||
|
||||
| # | Criterion | Status | Evidence/Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | A concrete deliverable is defined for every gate | Pass | The Deliverable now says the scoped workflow is marked deprecated, not removed. |
|
||||
| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Criterion 5 is checkable: a notice in the header, the README and ADR-0009, and the list of repositories recorded; No-Go if it was removed while a repository depends on it. |
|
||||
| 3 | Dependencies on other milestones are explicitly mapped | Pass | Unchanged: MIL-006 and the framework's `process/wiki.md`. |
|
||||
| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | Unchanged: O2, O3. |
|
||||
| 5 | Milestone owner and approving reviewer are identified | Pass | Owner S05, approving reviewer S01. |
|
||||
| 6 | Milestone has a defined target date consistent with project constraints | Pass | 2026-11-15, unchanged. |
|
||||
|
||||
## Overall Verdict
|
||||
|
||||
Go - all six criteria pass. The amendment follows from a scan on 2026-10-13: 8 repositories still publish through the scoped workflow and none calls the reusable one, so removal would have broken them. Removal and the migrations move to a follow-up milestone that needs its own plan.
|
||||
|
||||
## Action Items
|
||||
|
||||
| Action | Owner | Due |
|
||||
| --- | --- | --- |
|
||||
| Plan the follow-up milestone: migrate the 8 repositories (move `wiki/` to `docs/wiki/`, add the caller from `templates/ci/publish-wiki.yml`), then remove the scoped workflow in a major release | S05 | after the 1.2.2 release |
|
||||
| Add MIL-008 to the Project Plan and review it (open since RC-060) | S05 | before the pull request |
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
[MIL-008]: ../../milestones/mil-008-wiki-reusable-workflow.md
|
||||
[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
|
||||
[RC-060]: ./rc-060-mil-008-plan.md
|
||||
[01b9c29]: https://git.tirsystem.com/TirSystem/github-action/commit/01b9c2972b4317bcc590540010aea0eaf7f30014
|
||||
@@ -4,13 +4,13 @@
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | TM-001 |
|
||||
| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [RC-001], [RC-002], [RC-003], [RC-004], [RC-005], [RC-006], [RC-007], [RC-008], [RC-009], [RC-010], [RC-011], [RC-012], [RC-013], [RC-014], [RC-015], [RC-016], [RC-017], [RC-018], [RC-019], [RC-020], [RC-021], [RC-022], [RC-023], [RC-024], [RC-025], [RC-026], [RC-027], [RC-028], [RC-029], [RC-030], [RC-031], [RC-032], [RC-033], [RC-034], [RC-035], [RC-036], [RC-037], [RC-038], [RC-039], [RC-040], [RC-041], [RC-042], [RC-043], [RC-044], [RC-045], [RC-046], [RC-047], [RC-048], [RC-049], [RC-050], [RC-051], [RC-052], [RC-053], [RC-054], [RC-055], [RC-056], [RC-057], [RC-058], [RC-059], [ADR-0007], [ADR-0008], [UC-007], [UC-006], [ADR-0006], [UC-005], [ADR-0005], [UCD-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [ADR-0001], [ADR-0002], [ADR-0003], [ADR-0004] |
|
||||
| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [RC-001], [RC-002], [RC-003], [RC-004], [RC-005], [RC-006], [RC-007], [RC-008], [RC-009], [RC-010], [RC-011], [RC-012], [RC-013], [RC-014], [RC-015], [RC-016], [RC-017], [RC-018], [RC-019], [RC-020], [RC-021], [RC-022], [RC-023], [RC-024], [RC-025], [RC-026], [RC-027], [RC-028], [RC-029], [RC-030], [RC-031], [RC-032], [RC-033], [RC-034], [RC-035], [RC-036], [RC-037], [RC-038], [RC-039], [RC-040], [RC-041], [RC-042], [RC-043], [RC-044], [RC-045], [RC-046], [RC-047], [RC-048], [RC-049], [RC-050], [RC-051], [RC-052], [RC-053], [RC-054], [RC-055], [RC-056], [RC-057], [RC-058], [RC-059], [RC-060], [ADR-0007], [ADR-0008], [UC-007], [UC-006], [ADR-0006], [UC-005], [ADR-0005], [UCD-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [ADR-0001], [ADR-0002], [ADR-0003], [ADR-0004] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-13 | Proposed | Jens Tirsvad Nielsen | S01 | Added RC-058 (MIL-006 task 6 amendment) | [8051cc4] |
|
||||
| 2026-10-13 | Proposed | Jens Tirsvad Nielsen | S01 | Added RC-059 (MIL-007 task 7 results) | [2481c26] |
|
||||
| 2026-10-13 | Proposed | Jens Tirsvad Nielsen | S01 | Added MIL-008, RC-060 and RC-061 | [01b9c29] |
|
||||
|
||||
---
|
||||
|
||||
@@ -40,6 +40,7 @@ updated whenever an artifact instance is created or reviewed.
|
||||
| [MIL-005] | MIL | [BC-001], [PP-001], [MIL-002] | [MIL-006] | [RC-010], [RC-011], [RC-030], [RC-050] |
|
||||
| [MIL-006] | MIL | [BC-001], [PP-001], [MIL-002], [MIL-005] | - | [RC-016], [RC-031], [RC-049], [RC-058] |
|
||||
| [MIL-007] | MIL | [BC-001], [PP-001], [MIL-003], [MIL-004], [ADR-0008] | - | [RC-052], [RC-055], [RC-059] |
|
||||
| [MIL-008] | MIL | [BC-001], [MIL-006], [ADR-0004] | - | [RC-060], [RC-061] |
|
||||
| [RC-007] | RC | [MIL-004] | - | - |
|
||||
| [RC-008] | RC | [BC-001] | - | - |
|
||||
| [RC-009] | RC | [PP-001] | - | - |
|
||||
@@ -110,6 +111,8 @@ updated whenever an artifact instance is created or reviewed.
|
||||
| [RC-057] | RC | [US-001] | - | - |
|
||||
| [RC-058] | RC | [MIL-006] | - | - |
|
||||
| [RC-059] | RC | [MIL-007] | - | - |
|
||||
| [RC-060] | RC | [MIL-008] | - | - |
|
||||
| [RC-061] | RC | [MIL-008] | - | - |
|
||||
|
||||
## Coverage Notes
|
||||
|
||||
@@ -130,6 +133,7 @@ updated whenever an artifact instance is created or reviewed.
|
||||
[MIL-005]: ../milestones/mil-005-wiki-and-translations.md
|
||||
[MIL-006]: ../milestones/mil-006-shared-wiki-publishing.md
|
||||
[MIL-007]: ../milestones/mil-007-cpp-csharp-quality-checks.md
|
||||
[MIL-008]: ../milestones/mil-008-wiki-reusable-workflow.md
|
||||
[RC-001]: ./reviews/rc-001-business-case.md
|
||||
[RC-002]: ./reviews/rc-002-project-plan.md
|
||||
[RC-003]: ./reviews/rc-003-mil-001.md
|
||||
@@ -199,6 +203,8 @@ updated whenever an artifact instance is created or reviewed.
|
||||
[RC-057]: ./reviews/rc-057-us-001-cpp-csharp.md
|
||||
[RC-058]: ./reviews/rc-058-mil-006-task-6.md
|
||||
[RC-059]: ./reviews/rc-059-mil-007-adoption.md
|
||||
[RC-060]: ./reviews/rc-060-mil-008-plan.md
|
||||
[RC-061]: ./reviews/rc-061-mil-008-task-5-deferred.md
|
||||
[ADR-0008]: ../adr/adr-0008-cpp-csharp-quality-check-contract.md
|
||||
[ADR-0007]: ../adr/adr-0007-release-publish-destination.md
|
||||
[UC-007]: ../uc-007/uc.md
|
||||
@@ -208,5 +214,5 @@ updated whenever an artifact instance is created or reviewed.
|
||||
[ADR-0005]: ../adr/adr-0005-quality-check-contract.md
|
||||
[faf13b2]: https://git.tirsystem.com/TirSystem/github-action/commit/faf13b2c2a4901c0171977de1ffc2841023f537a
|
||||
[1bc56f8]: https://git.tirsystem.com/TirSystem/github-action/commit/1bc56f8b771531f221f218fc00b147ecc73c051e
|
||||
[8051cc4]: https://git.tirsystem.com/TirSystem/github-action/commit/8051cc4489ee9bcf3b6c62f2eafcb2013b7d2f90
|
||||
[2481c26]: https://git.tirsystem.com/TirSystem/github-action/commit/2481c26d802464decd51d75539157093b60e08e8
|
||||
[01b9c29]: https://git.tirsystem.com/TirSystem/github-action/commit/01b9c2972b4317bcc590540010aea0eaf7f30014
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
<!-- translation of Capabilities.md, source sha256 c60d434988dc -->
|
||||
|
||||
> Dette er en oversættelse af [`Capabilities`](Capabilities). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
|
||||
|
||||
[English](Capabilities) | Dansk | [Bahasa Melayu](Capabilities.ms)
|
||||
|
||||
## Funktionalitet
|
||||
|
||||
Rækker, der siger Implementeret eller Vejledninger er skrevet, findes i dag. Resten er planlagt og følges i [projektplanen](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/docs/project-plan.md), som også beskriver hver enkelt use case.
|
||||
|
||||
| Funktionalitet | Status |
|
||||
| --- | --- |
|
||||
| Synkronisering af repositorymetadata (Gitea til GitHub-spejl) | Implementeret i `.gitea/scoped_workflows/`, med offline-tests og et valideringsworkflow |
|
||||
| Konfiguration og validering af workflow-credentials | Implementeret for synkroniseringsworkflowet: en forhåndskontrol tjekker begge tokens før enhver ændring ([vejledning](Credentials.da)) |
|
||||
| Tilslutning af et repository, administration af runners, fejlfinding | Vejledninger er skrevet ([tilslutning](Onboarding.da), [fejlfinding](Troubleshooting.da)); scoped levering til alle fire organisationers repositories er verificeret (MIL-002) |
|
||||
| Publicering af et repositorys wiki fra `wiki/` (tilmelding, leveres til alle organisationer) | Implementeret i `.gitea/scoped_workflows/publish-wiki.yml`, med offline-tests; et pilotforsøg i et andet repository publicerer sin wiki (MIL-006); afløses af det genbrugelige workflow nedenfor (ADR-0009) |
|
||||
| Publicering af et repositorys wiki fra `docs/wiki/` gennem et kaldt workflow | Implementeret som det genbrugelige workflow `.gitea/workflows/publish-wiki-pages.yml`, med offline-tests; dette repositorys egen wiki er i `docs/wiki/` og publiceres af det gennem `publish-own-wiki.yml`; endnu ikke kaldt fra et andet repository (MIL-008) |
|
||||
| Fælles kvalitetskontrol (Python og shell) | Implementeret som det genbrugelige workflow `.gitea/workflows/quality-checks.yml`, med offline-tests og et forsøg i en anden organisation; taget i brug i RepoFoundry ([vejledning](QualityChecksPythonShell.da)) |
|
||||
| Fælles kvalitetskontrol (C og C++, C#) | Implementeret som de genbrugelige workflows `.gitea/workflows/quality-checks-cpp.yml` og `.gitea/workflows/quality-checks-csharp.yml` med præcise værktøjsversioner og offline-tests; endnu ikke brugt i et andet repository (MIL-007) ([vejledning til C og C++](QualityChecksCpp.da), [vejledning til C#](QualityChecksCSharp.da)) |
|
||||
| Versioneret udgivelse og publicering | Udgivelsesproces, changelog og opgraderingsvejledning er defineret; udgivelsesworkflowet findes, og `v1.0.0` er udgivet (MIL-004) ([vejledning](Upgrading.da)) |
|
||||
@@ -0,0 +1,20 @@
|
||||
<!-- 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.
|
||||
|
||||
English | [Dansk](Capabilities.da) | [Bahasa Melayu](Capabilities.ms)
|
||||
|
||||
## Capabilities
|
||||
|
||||
Rows that say Implemented or Guides written exist today. 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 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); being replaced by the reusable workflow below (ADR-0009) |
|
||||
| Publish a repository wiki from `docs/wiki/` through a called workflow | Implemented as the reusable workflow `.gitea/workflows/publish-wiki-pages.yml`, with offline tests; this repository's own wiki is in `docs/wiki/` and published by it through `publish-own-wiki.yml`; not yet called from another repository (MIL-008) |
|
||||
| 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](QualityChecksPythonShell)) |
|
||||
| Shared quality checks (C and C++, C#) | Implemented as the reusable workflows `.gitea/workflows/quality-checks-cpp.yml` and `.gitea/workflows/quality-checks-csharp.yml` with exact tool versions and offline tests; not yet used in another repository (MIL-007) ([C and C++ guide](QualityChecksCpp), [C# guide](QualityChecksCSharp)) |
|
||||
| Versioned release and publishing | Release process, changelog and upgrade guide defined; the release workflow exists and `v1.0.0` is released (MIL-004) ([guide](Upgrading)) |
|
||||
@@ -0,0 +1,20 @@
|
||||
<!-- translation of Capabilities.md, source sha256 c60d434988dc -->
|
||||
|
||||
> Ini ialah terjemahan [`Capabilities`](Capabilities). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
|
||||
|
||||
[English](Capabilities) | [Dansk](Capabilities.da) | Bahasa Melayu
|
||||
|
||||
## Keupayaan
|
||||
|
||||
Baris yang menyatakan Dilaksanakan atau Panduan telah ditulis wujud hari ini. Selebihnya dirancang dan dijejaki dalam [Pelan Projek](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/docs/project-plan.md), yang juga menerangkan setiap kes guna (use case).
|
||||
|
||||
| Keupayaan | Status |
|
||||
| --- | --- |
|
||||
| Menyegerakkan metadata repositori (Gitea ke cermin GitHub) | Dilaksanakan dalam `.gitea/scoped_workflows/`, dengan ujian luar talian dan aliran kerja pengesahan |
|
||||
| Mengkonfigur dan mengesahkan kelayakan (credentials) aliran kerja | Dilaksanakan untuk aliran kerja penyegerakan: semakan awal (preflight) memeriksa kedua-dua token sebelum sebarang perubahan ([panduan](Credentials.ms)) |
|
||||
| Menyertakan repositori, mengurus runner, mendiagnosis kegagalan | Panduan telah ditulis ([menyertakan repositori](Onboarding.ms), [diagnosis](Troubleshooting.ms)); penghantaran scoped ke repositori keempat-empat organisasi telah disahkan (MIL-002) |
|
||||
| Menerbitkan wiki repositori daripada `wiki/` (pilih menyertai, dihantar ke setiap organisasi) | Dilaksanakan dalam `.gitea/scoped_workflows/publish-wiki.yml`, dengan ujian luar talian; satu juruterbang dalam repositori kedua menerbitkan wikinya (MIL-006); sedang diganti oleh aliran kerja boleh guna semula di bawah (ADR-0009) |
|
||||
| Menerbitkan wiki repositori daripada `docs/wiki/` melalui aliran kerja yang dipanggil | Dilaksanakan sebagai aliran kerja boleh guna semula `.gitea/workflows/publish-wiki-pages.yml`, dengan ujian luar talian; wiki repositori ini sendiri ada dalam `docs/wiki/` dan diterbitkan olehnya melalui `publish-own-wiki.yml`; belum dipanggil daripada repositori lain (MIL-008) |
|
||||
| Semakan kualiti bersama (Python dan shell) | Dilaksanakan sebagai aliran kerja boleh guna semula `.gitea/workflows/quality-checks.yml`, dengan ujian luar talian dan percubaan dalam organisasi kedua; digunakan dalam RepoFoundry ([panduan](QualityChecksPythonShell.ms)) |
|
||||
| Semakan kualiti bersama (C dan C++, C#) | Dilaksanakan sebagai aliran kerja boleh guna semula `.gitea/workflows/quality-checks-cpp.yml` dan `.gitea/workflows/quality-checks-csharp.yml` dengan versi alat yang tepat dan ujian luar talian; belum digunakan dalam repositori lain (MIL-007) ([panduan C dan C++](QualityChecksCpp.ms), [panduan C#](QualityChecksCSharp.ms)) |
|
||||
| Keluaran berversi dan penerbitan | Proses keluaran, changelog dan panduan naik taraf telah ditakrifkan; aliran kerja keluaran sudah ada dan `v1.0.0` telah dikeluarkan (MIL-004) ([panduan](Upgrading.ms)) |
|
||||
@@ -0,0 +1,76 @@
|
||||
<!-- translation of Credentials.md, source sha256 cba8a44e1152 -->
|
||||
|
||||
> Dette er en oversættelse af [`Credentials`](Credentials). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
|
||||
|
||||
[English](Credentials) | Dansk | [Bahasa Melayu](Credentials.ms)
|
||||
|
||||
# Workflow-credentials
|
||||
|
||||
Synkroniseringsworkflowet bruger to secrets. Giv hver af dem de mindste rettigheder, der virker, gem den kun som en Gitea-secret, og skift den, når en person med adgang forlader teamet.
|
||||
|
||||
| Secret | Indhold | Bruges til |
|
||||
| --- | --- | --- |
|
||||
| `TOKEN_FOR_GITEA` | Gitea-tokenet, intet andet | At læse repositoryet (beskrivelse, emner) og dets push-spejle |
|
||||
| `PAT_FOR_GITHUB` | GitHub-tokenet, intet andet | At ændre beskrivelse og emner på GitHub-spejlet |
|
||||
|
||||
## Mindste rettigheder
|
||||
|
||||
Disse blev kontrolleret den 2026-10-10 mod Gitea-kildekoden (rutedefinitionerne i `routers/api/v1/api.go`, `main`-grenen) og GitHub-siden "Permissions required for fine-grained personal access tokens" for hvert API-kald, workflows foretager. S01 godkendte dem som stedfortræder for S05 (ADR-0002) den 2026-10-10. De er **ikke afprøvet på denne instans med et token, der kun har disse rettigheder**; kontrollerne i slutningen af dette afsnit er måden at gøre det på.
|
||||
|
||||
**Gitea-token** (et personal access token for en bruger, ikke en deploy key; deploy keys virker ikke til REST API'et):
|
||||
|
||||
- scope `read:repository`: hver `/repos/...`-rute kræver repository-scopet, og kaldene nedenfor læser kun
|
||||
- brugeren skal være administrator af repositoryet: `push_mirrors`-rutene kræver repository-administration ud over token-scopet
|
||||
|
||||
Kald, der foretages: `GET /repos/{owner}/{repo}` og `GET /repos/{owner}/{repo}/push_mirrors`.
|
||||
|
||||
**GitHub-token** (fine-grained personal access token):
|
||||
|
||||
- Resource owner: ejeren af spejl-repositoryet
|
||||
- Repository access: kun spejl-repositoryet
|
||||
- Repository permission: **Administration: Read and write** (ingen andre tilladelser); den kræves til `PATCH /repos/{owner}/{repo}` og `PUT /repos/{owner}/{repo}/topics`. `Metadata: Read` tilføjes automatisk og dækker `GET /repos/{owner}/{repo}`.
|
||||
- Angiv en udløbsdato
|
||||
|
||||
Kald, der foretages: `GET /repos/{owner}/{repo}`, `PATCH /repos/{owner}/{repo}` (beskrivelse) og `PUT /repos/{owner}/{repo}/topics`.
|
||||
|
||||
**Gitea-token til wikien** (se "Secret til publicering af wiki" nedenfor): scope `write:repository`, fordi skrivning af en side (`POST`, `PATCH`, `DELETE` under `/repos/{owner}/{repo}/wiki`) kræver repository-scopet med skriveadgang, og brugeren skal have skriveadgang til repositoryets wiki. Oplistning og læsning af sider kræver kun læse-scopet.
|
||||
|
||||
**Afprøvning af rettighederne på instansen (valgfrit)**
|
||||
|
||||
1. I brugerens Gitea-indstillinger viser det token, der er gemt som `TOKEN_FOR_GITEA`, kun `read:repository`, brugeren er administrator af repositoryet, og en kørsel slutter stadig med `Preflight passed`.
|
||||
2. GitHub-tokenet viser kun spejl-repositoryet og `Administration: Read and write` (plus den automatiske `Metadata: Read`), og en kørsel slutter med `Preflight passed` og `Synced description and topics`.
|
||||
3. Et midlertidigt token, der mangler én af disse rettigheder, får kørslen til at fejle med `[permissions]` (eller HTTP 403 for Gitea) og navngive kategorien uden at udskrive tokenet.
|
||||
|
||||
Format for `PAT_FOR_GITHUB`: kun token-strengen (fx `github_pat_...`) som almindelig tekst. Workflowet tjekker kun, at den ikke er tom; GitHub afviser en forkert værdi (HTTP 401).
|
||||
|
||||
## Hvad workflowet kontrollerer, før det ændrer noget
|
||||
|
||||
Workflowet kører en forhåndskontrol (preflight) og skriver intet til GitHub, medmindre den består:
|
||||
|
||||
1. Begge secrets findes og har den forventede form.
|
||||
2. Gitea accepterer tokenet, og repositoryet er synligt med det.
|
||||
3. Højst ét GitHub push-spejl er konfigureret. Hvis der ingen er, slutter kørslen med succes uden at synkronisere, og GitHub-secreten bliver ikke læst.
|
||||
4. GitHub accepterer tokenet for spejl-repositoryet **og** tokenet melder, at det har administrationsadgang.
|
||||
|
||||
Ved succes står der i loggen `Preflight passed: Gitea and GitHub accepted the credentials.` Fejl begynder med en kategori som `[credentials]` eller `[permissions]`; se [troubleshooting.md](Troubleshooting.da). Ingen secret-værdi bliver nogensinde udskrevet.
|
||||
|
||||
## Secret til publicering af wiki
|
||||
|
||||
Workflowet **Publish wiki pages** kopierer `docs/wiki/` til Gitea-wikien i et repository, der kalder det (se [onboarding.md](Onboarding.da)). Det bruger sin egen secret, så synkroniseringstokenet forbliver skrivebeskyttet. Kalderen sender secreten i `secrets:`; den nedarves ikke.
|
||||
|
||||
| Secret | Indhold | Bruges til |
|
||||
| --- | --- | --- |
|
||||
| `TOKEN_FOR_GITEA_WIKI` | Gitea-tokenet, intet andet | At skrive wikisiderne for de repositories i en organisation, der melder sig til |
|
||||
|
||||
- Gem den som en secret i organisationen for hvert repository, der publicerer. Der er ingen reserve til `TOKEN_FOR_GITEA`: et repository, der kalder workflowet og ikke har secreten, fejler med en konfigurationsfejl, og et repository, der ikke kalder det, behøver den ikke.
|
||||
- Tokenet skal have scope `write:repository`, og dets bruger skal have skriveadgang til repositories. Gitea har intet scope kun til wikien, så opret tokenet til en dedikeret bruger. S05 godkender scopet, og S03 gemmer secreten.
|
||||
- Kald, der foretages: `GET /repos/{owner}/{repo}`, `GET /repos/{owner}/{repo}/wiki/pages`, `GET`, `POST` og `PATCH /repos/{owner}/{repo}/wiki/...` og, for en side, der ikke længere findes i `docs/wiki/`, `DELETE /repos/{owner}/{repo}/wiki/page/{name}`.
|
||||
- Wikien skal være aktiveret i repositoryets indstillinger. Workflowet nægter at køre, hvis den ikke er det.
|
||||
- Sider, der findes i `docs/wiki/`, overskrives altid fra den, så en ændring i Gitea's weboverflade går tabt ved næste publicering. Sider, der kun findes i wikien, fjernes kun, når kaldet sætter `prune: "true"`.
|
||||
|
||||
## Udskiftning af et token
|
||||
|
||||
1. Opret det nye token med de rettigheder, der er nævnt ovenfor.
|
||||
2. Erstat secret-værdien i repositoryets eller organisationens indstillinger.
|
||||
3. Kør workflowet manuelt, og vent på `Preflight passed`.
|
||||
4. Tilbagekald det gamle token.
|
||||
@@ -0,0 +1,121 @@
|
||||
<!-- 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 were checked on 2026-10-10 against the Gitea source (the route
|
||||
definitions in `routers/api/v1/api.go`, `main` branch) and the GitHub page
|
||||
"Permissions required for fine-grained personal access tokens", for every API
|
||||
call the workflows make. S01, standing in for S05 (ADR-0002), approved them on
|
||||
2026-10-10. They have **not been tested on this instance with a token that
|
||||
holds only these permissions**; the checks at the end of this section are the
|
||||
way to do that.
|
||||
|
||||
**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`: every `/repos/...` route needs the repository
|
||||
scope, and the calls below only read
|
||||
- the user must be an administrator of the repository: the `push_mirrors`
|
||||
routes require repository administration in addition to the token scope
|
||||
|
||||
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); it is needed for `PATCH /repos/{owner}/{repo}` and
|
||||
`PUT /repos/{owner}/{repo}/topics`. `Metadata: Read` is added automatically
|
||||
and covers `GET /repos/{owner}/{repo}`.
|
||||
- Set an expiry date
|
||||
|
||||
Calls made: `GET /repos/{owner}/{repo}`, `PATCH /repos/{owner}/{repo}` (description)
|
||||
and `PUT /repos/{owner}/{repo}/topics`.
|
||||
|
||||
**Gitea token for the wiki** (see "Wiki publishing secret" below): scope
|
||||
`write:repository`, because writing a page (`POST`, `PATCH`, `DELETE` under
|
||||
`/repos/{owner}/{repo}/wiki`) needs the repository scope with write access, and
|
||||
the user needs write access to the repository's wiki. Listing and reading
|
||||
pages needs only the read scope.
|
||||
|
||||
**Testing the permissions on the instance (optional)**
|
||||
|
||||
1. In the Gitea settings of the user, the token stored as `TOKEN_FOR_GITEA`
|
||||
lists only `read:repository`, the user is an administrator of the
|
||||
repository, and a run still ends with `Preflight passed`.
|
||||
2. The GitHub token lists only the mirror repository and
|
||||
`Administration: Read and write` (plus the automatic `Metadata: Read`), and
|
||||
a run ends with `Preflight passed` and `Synced description and topics`.
|
||||
3. A throwaway token that lacks one of these permissions makes the run fail
|
||||
with `[permissions]` (or HTTP 403 for Gitea) and names the category,
|
||||
without printing the token.
|
||||
|
||||
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 pages** copies `docs/wiki/` to the Gitea wiki of a
|
||||
repository that calls it (see [onboarding.md](Onboarding)). It uses its own
|
||||
secret, so the metadata sync token stays read-only. The caller passes the
|
||||
secret in `secrets:`; it is not inherited.
|
||||
|
||||
| Secret | Content | Used for |
|
||||
| --- | --- | --- |
|
||||
| `TOKEN_FOR_GITEA_WIKI` | The Gitea token, nothing else | Writing the wiki pages of the repositories of an organization that opt in |
|
||||
|
||||
- Store it as a secret of the organization of each repository that publishes.
|
||||
There is no fallback to `TOKEN_FOR_GITEA`: a repository that calls the
|
||||
workflow and has no such secret fails with a configuration error, and a
|
||||
repository that does not call it does not need it.
|
||||
- The token needs scope `write:repository`, and its user needs write access to
|
||||
the repositories. Gitea has no wiki-only scope, so create the token for a
|
||||
dedicated user. S05 approves the scope 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 `docs/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.
|
||||
- Pages that are in `docs/wiki/` are always overwritten from it, so a change
|
||||
made in the Gitea web UI is lost on the next publish. Pages that are only in
|
||||
the wiki are removed only when the call sets `prune: "true"`.
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,76 @@
|
||||
<!-- translation of Credentials.md, source sha256 cba8a44e1152 -->
|
||||
|
||||
> Ini ialah terjemahan [`Credentials`](Credentials). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
|
||||
|
||||
[English](Credentials) | [Dansk](Credentials.da) | Bahasa Melayu
|
||||
|
||||
# Kelayakan (credentials) aliran kerja
|
||||
|
||||
Aliran kerja penyegerakan menggunakan dua rahsia (secret). Beri setiap satu keistimewaan paling minimum yang berfungsi, simpan hanya sebagai secret Gitea, dan tukar apabila seseorang yang mempunyai akses meninggalkan pasukan.
|
||||
|
||||
| Secret | Kandungan | Digunakan untuk |
|
||||
| --- | --- | --- |
|
||||
| `TOKEN_FOR_GITEA` | Token Gitea, tiada yang lain | Membaca repositori (penerangan, topik) dan push mirror-nya |
|
||||
| `PAT_FOR_GITHUB` | Token GitHub, tiada yang lain | Mengubah penerangan dan topik cermin GitHub |
|
||||
|
||||
## Kebenaran minimum
|
||||
|
||||
Ini disemak pada 2026-10-10 terhadap kod sumber Gitea (definisi laluan dalam `routers/api/v1/api.go`, cabang `main`) dan halaman GitHub "Permissions required for fine-grained personal access tokens", bagi setiap panggilan API yang dibuat oleh aliran kerja. S01 meluluskannya sebagai pengganti S05 (ADR-0002) pada 2026-10-10. Ia **belum diuji pada instans ini dengan token yang hanya mempunyai kebenaran ini**; semakan di hujung bahagian ini ialah cara untuk melakukannya.
|
||||
|
||||
**Token Gitea** (personal access token seorang pengguna, bukan deploy key; deploy key tidak berfungsi untuk REST API):
|
||||
|
||||
- skop `read:repository`: setiap laluan `/repos/...` memerlukan skop repositori, dan panggilan di bawah hanya membaca
|
||||
- pengguna mesti pentadbir repositori: laluan `push_mirrors` memerlukan pentadbiran repositori selain skop token
|
||||
|
||||
Panggilan yang dibuat: `GET /repos/{owner}/{repo}` dan `GET /repos/{owner}/{repo}/push_mirrors`.
|
||||
|
||||
**Token GitHub** (fine-grained personal access token):
|
||||
|
||||
- Resource owner: pemilik repositori cermin
|
||||
- Repository access: hanya repositori cermin
|
||||
- Repository permission: **Administration: Read and write** (tiada kebenaran lain); ia diperlukan untuk `PATCH /repos/{owner}/{repo}` dan `PUT /repos/{owner}/{repo}/topics`. `Metadata: Read` ditambah secara automatik dan meliputi `GET /repos/{owner}/{repo}`.
|
||||
- Tetapkan tarikh tamat tempoh
|
||||
|
||||
Panggilan yang dibuat: `GET /repos/{owner}/{repo}`, `PATCH /repos/{owner}/{repo}` (penerangan) dan `PUT /repos/{owner}/{repo}/topics`.
|
||||
|
||||
**Token Gitea untuk wiki** (lihat "Secret untuk menerbitkan wiki" di bawah): skop `write:repository`, kerana menulis halaman (`POST`, `PATCH`, `DELETE` di bawah `/repos/{owner}/{repo}/wiki`) memerlukan skop repositori dengan akses tulis, dan pengguna mesti mempunyai akses tulis kepada wiki repositori. Menyenaraikan dan membaca halaman hanya memerlukan skop baca.
|
||||
|
||||
**Menguji kebenaran pada instans (pilihan)**
|
||||
|
||||
1. Dalam tetapan Gitea pengguna, token yang disimpan sebagai `TOKEN_FOR_GITEA` hanya menyenaraikan `read:repository`, pengguna ialah pentadbir repositori, dan larian masih berakhir dengan `Preflight passed`.
|
||||
2. Token GitHub hanya menyenaraikan repositori cermin dan `Administration: Read and write` (serta `Metadata: Read` automatik), dan larian berakhir dengan `Preflight passed` dan `Synced description and topics`.
|
||||
3. Token sementara yang tidak mempunyai salah satu kebenaran ini menyebabkan larian gagal dengan `[permissions]` (atau HTTP 403 bagi Gitea) dan menamakan kategori tanpa mencetak token.
|
||||
|
||||
Format `PAT_FOR_GITHUB`: hanya rentetan token (contohnya `github_pat_...`) sebagai teks biasa. Aliran kerja hanya menyemak bahawa ia tidak kosong; GitHub menolak nilai yang salah (HTTP 401).
|
||||
|
||||
## Perkara yang disemak oleh aliran kerja sebelum mengubah apa-apa
|
||||
|
||||
Aliran kerja menjalankan semakan awal (preflight) dan tidak menulis apa-apa ke GitHub melainkan ia lulus:
|
||||
|
||||
1. Kedua-dua secret wujud dan mempunyai bentuk yang dijangka.
|
||||
2. Gitea menerima token dan repositori kelihatan dengannya.
|
||||
3. Paling banyak satu push mirror GitHub dikonfigurasi. Jika tiada, larian berakhir dengan jayanya tanpa menyegerakkan dan secret GitHub tidak dibaca.
|
||||
4. GitHub menerima token untuk repositori cermin **dan** token melaporkan akses pentadbiran padanya.
|
||||
|
||||
Apabila berjaya, log menyatakan `Preflight passed: Gitea and GitHub accepted the credentials.` Kegagalan bermula dengan kategori seperti `[credentials]` atau `[permissions]`; lihat [troubleshooting.md](Troubleshooting.ms). Tiada nilai secret yang pernah dicetak.
|
||||
|
||||
## Secret untuk menerbitkan wiki
|
||||
|
||||
Aliran kerja **Publish wiki pages** menyalin `docs/wiki/` ke wiki Gitea bagi repositori yang memanggilnya (lihat [onboarding.md](Onboarding.ms)). Ia menggunakan secret sendiri, supaya token penyegerakan metadata kekal baca sahaja. Pemanggil menghantar secret dalam `secrets:`; ia tidak diwarisi.
|
||||
|
||||
| Secret | Kandungan | Digunakan untuk |
|
||||
| --- | --- | --- |
|
||||
| `TOKEN_FOR_GITEA_WIKI` | Token Gitea, tiada yang lain | Menulis halaman wiki bagi repositori dalam organisasi yang memilih menyertainya |
|
||||
|
||||
- Simpan sebagai secret organisasi bagi setiap repositori yang menerbitkan. Tiada sandaran kepada `TOKEN_FOR_GITEA`: repositori yang memanggil aliran kerja dan tidak mempunyai secret itu gagal dengan ralat konfigurasi, dan repositori yang tidak memanggilnya tidak memerlukannya.
|
||||
- Token mesti mempunyai skop `write:repository`, dan penggunanya mesti mempunyai akses tulis kepada repositori. Gitea tidak mempunyai skop untuk wiki sahaja, jadi cipta token untuk pengguna khusus. S05 meluluskan skop dan S03 menyimpan secret.
|
||||
- Panggilan yang dibuat: `GET /repos/{owner}/{repo}`, `GET /repos/{owner}/{repo}/wiki/pages`, `GET`, `POST` dan `PATCH /repos/{owner}/{repo}/wiki/...` dan, bagi halaman yang tidak lagi wujud dalam `docs/wiki/`, `DELETE /repos/{owner}/{repo}/wiki/page/{name}`.
|
||||
- Wiki mesti diaktifkan dalam tetapan repositori. Aliran kerja enggan berjalan jika ia tidak diaktifkan.
|
||||
- Halaman yang ada dalam `docs/wiki/` sentiasa ditimpa daripadanya, jadi perubahan yang dibuat dalam antara muka web Gitea hilang pada penerbitan seterusnya. Halaman yang hanya ada dalam wiki dibuang hanya apabila panggilan menetapkan `prune: "true"`.
|
||||
|
||||
## Menukar token
|
||||
|
||||
1. Cipta token baharu dengan kebenaran di atas.
|
||||
2. Gantikan nilai secret dalam tetapan repositori atau organisasi.
|
||||
3. Jalankan aliran kerja secara manual dan tunggu `Preflight passed`.
|
||||
4. Batalkan token lama.
|
||||
@@ -0,0 +1,535 @@
|
||||
<!-- translation of Home.md, source sha256 b6796554f4eb -->
|
||||
|
||||
> Dette er en oversættelse af [`Home`](Home). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
|
||||
|
||||
[English](Home) | Dansk | [Bahasa Melayu](Home.ms)
|
||||
|
||||
# TirSystem GitHub Actions
|
||||
|
||||
En samling af genbrugelige Gitea Actions-workflows til DevOps-professionelle og softwareudviklere, der arbejder på TirSystem-projekter.
|
||||
|
||||
|
||||
## Oversigt
|
||||
|
||||
Dette repository er den centrale samling af genbrugelig automatisering til TirSystems repositories. Det primære repository ligger på `git.tirsystem.com` (Gitea) og spejles med push til GitHub.
|
||||
|
||||
Det indeholder ti workflows: synkronisering af metadata til GitHub-spejlet, publicering af wiki (scoped og genbrugeligt for repositories, der kalder det), fælles kvalitetskontrol for Python og shell, for C og C++ og for C#, et udgivelsesworkflow, publicering af accepterede milepæle og repositoryets egen validering. De er listet med formål og diagram under [Workflows](#workflows).
|
||||
|
||||
|
||||
## Workflows
|
||||
|
||||
Der er ti workflows i dette repository. Et **scoped** workflow leveres af instansen til alle repositories i TirSystem-organisationerne og kræver intet i repositoryet; et **genbrugeligt** workflow kaldes fra et repository med `uses:`; de øvrige kører kun her. Diagrammerne er PlantUML-kildekode og er på engelsk.
|
||||
|
||||
| Workflow | Fil | Type | Starter ved | Formål |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Sync GitHub mirror metadata | [`sync-github-metadata.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/scoped_workflows/sync-github-metadata.yml) | Scoped | push til `main`, manuelt, dagligt kl. 03:17 UTC | Kopierer beskrivelsen og emnerne for et Gitea-repository til dets GitHub push-spejl |
|
||||
| Publish wiki | [`publish-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/scoped_workflows/publish-wiki.yml) | Scoped, tilmelding med `wiki/.publish`; forældet, afløses af det genbrugelige workflow nedenfor (ADR-0009) | push til `main`, der ændrer `wiki/**`, manuelt | Publicerer siderne i `wiki/` til repositoryets wiki |
|
||||
| Publish wiki pages | [`publish-wiki-pages.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/publish-wiki-pages.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Publicerer siderne i `docs/wiki/` (eller den mappe, `wiki_dir` angiver) til wikien i det kaldende repository |
|
||||
| Quality checks | [`quality-checks.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Kører ruff, mypy, shellcheck og shfmt på de sporede filer og ændrer intet |
|
||||
| Quality checks C++ | [`quality-checks-cpp.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks-cpp.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Kører clang-format og clang-tidy i præcise versioner på de sporede C- og C++-filer og ændrer intet |
|
||||
| Quality checks C# | [`quality-checks-csharp.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks-csharp.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Kører `dotnet format` og `dotnet build` på et præcist .NET SDK 10 eller nyere og ændrer intet |
|
||||
| Publish own wiki | [`publish-own-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/publish-own-wiki.yml) | Kun dette repository | push til `main`, der ændrer `docs/wiki/**`, manuelt | Kalder det genbrugelige workflow Publish wiki pages for dette repositorys wiki |
|
||||
| Release | [`release.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/release.yml) | Kun dette repository | manuelt | Opretter versionstagget, udgivelsessiden og major-tagget efter kontrollerne |
|
||||
| Publicering af accepterede milepæle | [`sync-milestones.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/sync-milestones.yml) | Kun dette repository | push til `main`, der ændrer `docs/milestones/**` eller `docs/sqa/reviews/**`, manuelt (tørkørsel som standard) | Opretter eller opdaterer Gitea-milepælen og issues for hver milepæl, der er Accepted med en Go-gennemgang |
|
||||
| Validate workflows | [`validate-workflows.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/validate-workflows.yml) | Kun dette repository | pull request, push til `main`, manuelt | Læser hvert workflow som YAML og kører offline-testene |
|
||||
|
||||
### Synkronisering af GitHub-metadata
|
||||
|
||||
Synkroniserer Gitea-repositoryets beskrivelse og emner til GitHub push-spejlet.
|
||||
|
||||
#### Tidsplan (cron)
|
||||
|
||||
Dagligt kl. 03:17 UTC (`17 3 * * *`) samt ved hvert push til `main` og manuel `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
|
||||
```
|
||||
|
||||
### Publicering af wiki (scoped, forældet)
|
||||
|
||||
Publicerer `wiki/` til repositoryets wiki, kun i et repository, der har tilmeldt sig med `wiki/.publish`. Ordet `prune` i den fil sletter også sider, som ikke findes i `wiki/`.
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Publish wiki/ to the repository wiki
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Push to main that changes wiki/**,\nor manual trigger" as Trigger
|
||||
participant "Gitea Actions\npublish-wiki" as Workflow
|
||||
participant "shared-scripts\n(tools/publish_wiki.py at v1)" as Script
|
||||
participant "Gitea wiki API" as Wiki
|
||||
|
||||
Trigger -> Workflow: Start workflow
|
||||
activate Workflow
|
||||
Workflow -> Script: Check out the repository and the script, run it
|
||||
activate Script
|
||||
|
||||
alt wiki/.publish does not exist
|
||||
Script --> Workflow: Log that publishing is not enabled and succeed\n(nothing is written)
|
||||
else wiki/ has no Markdown pages
|
||||
Script --> Workflow: Fail with [configuration]\n(an empty wiki/ never deletes pages)
|
||||
else
|
||||
Script -> Script: Read the marker (empty, or the word prune)\nand TOKEN_FOR_GITEA_WIKI
|
||||
Script -> Wiki: GET repository (preflight)
|
||||
Wiki --> Script: Wiki is enabled, token accepted
|
||||
Script -> Wiki: GET pages
|
||||
Wiki --> Script: Existing pages
|
||||
Script -> Wiki: Create new pages, update changed pages
|
||||
opt marker says prune
|
||||
Script -> Wiki: Delete pages that are not in wiki/
|
||||
end
|
||||
Script --> Workflow: Log created, updated and deleted counts
|
||||
end
|
||||
deactivate Script
|
||||
Workflow --> Trigger: Workflow result
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Kvalitetskontrol
|
||||
|
||||
Et genbrugeligt workflow til Python og shell, kaldt med `uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1` (se [vejledningen](QualityChecksPythonShell)).
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Shared quality checks (reusable workflow)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Calling repository\nuses: ...quality-checks.yml@v1" as Caller
|
||||
participant "Gitea Actions\nquality-checks" as Workflow
|
||||
participant "PyPI" as PyPI
|
||||
|
||||
Caller -> Workflow: workflow_call with languages,\nworking-directory and tool versions
|
||||
activate Workflow
|
||||
|
||||
Workflow -> Workflow: Validate the inputs
|
||||
alt languages or working-directory is invalid
|
||||
Workflow --> Caller: Fail with [configuration]
|
||||
end
|
||||
|
||||
Workflow -> Workflow: Check out the calling repository
|
||||
Workflow -> PyPI: Install the pinned tools in a virtual environment\n(ruff, mypy, shellcheck-py, shfmt-py as selected)
|
||||
PyPI --> Workflow: Tools installed
|
||||
|
||||
loop for each selected language
|
||||
Workflow -> Workflow: List tracked files
|
||||
alt no files of that language
|
||||
Workflow -> Workflow: Notice: nothing was checked
|
||||
else
|
||||
Workflow -> Workflow: Run every tool and record PASS or FAIL
|
||||
end
|
||||
end
|
||||
|
||||
alt any tool failed
|
||||
Workflow --> Caller: Fail and list the failed tools
|
||||
else
|
||||
Workflow --> Caller: All selected checks passed
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Kvalitetskontrol C++
|
||||
|
||||
Et genbrugeligt workflow til C og C++, kaldt med `uses: TirSystem/github-action/.gitea/workflows/quality-checks-cpp.yml@v1` (ADR-0008). Repositoryet skal have en `.clang-format`; en `.clang-tidy` og en compile-database er valgfrie.
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Shared quality checks for C and C++ (reusable workflow)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Calling repository\nuses: ...quality-checks-cpp.yml@v1" as Caller
|
||||
participant "Gitea Actions\nquality-checks-cpp" as Workflow
|
||||
participant "PyPI" as PyPI
|
||||
|
||||
Caller -> Workflow: workflow_call with working-directory, std,\ncompile-commands-dir and tool versions
|
||||
activate Workflow
|
||||
|
||||
Workflow -> Workflow: Check out the caller and the shared script
|
||||
Workflow -> Workflow: Validate the inputs
|
||||
alt an input is invalid or a version is not exact
|
||||
Workflow --> Caller: Fail with [configuration]
|
||||
end
|
||||
|
||||
Workflow -> PyPI: Install clang-format and clang-tidy at the exact versions
|
||||
PyPI --> Workflow: Tools installed
|
||||
|
||||
alt no C or C++ file is tracked
|
||||
Workflow --> Caller: Notice: nothing was checked, pass
|
||||
else no .clang-format, or compile-commands-dir\nwithout compile_commands.json
|
||||
Workflow --> Caller: Fail with [configuration]
|
||||
else
|
||||
Workflow -> Workflow: clang-format --dry-run -Werror on all files
|
||||
Workflow -> Workflow: clang-tidy on the C++ files (-std=std)\nand on the C files (or with the compile database)
|
||||
alt any tool failed
|
||||
Workflow --> Caller: Fail with tool, file and line in the log
|
||||
else
|
||||
Workflow --> Caller: All selected checks passed
|
||||
end
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Kvalitetskontrol C#
|
||||
|
||||
Et genbrugeligt workflow til C#, kaldt med `uses: TirSystem/github-action/.gitea/workflows/quality-checks-csharp.yml@v1` (ADR-0008). Det installerer det præcise .NET SDK, som `dotnet-sdk-version` angiver (10 eller nyere), og skal bruge netværket til pakkegendannelsen.
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Shared quality checks for C# (reusable workflow)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Calling repository\nuses: ...quality-checks-csharp.yml@v1" as Caller
|
||||
participant "Gitea Actions\nquality-checks-csharp" as Workflow
|
||||
participant "dot.net\n(dotnet-install.sh)" as DotNet
|
||||
|
||||
Caller -> Workflow: workflow_call with working-directory,\nproject and dotnet-sdk-version
|
||||
activate Workflow
|
||||
|
||||
Workflow -> Workflow: Check out the caller and the shared script
|
||||
Workflow -> Workflow: Validate the inputs
|
||||
alt an input is invalid or the SDK is not an exact\nstable version 10 or later
|
||||
Workflow --> Caller: Fail with [configuration]
|
||||
end
|
||||
|
||||
Workflow -> DotNet: Install the exact .NET SDK version
|
||||
DotNet --> Workflow: SDK installed
|
||||
|
||||
alt no C# file is tracked
|
||||
Workflow --> Caller: Notice: nothing was checked, pass
|
||||
else no solution or project, or several without the project input
|
||||
Workflow --> Caller: Fail with [configuration] that names them
|
||||
else
|
||||
Workflow -> Workflow: dotnet format --verify-no-changes
|
||||
Workflow -> Workflow: dotnet build -warnaserror\n(package restore needs the network)
|
||||
alt any tool failed
|
||||
Workflow --> Caller: Fail with tool, file and line in the log
|
||||
else
|
||||
Workflow --> Caller: All selected checks passed
|
||||
end
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Udgivelse
|
||||
|
||||
Startes manuelt af en vedligeholder; med `dry_run` `true` (standard) kontrollerer det kun (se [udgivelsesprocessen](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/release-process.md)).
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Release this repository
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Maintainer\n(workflow_dispatch: version, dry_run)" as Trigger
|
||||
participant "Gitea Actions\nrelease" as Workflow
|
||||
participant "Gitea REST API" as Gitea
|
||||
|
||||
Trigger -> Workflow: Start with version and dry_run
|
||||
activate Workflow
|
||||
|
||||
Workflow -> Workflow: Check the version and read CHANGELOG.md
|
||||
alt version malformed or no changelog entry
|
||||
Workflow --> Trigger: Fail with [validation] or [configuration]
|
||||
end
|
||||
|
||||
Workflow -> Gitea: GET branch main and status of the commit
|
||||
Gitea --> Workflow: Tip of main and the validation run
|
||||
alt commit is not the tip of main,\nor the validation run is not green
|
||||
Workflow --> Trigger: Fail with [validation]\n(no tag is created)
|
||||
end
|
||||
|
||||
Workflow -> Gitea: GET tags
|
||||
Gitea --> Workflow: Existing tags
|
||||
alt tag vMAJOR.MINOR.PATCH exists
|
||||
Workflow --> Trigger: Fail with [validation]\n(tags are never moved)
|
||||
end
|
||||
|
||||
alt dry_run is true (default)
|
||||
Workflow --> Trigger: Log what would be created and stop
|
||||
else
|
||||
Workflow -> Gitea: POST release (creates the version tag,\nbody is the changelog entry)
|
||||
opt this is the highest version of its major
|
||||
Workflow -> Gitea: Delete and recreate the major tag vMAJOR
|
||||
end
|
||||
Workflow --> Trigger: Released
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Publicering af wiki-sider
|
||||
|
||||
Et genbrugeligt workflow (ADR-0009). Et repository kalder det fra sit eget workflow, så selve kaldet er tilmeldingen, og der behøves ingen markørfil. Det publicerer Markdown-siderne i `wiki_dir` (standard `docs/wiki`) til wikien i det kaldende repository og sletter kun sider, der ikke findes i mappen, når `prune` er `true`.
|
||||
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
branches: [ main ]
|
||||
paths: [ "docs/wiki/**" ]
|
||||
jobs:
|
||||
wiki:
|
||||
uses: TirSystem/github-action/.gitea/workflows/publish-wiki-pages.yml@v1
|
||||
secrets:
|
||||
TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
|
||||
```
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Publish docs/wiki to the wiki of the calling repository
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Calling repository\nuses: ...publish-wiki-pages.yml@v1" as Caller
|
||||
participant "Gitea Actions\npublish-wiki-pages" as Workflow
|
||||
participant "shared-scripts\n(tools/publish_wiki.py at tools-ref)" as Script
|
||||
participant "Gitea wiki API" as Wiki
|
||||
|
||||
Caller -> Workflow: Call with wiki_dir, prune and the secret
|
||||
activate Workflow
|
||||
Workflow -> Script: Check out the repository and the script, run it
|
||||
activate Script
|
||||
|
||||
alt wiki_dir does not exist, or has no Markdown pages
|
||||
Script --> Workflow: Fail with [configuration]\n(an empty folder never deletes pages)
|
||||
else
|
||||
Script -> Script: Read prune and TOKEN_FOR_GITEA_WIKI
|
||||
Script -> Wiki: GET repository (preflight)
|
||||
Wiki --> Script: Wiki is enabled, token accepted
|
||||
Script -> Wiki: GET pages
|
||||
Wiki --> Script: Existing pages
|
||||
Script -> Wiki: Create new pages, update changed pages
|
||||
opt prune is true
|
||||
Script -> Wiki: Delete pages that are not in wiki_dir
|
||||
end
|
||||
Script --> Workflow: Log created, updated and deleted counts
|
||||
end
|
||||
deactivate Script
|
||||
Workflow --> Caller: Workflow result
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Publicering af egen wiki
|
||||
|
||||
Dette repositorys wiki er `docs/wiki/`. Workflowet kalder det genbrugelige workflow ovenfor med dets lokale sti, med `prune` sat til `true`, så wikien altid er lig med mappen, og `tools-ref` sat til `main`, så scriptet fra samme commit kører. Det er den kalder, et projekt kopierer fra frameworkets `templates/ci/publish-wiki.yml`.
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Publish the wiki of this repository (docs/wiki)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Push to main that changes docs/wiki/**,\nor manual trigger" as Trigger
|
||||
participant "Gitea Actions\npublish-own-wiki" as Caller
|
||||
participant "Gitea Actions\npublish-wiki-pages\n(called by its local path)" as Workflow
|
||||
participant "Gitea wiki API" as Wiki
|
||||
|
||||
Trigger -> Caller: Start workflow
|
||||
activate Caller
|
||||
Caller -> Workflow: Call with wiki_dir docs/wiki, prune true,\ntools-ref main and TOKEN_FOR_GITEA_WIKI
|
||||
activate Workflow
|
||||
Workflow -> Wiki: Create, update and delete pages\nso the wiki equals docs/wiki
|
||||
Wiki --> Workflow: Done
|
||||
Workflow --> Caller: Workflow result
|
||||
deactivate Workflow
|
||||
Caller --> Trigger: Workflow result
|
||||
deactivate Caller
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Publicering af accepterede milepæle
|
||||
|
||||
Permanent tilladelse til at publicere: ved et push til `main`, der ændrer milepælene eller deres gennemgange, oprettes eller opdateres hver milepæl, hvis seneste række i Version History er Accepted, og hvis seneste gennemgang er en Go, på Gitea med sine opgaver som issues. Intet lukkes eller slettes. En manuel kørsel er en tørkørsel, medmindre `dry_run` slås fra. Det bruger secret'en `TOKEN_FOR_GITEA` og `--accepted-only`-reglen i det monterede framework (v0.5.0 eller nyere).
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Publish accepted milestones (this repository)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Push to main that changes\ndocs/milestones/** or docs/sqa/reviews/**,\nor manual trigger" as Trigger
|
||||
participant "Gitea Actions\nsync-milestones" as Workflow
|
||||
participant "framework/scripts/\nsync-project.sh" as Script
|
||||
participant "Gitea REST API" as Gitea
|
||||
|
||||
Trigger -> Workflow: Start workflow
|
||||
activate Workflow
|
||||
Workflow -> Workflow: Check out the project and the framework\nsubmodules over HTTPS with TOKEN_FOR_GITEA
|
||||
Workflow -> Script: --accepted-only (dry run)\nor --accepted-only --apply
|
||||
activate Script
|
||||
|
||||
loop for each docs/milestones/mil-*.md
|
||||
alt latest Version History row is not Accepted,\nor the latest review record is not a Go
|
||||
Script -> Script: Skip with the reason on stderr
|
||||
else
|
||||
alt dry run
|
||||
Script -> Script: Print the plan, no network call
|
||||
else
|
||||
Script -> Gitea: Create or update the Milestone\nand one Issue per task row
|
||||
Gitea --> Script: Milestone and issue numbers
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
note right of Script
|
||||
Nothing is closed or deleted.
|
||||
Each real run edits the issues
|
||||
of every accepted milestone.
|
||||
end note
|
||||
Script --> Workflow: Done, or "nothing to publish"
|
||||
deactivate Script
|
||||
Workflow --> Trigger: Workflow result
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Validering af workflows
|
||||
|
||||
Repositoryets egen validering: de offline-tests, der er en betingelse for hver pull request.
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Validate workflows (this repository's own checks)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Pull request,\npush to main, or manual trigger" as Trigger
|
||||
participant "Gitea Actions\nvalidate-workflows" as Workflow
|
||||
|
||||
Trigger -> Workflow: Start workflow
|
||||
activate Workflow
|
||||
Workflow -> Workflow: Check out the repository
|
||||
Workflow -> Workflow: Create a virtual environment and\ninstall tests/requirements.txt
|
||||
Workflow -> Workflow: Run pytest on tests/ under coverage (offline, no secrets):\nworkflows parse as YAML, no embedded Python,\nscripts compile, wiki pages and translations are current,\nsync, publish and release flows against a fake API
|
||||
|
||||
alt a test fails
|
||||
Workflow --> Trigger: Workflow fails (the pull request is not ready)
|
||||
else
|
||||
Workflow --> Trigger: Workflow succeeds
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
|
||||
## Krav
|
||||
|
||||
- En Gitea-instans med Actions aktiveret og en runner med labelen `ubuntu-latest` og `python3`
|
||||
- Et konfigureret GitHub push-spejl på Gitea-repositoryet (højst ét; repositories uden spejl springes over uden fejl)
|
||||
- Repository-secrets:
|
||||
- `TOKEN_FOR_GITEA`: Gitea API-token (kun tokenet, ingen JSON)
|
||||
- `PAT_FOR_GITHUB`: et GitHub personal access token, der må redigere spejl-repositoryet (kun tokenet, ingen JSON)
|
||||
- `TOKEN_FOR_GITEA_WIKI` (kun for repositories, der publicerer en wiki, se [tilslutningsvejledningen](Onboarding.da)): et Gitea-token, der kan skrive til wikien, gemt som en secret i repositoryets organisation; der er ingen reserve til `TOKEN_FOR_GITEA`
|
||||
|
||||
|
||||
## Opsætning
|
||||
|
||||
Der skal ikke installeres afhængigheder; workflowet bruger kun Pythons standardbibliotek.
|
||||
|
||||
1. Klon repositoryet:
|
||||
```bash
|
||||
git clone ssh://git@git.tirsystem.com:10022/TirSystem/github-action.git
|
||||
```
|
||||
2. Tilføj de secrets, der er nævnt under [Krav](#krav), til repositoryets indstillinger i Gitea.
|
||||
3. Konfigurer GitHub push-spejlet i repositoryets indstillinger.
|
||||
|
||||
|
||||
## Kørsel
|
||||
|
||||
Workflows kører automatisk ved push til `main` og efter den daglige tidsplan. For at køre manuelt skal du starte **Sync GitHub mirror metadata** via `workflow_dispatch` fra fanen Actions i Gitea.
|
||||
|
||||
|
||||
## Tests
|
||||
|
||||
Workflow-filerne og scripts i `tools/` valideres af offline-tests, som hverken kræver netværksadgang eller 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 coverage run -m pytest -q tests
|
||||
python -m coverage report
|
||||
```
|
||||
|
||||
De samme kontroller kører ved hver pull request og hvert push til `main` gennem [`validate-workflows.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/validate-workflows.yml). De parser alle workflows som YAML, kontrollerer at ingen indlejrer Python, kompilerer scripts i `tools/`, kræver eksplicitte jobtilladelser og tester parsing af credentials, parsing af push-spejlets adresse og synkroniserings- og publiceringsforløbene mod et falsk API. Kørslen fejler, når linje- og forgreningsdækningen af `tools/` er under 95 % (`.coveragerc`).
|
||||
|
||||
Efter en ændring af synkroniseringsworkflowet skal du også starte **Sync GitHub mirror metadata** manuelt i Gitea og sammenligne beskrivelsen og emnerne på GitHub-spejlet.
|
||||
@@ -0,0 +1,535 @@
|
||||
<!-- 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.
|
||||
|
||||
English | [Dansk](Home.da) | [Bahasa Melayu](Home.ms)
|
||||
|
||||
# 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 contains ten workflows: metadata sync to the GitHub mirror, wiki publishing (scoped, and reusable for repositories that call it), shared quality checks for Python and shell, for C and C++ and for C#, a release workflow, the publishing of accepted milestones and the repository's own validation. They are listed with their purpose and a diagram under [Workflows](#workflows).
|
||||
|
||||
|
||||
## Workflows
|
||||
|
||||
Ten workflows live in this repository. A **scoped** workflow is delivered by the instance to every repository of the TirSystem organizations and needs nothing in the repository; a **reusable** workflow is called by a repository with `uses:`; the others run only here. The diagrams are PlantUML source.
|
||||
|
||||
| Workflow | File | Kind | Starts on | Purpose |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Sync GitHub mirror metadata | [`sync-github-metadata.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/scoped_workflows/sync-github-metadata.yml) | Scoped | push to `main`, manual, daily 03:17 UTC | Copies the description and topics of a Gitea repository to its GitHub push mirror |
|
||||
| Publish wiki | [`publish-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/scoped_workflows/publish-wiki.yml) | Scoped, opt-in with `wiki/.publish`; deprecated, replaced by the reusable workflow below (ADR-0009) | push to `main` that changes `wiki/**`, manual | Publishes the pages in `wiki/` to the repository wiki |
|
||||
| Publish wiki pages | [`publish-wiki-pages.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/publish-wiki-pages.yml) | Reusable (`workflow_call`) | a call from another repository | Publishes the pages in `docs/wiki/` (or the folder named by `wiki_dir`) to the wiki of the calling repository |
|
||||
| Quality checks | [`quality-checks.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks.yml) | Reusable (`workflow_call`) | a call from another repository | Runs ruff, mypy, shellcheck and shfmt on the tracked files and changes nothing |
|
||||
| Quality checks C++ | [`quality-checks-cpp.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks-cpp.yml) | Reusable (`workflow_call`) | a call from another repository | Runs clang-format and clang-tidy at exact versions on the tracked C and C++ files and changes nothing |
|
||||
| Quality checks C# | [`quality-checks-csharp.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks-csharp.yml) | Reusable (`workflow_call`) | a call from another repository | Runs `dotnet format` and `dotnet build` on an exact .NET SDK 10 or later and changes nothing |
|
||||
| Publish own wiki | [`publish-own-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/publish-own-wiki.yml) | This repository only | push to `main` that changes `docs/wiki/**`, manual | Calls the reusable Publish wiki pages workflow for the wiki of this repository |
|
||||
| Release | [`release.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/release.yml) | This repository only | manual | Creates the version tag, the release page and the major tag after the checks |
|
||||
| Publish accepted milestones | [`sync-milestones.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/sync-milestones.yml) | This repository only | push to `main` that changes `docs/milestones/**` or `docs/sqa/reviews/**`, manual (dry run by default) | Creates or updates the Gitea milestone and issues of every milestone that is Accepted with a Go review |
|
||||
| Validate workflows | [`validate-workflows.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/validate-workflows.yml) | This repository only | pull request, push to `main`, manual | Parses every workflow and runs the offline tests |
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
### Publish wiki (scoped, deprecated)
|
||||
|
||||
Publishes `wiki/` to the repository wiki, only in a repository that has opted in with `wiki/.publish`. The word `prune` in that file also deletes pages that are not in `wiki/`.
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Publish wiki/ to the repository wiki
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Push to main that changes wiki/**,\nor manual trigger" as Trigger
|
||||
participant "Gitea Actions\npublish-wiki" as Workflow
|
||||
participant "shared-scripts\n(tools/publish_wiki.py at v1)" as Script
|
||||
participant "Gitea wiki API" as Wiki
|
||||
|
||||
Trigger -> Workflow: Start workflow
|
||||
activate Workflow
|
||||
Workflow -> Script: Check out the repository and the script, run it
|
||||
activate Script
|
||||
|
||||
alt wiki/.publish does not exist
|
||||
Script --> Workflow: Log that publishing is not enabled and succeed\n(nothing is written)
|
||||
else wiki/ has no Markdown pages
|
||||
Script --> Workflow: Fail with [configuration]\n(an empty wiki/ never deletes pages)
|
||||
else
|
||||
Script -> Script: Read the marker (empty, or the word prune)\nand TOKEN_FOR_GITEA_WIKI
|
||||
Script -> Wiki: GET repository (preflight)
|
||||
Wiki --> Script: Wiki is enabled, token accepted
|
||||
Script -> Wiki: GET pages
|
||||
Wiki --> Script: Existing pages
|
||||
Script -> Wiki: Create new pages, update changed pages
|
||||
opt marker says prune
|
||||
Script -> Wiki: Delete pages that are not in wiki/
|
||||
end
|
||||
Script --> Workflow: Log created, updated and deleted counts
|
||||
end
|
||||
deactivate Script
|
||||
Workflow --> Trigger: Workflow result
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Quality checks
|
||||
|
||||
A reusable workflow for Python and shell, called with `uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1` (see the [guide](QualityChecksPythonShell)).
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Shared quality checks (reusable workflow)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Calling repository\nuses: ...quality-checks.yml@v1" as Caller
|
||||
participant "Gitea Actions\nquality-checks" as Workflow
|
||||
participant "PyPI" as PyPI
|
||||
|
||||
Caller -> Workflow: workflow_call with languages,\nworking-directory and tool versions
|
||||
activate Workflow
|
||||
|
||||
Workflow -> Workflow: Validate the inputs
|
||||
alt languages or working-directory is invalid
|
||||
Workflow --> Caller: Fail with [configuration]
|
||||
end
|
||||
|
||||
Workflow -> Workflow: Check out the calling repository
|
||||
Workflow -> PyPI: Install the pinned tools in a virtual environment\n(ruff, mypy, shellcheck-py, shfmt-py as selected)
|
||||
PyPI --> Workflow: Tools installed
|
||||
|
||||
loop for each selected language
|
||||
Workflow -> Workflow: List tracked files
|
||||
alt no files of that language
|
||||
Workflow -> Workflow: Notice: nothing was checked
|
||||
else
|
||||
Workflow -> Workflow: Run every tool and record PASS or FAIL
|
||||
end
|
||||
end
|
||||
|
||||
alt any tool failed
|
||||
Workflow --> Caller: Fail and list the failed tools
|
||||
else
|
||||
Workflow --> Caller: All selected checks passed
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Quality checks C++
|
||||
|
||||
A reusable workflow for C and C++, called with `uses: TirSystem/github-action/.gitea/workflows/quality-checks-cpp.yml@v1` (ADR-0008). The repository needs a `.clang-format`; a `.clang-tidy` and a compile database are optional.
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Shared quality checks for C and C++ (reusable workflow)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Calling repository\nuses: ...quality-checks-cpp.yml@v1" as Caller
|
||||
participant "Gitea Actions\nquality-checks-cpp" as Workflow
|
||||
participant "PyPI" as PyPI
|
||||
|
||||
Caller -> Workflow: workflow_call with working-directory, std,\ncompile-commands-dir and tool versions
|
||||
activate Workflow
|
||||
|
||||
Workflow -> Workflow: Check out the caller and the shared script
|
||||
Workflow -> Workflow: Validate the inputs
|
||||
alt an input is invalid or a version is not exact
|
||||
Workflow --> Caller: Fail with [configuration]
|
||||
end
|
||||
|
||||
Workflow -> PyPI: Install clang-format and clang-tidy at the exact versions
|
||||
PyPI --> Workflow: Tools installed
|
||||
|
||||
alt no C or C++ file is tracked
|
||||
Workflow --> Caller: Notice: nothing was checked, pass
|
||||
else no .clang-format, or compile-commands-dir\nwithout compile_commands.json
|
||||
Workflow --> Caller: Fail with [configuration]
|
||||
else
|
||||
Workflow -> Workflow: clang-format --dry-run -Werror on all files
|
||||
Workflow -> Workflow: clang-tidy on the C++ files (-std=std)\nand on the C files (or with the compile database)
|
||||
alt any tool failed
|
||||
Workflow --> Caller: Fail with tool, file and line in the log
|
||||
else
|
||||
Workflow --> Caller: All selected checks passed
|
||||
end
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Quality checks C#
|
||||
|
||||
A reusable workflow for C#, called with `uses: TirSystem/github-action/.gitea/workflows/quality-checks-csharp.yml@v1` (ADR-0008). It installs the exact .NET SDK given by `dotnet-sdk-version` (10 or later) and needs the network for the package restore.
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Shared quality checks for C# (reusable workflow)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Calling repository\nuses: ...quality-checks-csharp.yml@v1" as Caller
|
||||
participant "Gitea Actions\nquality-checks-csharp" as Workflow
|
||||
participant "dot.net\n(dotnet-install.sh)" as DotNet
|
||||
|
||||
Caller -> Workflow: workflow_call with working-directory,\nproject and dotnet-sdk-version
|
||||
activate Workflow
|
||||
|
||||
Workflow -> Workflow: Check out the caller and the shared script
|
||||
Workflow -> Workflow: Validate the inputs
|
||||
alt an input is invalid or the SDK is not an exact\nstable version 10 or later
|
||||
Workflow --> Caller: Fail with [configuration]
|
||||
end
|
||||
|
||||
Workflow -> DotNet: Install the exact .NET SDK version
|
||||
DotNet --> Workflow: SDK installed
|
||||
|
||||
alt no C# file is tracked
|
||||
Workflow --> Caller: Notice: nothing was checked, pass
|
||||
else no solution or project, or several without the project input
|
||||
Workflow --> Caller: Fail with [configuration] that names them
|
||||
else
|
||||
Workflow -> Workflow: dotnet format --verify-no-changes
|
||||
Workflow -> Workflow: dotnet build -warnaserror\n(package restore needs the network)
|
||||
alt any tool failed
|
||||
Workflow --> Caller: Fail with tool, file and line in the log
|
||||
else
|
||||
Workflow --> Caller: All selected checks passed
|
||||
end
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Release
|
||||
|
||||
Started by hand by a maintainer; with `dry_run` `true` (the default) it only checks (see the [release process](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/release-process.md)).
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Release this repository
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Maintainer\n(workflow_dispatch: version, dry_run)" as Trigger
|
||||
participant "Gitea Actions\nrelease" as Workflow
|
||||
participant "Gitea REST API" as Gitea
|
||||
|
||||
Trigger -> Workflow: Start with version and dry_run
|
||||
activate Workflow
|
||||
|
||||
Workflow -> Workflow: Check the version and read CHANGELOG.md
|
||||
alt version malformed or no changelog entry
|
||||
Workflow --> Trigger: Fail with [validation] or [configuration]
|
||||
end
|
||||
|
||||
Workflow -> Gitea: GET branch main and status of the commit
|
||||
Gitea --> Workflow: Tip of main and the validation run
|
||||
alt commit is not the tip of main,\nor the validation run is not green
|
||||
Workflow --> Trigger: Fail with [validation]\n(no tag is created)
|
||||
end
|
||||
|
||||
Workflow -> Gitea: GET tags
|
||||
Gitea --> Workflow: Existing tags
|
||||
alt tag vMAJOR.MINOR.PATCH exists
|
||||
Workflow --> Trigger: Fail with [validation]\n(tags are never moved)
|
||||
end
|
||||
|
||||
alt dry_run is true (default)
|
||||
Workflow --> Trigger: Log what would be created and stop
|
||||
else
|
||||
Workflow -> Gitea: POST release (creates the version tag,\nbody is the changelog entry)
|
||||
opt this is the highest version of its major
|
||||
Workflow -> Gitea: Delete and recreate the major tag vMAJOR
|
||||
end
|
||||
Workflow --> Trigger: Released
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Publish wiki pages
|
||||
|
||||
A reusable workflow (ADR-0009). A repository calls it from its own workflow, so the call is the opt-in and no marker file is needed. It publishes the Markdown pages of `wiki_dir` (default `docs/wiki`) to the wiki of the calling repository, and deletes pages that are not in the folder only when `prune` is `true`.
|
||||
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
branches: [ main ]
|
||||
paths: [ "docs/wiki/**" ]
|
||||
jobs:
|
||||
wiki:
|
||||
uses: TirSystem/github-action/.gitea/workflows/publish-wiki-pages.yml@v1
|
||||
secrets:
|
||||
TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
|
||||
```
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Publish docs/wiki to the wiki of the calling repository
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Calling repository\nuses: ...publish-wiki-pages.yml@v1" as Caller
|
||||
participant "Gitea Actions\npublish-wiki-pages" as Workflow
|
||||
participant "shared-scripts\n(tools/publish_wiki.py at tools-ref)" as Script
|
||||
participant "Gitea wiki API" as Wiki
|
||||
|
||||
Caller -> Workflow: Call with wiki_dir, prune and the secret
|
||||
activate Workflow
|
||||
Workflow -> Script: Check out the repository and the script, run it
|
||||
activate Script
|
||||
|
||||
alt wiki_dir does not exist, or has no Markdown pages
|
||||
Script --> Workflow: Fail with [configuration]\n(an empty folder never deletes pages)
|
||||
else
|
||||
Script -> Script: Read prune and TOKEN_FOR_GITEA_WIKI
|
||||
Script -> Wiki: GET repository (preflight)
|
||||
Wiki --> Script: Wiki is enabled, token accepted
|
||||
Script -> Wiki: GET pages
|
||||
Wiki --> Script: Existing pages
|
||||
Script -> Wiki: Create new pages, update changed pages
|
||||
opt prune is true
|
||||
Script -> Wiki: Delete pages that are not in wiki_dir
|
||||
end
|
||||
Script --> Workflow: Log created, updated and deleted counts
|
||||
end
|
||||
deactivate Script
|
||||
Workflow --> Caller: Workflow result
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Publish own wiki
|
||||
|
||||
The wiki of this repository is `docs/wiki/`. This workflow calls the reusable workflow above by its local path, with `prune` set to `true` so the wiki always equals the folder and `tools-ref` set to `main` so that the script of the same commit runs. It is the caller that a project copies from the framework's `templates/ci/publish-wiki.yml`.
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Publish the wiki of this repository (docs/wiki)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Push to main that changes docs/wiki/**,\nor manual trigger" as Trigger
|
||||
participant "Gitea Actions\npublish-own-wiki" as Caller
|
||||
participant "Gitea Actions\npublish-wiki-pages\n(called by its local path)" as Workflow
|
||||
participant "Gitea wiki API" as Wiki
|
||||
|
||||
Trigger -> Caller: Start workflow
|
||||
activate Caller
|
||||
Caller -> Workflow: Call with wiki_dir docs/wiki, prune true,\ntools-ref main and TOKEN_FOR_GITEA_WIKI
|
||||
activate Workflow
|
||||
Workflow -> Wiki: Create, update and delete pages\nso the wiki equals docs/wiki
|
||||
Wiki --> Workflow: Done
|
||||
Workflow --> Caller: Workflow result
|
||||
deactivate Workflow
|
||||
Caller --> Trigger: Workflow result
|
||||
deactivate Caller
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Publish accepted milestones
|
||||
|
||||
Standing authorization to publish: on a push to `main` that changes the milestones or their reviews, every milestone whose latest Version History row is Accepted and whose latest review is a Go is created or updated on Gitea with its tasks as issues. Nothing is closed or deleted. A manual run is a dry run unless `dry_run` is switched off. It uses the secret `TOKEN_FOR_GITEA` and the `--accepted-only` rule of the mounted framework (v0.5.0 or later).
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Publish accepted milestones (this repository)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Push to main that changes\ndocs/milestones/** or docs/sqa/reviews/**,\nor manual trigger" as Trigger
|
||||
participant "Gitea Actions\nsync-milestones" as Workflow
|
||||
participant "framework/scripts/\nsync-project.sh" as Script
|
||||
participant "Gitea REST API" as Gitea
|
||||
|
||||
Trigger -> Workflow: Start workflow
|
||||
activate Workflow
|
||||
Workflow -> Workflow: Check out the project and the framework\nsubmodules over HTTPS with TOKEN_FOR_GITEA
|
||||
Workflow -> Script: --accepted-only (dry run)\nor --accepted-only --apply
|
||||
activate Script
|
||||
|
||||
loop for each docs/milestones/mil-*.md
|
||||
alt latest Version History row is not Accepted,\nor the latest review record is not a Go
|
||||
Script -> Script: Skip with the reason on stderr
|
||||
else
|
||||
alt dry run
|
||||
Script -> Script: Print the plan, no network call
|
||||
else
|
||||
Script -> Gitea: Create or update the Milestone\nand one Issue per task row
|
||||
Gitea --> Script: Milestone and issue numbers
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
note right of Script
|
||||
Nothing is closed or deleted.
|
||||
Each real run edits the issues
|
||||
of every accepted milestone.
|
||||
end note
|
||||
Script --> Workflow: Done, or "nothing to publish"
|
||||
deactivate Script
|
||||
Workflow --> Trigger: Workflow result
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Validate workflows
|
||||
|
||||
The repository's own validation: the offline tests that gate every pull request.
|
||||
|
||||
#### Workflow
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Validate workflows (this repository's own checks)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Pull request,\npush to main, or manual trigger" as Trigger
|
||||
participant "Gitea Actions\nvalidate-workflows" as Workflow
|
||||
|
||||
Trigger -> Workflow: Start workflow
|
||||
activate Workflow
|
||||
Workflow -> Workflow: Check out the repository
|
||||
Workflow -> Workflow: Create a virtual environment and\ninstall tests/requirements.txt
|
||||
Workflow -> Workflow: Run pytest on tests/ under coverage (offline, no secrets):\nworkflows parse as YAML, no embedded Python,\nscripts compile, wiki pages and translations are current,\nsync, publish and release flows against a fake API
|
||||
|
||||
alt a test fails
|
||||
Workflow --> Trigger: Workflow fails (the pull request is not ready)
|
||||
else
|
||||
Workflow --> Trigger: Workflow succeeds
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
|
||||
## 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](Onboarding)): 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 coverage run -m pytest -q tests
|
||||
python -m coverage report
|
||||
```
|
||||
|
||||
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, 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. The run fails when the line and branch coverage of `tools/` falls below 95% (`.coveragerc`).
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,535 @@
|
||||
<!-- translation of Home.md, source sha256 b6796554f4eb -->
|
||||
|
||||
> Ini ialah terjemahan [`Home`](Home). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
|
||||
|
||||
[English](Home) | [Dansk](Home.da) | Bahasa Melayu
|
||||
|
||||
# TirSystem GitHub Actions
|
||||
|
||||
Koleksi aliran kerja (workflow) Gitea Actions yang boleh digunakan semula untuk profesional DevOps dan jurutera perisian yang mengusahakan projek TirSystem.
|
||||
|
||||
|
||||
## Gambaran keseluruhan
|
||||
|
||||
Repositori ini ialah koleksi pusat bagi automasi yang boleh digunakan semula untuk repositori TirSystem. Repositori utama berada di `git.tirsystem.com` (Gitea) dan dicerminkan dengan push ke GitHub.
|
||||
|
||||
Ia mengandungi sepuluh aliran kerja: penyegerakan metadata ke cermin GitHub, penerbitan wiki (scoped, dan boleh guna semula bagi repositori yang memanggilnya), semakan kualiti bersama untuk Python dan shell, untuk C dan C++ serta untuk C#, aliran kerja keluaran, penerbitan pencapaian (milestone) yang diterima dan pengesahan repositori sendiri. Ia disenaraikan dengan tujuan dan rajah di bawah [Aliran kerja](#aliran-kerja).
|
||||
|
||||
|
||||
## Aliran kerja
|
||||
|
||||
Terdapat sepuluh aliran kerja dalam repositori ini. Aliran kerja **scoped** dihantar oleh instans ke setiap repositori organisasi TirSystem dan tidak memerlukan apa-apa dalam repositori; aliran kerja **boleh guna semula** dipanggil oleh sebuah repositori dengan `uses:`; yang lain hanya berjalan di sini. Rajah ialah kod sumber PlantUML dan dalam bahasa Inggeris.
|
||||
|
||||
| Aliran kerja | Fail | Jenis | Bermula apabila | Tujuan |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Sync GitHub mirror metadata | [`sync-github-metadata.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/scoped_workflows/sync-github-metadata.yml) | Scoped | push ke `main`, manual, setiap hari 03:17 UTC | Menyalin penerangan dan topik repositori Gitea ke push mirror GitHub-nya |
|
||||
| Publish wiki | [`publish-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/scoped_workflows/publish-wiki.yml) | Scoped, pilih menyertai dengan `wiki/.publish`; usang, sedang diganti oleh aliran kerja boleh guna semula di bawah (ADR-0009) | push ke `main` yang mengubah `wiki/**`, manual | Menerbitkan halaman dalam `wiki/` ke wiki repositori |
|
||||
| Publish wiki pages | [`publish-wiki-pages.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/publish-wiki-pages.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Menerbitkan halaman dalam `docs/wiki/` (atau folder yang dinamakan oleh `wiki_dir`) ke wiki repositori pemanggil |
|
||||
| Quality checks | [`quality-checks.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Menjalankan ruff, mypy, shellcheck dan shfmt pada fail yang dijejaki dan tidak mengubah apa-apa |
|
||||
| Quality checks C++ | [`quality-checks-cpp.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks-cpp.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Menjalankan clang-format dan clang-tidy pada versi tepat pada fail C dan C++ yang dijejaki dan tidak mengubah apa-apa |
|
||||
| Quality checks C# | [`quality-checks-csharp.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks-csharp.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Menjalankan `dotnet format` dan `dotnet build` pada .NET SDK 10 atau lebih baharu yang tepat dan tidak mengubah apa-apa |
|
||||
| Publish own wiki | [`publish-own-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/publish-own-wiki.yml) | Repositori ini sahaja | push ke `main` yang mengubah `docs/wiki/**`, manual | Memanggil aliran kerja boleh guna semula Publish wiki pages untuk wiki repositori ini |
|
||||
| Release | [`release.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/release.yml) | Repositori ini sahaja | manual | Mencipta tag versi, halaman keluaran dan tag major selepas semakan |
|
||||
| Menerbitkan milestone yang diterima | [`sync-milestones.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/sync-milestones.yml) | Repositori ini sahaja | push ke `main` yang mengubah `docs/milestones/**` atau `docs/sqa/reviews/**`, manual (larian percubaan secara lalai) | Mencipta atau mengemas kini milestone Gitea dan isu bagi setiap milestone yang Accepted dengan semakan Go |
|
||||
| Validate workflows | [`validate-workflows.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/validate-workflows.yml) | Repositori ini sahaja | pull request, push ke `main`, manual | Menghurai setiap aliran kerja sebagai YAML dan menjalankan ujian luar talian |
|
||||
|
||||
### Menyegerakkan metadata GitHub
|
||||
|
||||
Menyegerakkan penerangan dan topik repositori Gitea ke push mirror GitHub.
|
||||
|
||||
#### Jadual (cron)
|
||||
|
||||
Setiap hari pada 03:17 UTC (`17 3 * * *`), serta pada setiap push ke `main` dan `workflow_dispatch` manual.
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### Menerbitkan wiki (scoped, usang)
|
||||
|
||||
Menerbitkan `wiki/` ke wiki repositori, hanya dalam repositori yang telah menyertai dengan `wiki/.publish`. Perkataan `prune` dalam fail itu juga memadam halaman yang tiada dalam `wiki/`.
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Publish wiki/ to the repository wiki
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Push to main that changes wiki/**,\nor manual trigger" as Trigger
|
||||
participant "Gitea Actions\npublish-wiki" as Workflow
|
||||
participant "shared-scripts\n(tools/publish_wiki.py at v1)" as Script
|
||||
participant "Gitea wiki API" as Wiki
|
||||
|
||||
Trigger -> Workflow: Start workflow
|
||||
activate Workflow
|
||||
Workflow -> Script: Check out the repository and the script, run it
|
||||
activate Script
|
||||
|
||||
alt wiki/.publish does not exist
|
||||
Script --> Workflow: Log that publishing is not enabled and succeed\n(nothing is written)
|
||||
else wiki/ has no Markdown pages
|
||||
Script --> Workflow: Fail with [configuration]\n(an empty wiki/ never deletes pages)
|
||||
else
|
||||
Script -> Script: Read the marker (empty, or the word prune)\nand TOKEN_FOR_GITEA_WIKI
|
||||
Script -> Wiki: GET repository (preflight)
|
||||
Wiki --> Script: Wiki is enabled, token accepted
|
||||
Script -> Wiki: GET pages
|
||||
Wiki --> Script: Existing pages
|
||||
Script -> Wiki: Create new pages, update changed pages
|
||||
opt marker says prune
|
||||
Script -> Wiki: Delete pages that are not in wiki/
|
||||
end
|
||||
Script --> Workflow: Log created, updated and deleted counts
|
||||
end
|
||||
deactivate Script
|
||||
Workflow --> Trigger: Workflow result
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Semakan kualiti
|
||||
|
||||
Aliran kerja boleh guna semula untuk Python dan shell, dipanggil dengan `uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1` (lihat [panduan](QualityChecksPythonShell)).
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Shared quality checks (reusable workflow)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Calling repository\nuses: ...quality-checks.yml@v1" as Caller
|
||||
participant "Gitea Actions\nquality-checks" as Workflow
|
||||
participant "PyPI" as PyPI
|
||||
|
||||
Caller -> Workflow: workflow_call with languages,\nworking-directory and tool versions
|
||||
activate Workflow
|
||||
|
||||
Workflow -> Workflow: Validate the inputs
|
||||
alt languages or working-directory is invalid
|
||||
Workflow --> Caller: Fail with [configuration]
|
||||
end
|
||||
|
||||
Workflow -> Workflow: Check out the calling repository
|
||||
Workflow -> PyPI: Install the pinned tools in a virtual environment\n(ruff, mypy, shellcheck-py, shfmt-py as selected)
|
||||
PyPI --> Workflow: Tools installed
|
||||
|
||||
loop for each selected language
|
||||
Workflow -> Workflow: List tracked files
|
||||
alt no files of that language
|
||||
Workflow -> Workflow: Notice: nothing was checked
|
||||
else
|
||||
Workflow -> Workflow: Run every tool and record PASS or FAIL
|
||||
end
|
||||
end
|
||||
|
||||
alt any tool failed
|
||||
Workflow --> Caller: Fail and list the failed tools
|
||||
else
|
||||
Workflow --> Caller: All selected checks passed
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Semakan kualiti C++
|
||||
|
||||
Aliran kerja boleh guna semula untuk C dan C++, dipanggil dengan `uses: TirSystem/github-action/.gitea/workflows/quality-checks-cpp.yml@v1` (ADR-0008). Repositori mesti mempunyai `.clang-format`; `.clang-tidy` dan pangkalan data kompilasi adalah pilihan.
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Shared quality checks for C and C++ (reusable workflow)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Calling repository\nuses: ...quality-checks-cpp.yml@v1" as Caller
|
||||
participant "Gitea Actions\nquality-checks-cpp" as Workflow
|
||||
participant "PyPI" as PyPI
|
||||
|
||||
Caller -> Workflow: workflow_call with working-directory, std,\ncompile-commands-dir and tool versions
|
||||
activate Workflow
|
||||
|
||||
Workflow -> Workflow: Check out the caller and the shared script
|
||||
Workflow -> Workflow: Validate the inputs
|
||||
alt an input is invalid or a version is not exact
|
||||
Workflow --> Caller: Fail with [configuration]
|
||||
end
|
||||
|
||||
Workflow -> PyPI: Install clang-format and clang-tidy at the exact versions
|
||||
PyPI --> Workflow: Tools installed
|
||||
|
||||
alt no C or C++ file is tracked
|
||||
Workflow --> Caller: Notice: nothing was checked, pass
|
||||
else no .clang-format, or compile-commands-dir\nwithout compile_commands.json
|
||||
Workflow --> Caller: Fail with [configuration]
|
||||
else
|
||||
Workflow -> Workflow: clang-format --dry-run -Werror on all files
|
||||
Workflow -> Workflow: clang-tidy on the C++ files (-std=std)\nand on the C files (or with the compile database)
|
||||
alt any tool failed
|
||||
Workflow --> Caller: Fail with tool, file and line in the log
|
||||
else
|
||||
Workflow --> Caller: All selected checks passed
|
||||
end
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Semakan kualiti C#
|
||||
|
||||
Aliran kerja boleh guna semula untuk C#, dipanggil dengan `uses: TirSystem/github-action/.gitea/workflows/quality-checks-csharp.yml@v1` (ADR-0008). Ia memasang .NET SDK tepat yang diberikan oleh `dotnet-sdk-version` (10 atau lebih baharu) dan memerlukan rangkaian untuk pemulihan pakej.
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Shared quality checks for C# (reusable workflow)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Calling repository\nuses: ...quality-checks-csharp.yml@v1" as Caller
|
||||
participant "Gitea Actions\nquality-checks-csharp" as Workflow
|
||||
participant "dot.net\n(dotnet-install.sh)" as DotNet
|
||||
|
||||
Caller -> Workflow: workflow_call with working-directory,\nproject and dotnet-sdk-version
|
||||
activate Workflow
|
||||
|
||||
Workflow -> Workflow: Check out the caller and the shared script
|
||||
Workflow -> Workflow: Validate the inputs
|
||||
alt an input is invalid or the SDK is not an exact\nstable version 10 or later
|
||||
Workflow --> Caller: Fail with [configuration]
|
||||
end
|
||||
|
||||
Workflow -> DotNet: Install the exact .NET SDK version
|
||||
DotNet --> Workflow: SDK installed
|
||||
|
||||
alt no C# file is tracked
|
||||
Workflow --> Caller: Notice: nothing was checked, pass
|
||||
else no solution or project, or several without the project input
|
||||
Workflow --> Caller: Fail with [configuration] that names them
|
||||
else
|
||||
Workflow -> Workflow: dotnet format --verify-no-changes
|
||||
Workflow -> Workflow: dotnet build -warnaserror\n(package restore needs the network)
|
||||
alt any tool failed
|
||||
Workflow --> Caller: Fail with tool, file and line in the log
|
||||
else
|
||||
Workflow --> Caller: All selected checks passed
|
||||
end
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Keluaran
|
||||
|
||||
Dimulakan secara manual oleh penyelenggara; dengan `dry_run` `true` (lalai) ia hanya menyemak (lihat [proses keluaran](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/release-process.md)).
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Release this repository
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Maintainer\n(workflow_dispatch: version, dry_run)" as Trigger
|
||||
participant "Gitea Actions\nrelease" as Workflow
|
||||
participant "Gitea REST API" as Gitea
|
||||
|
||||
Trigger -> Workflow: Start with version and dry_run
|
||||
activate Workflow
|
||||
|
||||
Workflow -> Workflow: Check the version and read CHANGELOG.md
|
||||
alt version malformed or no changelog entry
|
||||
Workflow --> Trigger: Fail with [validation] or [configuration]
|
||||
end
|
||||
|
||||
Workflow -> Gitea: GET branch main and status of the commit
|
||||
Gitea --> Workflow: Tip of main and the validation run
|
||||
alt commit is not the tip of main,\nor the validation run is not green
|
||||
Workflow --> Trigger: Fail with [validation]\n(no tag is created)
|
||||
end
|
||||
|
||||
Workflow -> Gitea: GET tags
|
||||
Gitea --> Workflow: Existing tags
|
||||
alt tag vMAJOR.MINOR.PATCH exists
|
||||
Workflow --> Trigger: Fail with [validation]\n(tags are never moved)
|
||||
end
|
||||
|
||||
alt dry_run is true (default)
|
||||
Workflow --> Trigger: Log what would be created and stop
|
||||
else
|
||||
Workflow -> Gitea: POST release (creates the version tag,\nbody is the changelog entry)
|
||||
opt this is the highest version of its major
|
||||
Workflow -> Gitea: Delete and recreate the major tag vMAJOR
|
||||
end
|
||||
Workflow --> Trigger: Released
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Menerbitkan halaman wiki
|
||||
|
||||
Aliran kerja boleh guna semula (ADR-0009). Sesebuah repositori memanggilnya daripada aliran kerjanya sendiri, jadi panggilan itu ialah pilihan menyertai dan tiada fail penanda diperlukan. Ia menerbitkan halaman Markdown dalam `wiki_dir` (lalai `docs/wiki`) ke wiki repositori pemanggil, dan memadam halaman yang tiada dalam folder hanya apabila `prune` ialah `true`.
|
||||
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
branches: [ main ]
|
||||
paths: [ "docs/wiki/**" ]
|
||||
jobs:
|
||||
wiki:
|
||||
uses: TirSystem/github-action/.gitea/workflows/publish-wiki-pages.yml@v1
|
||||
secrets:
|
||||
TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
|
||||
```
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Publish docs/wiki to the wiki of the calling repository
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Calling repository\nuses: ...publish-wiki-pages.yml@v1" as Caller
|
||||
participant "Gitea Actions\npublish-wiki-pages" as Workflow
|
||||
participant "shared-scripts\n(tools/publish_wiki.py at tools-ref)" as Script
|
||||
participant "Gitea wiki API" as Wiki
|
||||
|
||||
Caller -> Workflow: Call with wiki_dir, prune and the secret
|
||||
activate Workflow
|
||||
Workflow -> Script: Check out the repository and the script, run it
|
||||
activate Script
|
||||
|
||||
alt wiki_dir does not exist, or has no Markdown pages
|
||||
Script --> Workflow: Fail with [configuration]\n(an empty folder never deletes pages)
|
||||
else
|
||||
Script -> Script: Read prune and TOKEN_FOR_GITEA_WIKI
|
||||
Script -> Wiki: GET repository (preflight)
|
||||
Wiki --> Script: Wiki is enabled, token accepted
|
||||
Script -> Wiki: GET pages
|
||||
Wiki --> Script: Existing pages
|
||||
Script -> Wiki: Create new pages, update changed pages
|
||||
opt prune is true
|
||||
Script -> Wiki: Delete pages that are not in wiki_dir
|
||||
end
|
||||
Script --> Workflow: Log created, updated and deleted counts
|
||||
end
|
||||
deactivate Script
|
||||
Workflow --> Caller: Workflow result
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Menerbitkan wiki sendiri
|
||||
|
||||
Wiki repositori ini ialah `docs/wiki/`. Aliran kerja ini memanggil aliran kerja boleh guna semula di atas melalui laluan tempatannya, dengan `prune` ditetapkan kepada `true` supaya wiki sentiasa sama dengan folder dan `tools-ref` ditetapkan kepada `main` supaya skrip daripada commit yang sama dijalankan. Ia ialah pemanggil yang disalin oleh projek daripada `templates/ci/publish-wiki.yml` framework.
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Publish the wiki of this repository (docs/wiki)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Push to main that changes docs/wiki/**,\nor manual trigger" as Trigger
|
||||
participant "Gitea Actions\npublish-own-wiki" as Caller
|
||||
participant "Gitea Actions\npublish-wiki-pages\n(called by its local path)" as Workflow
|
||||
participant "Gitea wiki API" as Wiki
|
||||
|
||||
Trigger -> Caller: Start workflow
|
||||
activate Caller
|
||||
Caller -> Workflow: Call with wiki_dir docs/wiki, prune true,\ntools-ref main and TOKEN_FOR_GITEA_WIKI
|
||||
activate Workflow
|
||||
Workflow -> Wiki: Create, update and delete pages\nso the wiki equals docs/wiki
|
||||
Wiki --> Workflow: Done
|
||||
Workflow --> Caller: Workflow result
|
||||
deactivate Workflow
|
||||
Caller --> Trigger: Workflow result
|
||||
deactivate Caller
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Menerbitkan milestone yang diterima
|
||||
|
||||
Kebenaran tetap untuk menerbitkan: pada push ke `main` yang mengubah milestone atau semakannya, setiap milestone yang baris terkini Version History-nya Accepted dan semakan terkininya Go dicipta atau dikemas kini di Gitea dengan tugasnya sebagai isu. Tiada apa-apa ditutup atau dipadam. Larian manual ialah larian percubaan kecuali `dry_run` dimatikan. Ia menggunakan secret `TOKEN_FOR_GITEA` dan peraturan `--accepted-only` framework yang dipasang (v0.5.0 atau lebih baharu).
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Publish accepted milestones (this repository)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Push to main that changes\ndocs/milestones/** or docs/sqa/reviews/**,\nor manual trigger" as Trigger
|
||||
participant "Gitea Actions\nsync-milestones" as Workflow
|
||||
participant "framework/scripts/\nsync-project.sh" as Script
|
||||
participant "Gitea REST API" as Gitea
|
||||
|
||||
Trigger -> Workflow: Start workflow
|
||||
activate Workflow
|
||||
Workflow -> Workflow: Check out the project and the framework\nsubmodules over HTTPS with TOKEN_FOR_GITEA
|
||||
Workflow -> Script: --accepted-only (dry run)\nor --accepted-only --apply
|
||||
activate Script
|
||||
|
||||
loop for each docs/milestones/mil-*.md
|
||||
alt latest Version History row is not Accepted,\nor the latest review record is not a Go
|
||||
Script -> Script: Skip with the reason on stderr
|
||||
else
|
||||
alt dry run
|
||||
Script -> Script: Print the plan, no network call
|
||||
else
|
||||
Script -> Gitea: Create or update the Milestone\nand one Issue per task row
|
||||
Gitea --> Script: Milestone and issue numbers
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
note right of Script
|
||||
Nothing is closed or deleted.
|
||||
Each real run edits the issues
|
||||
of every accepted milestone.
|
||||
end note
|
||||
Script --> Workflow: Done, or "nothing to publish"
|
||||
deactivate Script
|
||||
Workflow --> Trigger: Workflow result
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Mengesahkan aliran kerja
|
||||
|
||||
Pengesahan repositori sendiri: ujian luar talian yang menjadi syarat bagi setiap pull request.
|
||||
|
||||
#### Aliran kerja
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
title Validate workflows (this repository's own checks)
|
||||
|
||||
autonumber
|
||||
|
||||
actor "Pull request,\npush to main, or manual trigger" as Trigger
|
||||
participant "Gitea Actions\nvalidate-workflows" as Workflow
|
||||
|
||||
Trigger -> Workflow: Start workflow
|
||||
activate Workflow
|
||||
Workflow -> Workflow: Check out the repository
|
||||
Workflow -> Workflow: Create a virtual environment and\ninstall tests/requirements.txt
|
||||
Workflow -> Workflow: Run pytest on tests/ under coverage (offline, no secrets):\nworkflows parse as YAML, no embedded Python,\nscripts compile, wiki pages and translations are current,\nsync, publish and release flows against a fake API
|
||||
|
||||
alt a test fails
|
||||
Workflow --> Trigger: Workflow fails (the pull request is not ready)
|
||||
else
|
||||
Workflow --> Trigger: Workflow succeeds
|
||||
end
|
||||
deactivate Workflow
|
||||
@enduml
|
||||
```
|
||||
|
||||
|
||||
## Keperluan
|
||||
|
||||
- Satu instans Gitea dengan Actions diaktifkan dan satu runner yang menyediakan `ubuntu-latest` dengan `python3`
|
||||
- Satu push mirror GitHub yang dikonfigurasi pada repositori Gitea (paling banyak satu; repositori tanpa cermin dilangkau dengan jayanya)
|
||||
- Rahsia (secret) repositori:
|
||||
- `TOKEN_FOR_GITEA`: token API Gitea (token sahaja, tanpa JSON)
|
||||
- `PAT_FOR_GITHUB`: personal access token GitHub yang dibenarkan mengubah suai repositori cermin (token sahaja, tanpa JSON)
|
||||
- `TOKEN_FOR_GITEA_WIKI` (hanya untuk repositori yang menerbitkan wiki, lihat [panduan menyertakan repositori](Onboarding.ms)): token Gitea yang boleh menulis ke wiki, disimpan sebagai secret organisasi repositori; tiada sandaran kepada `TOKEN_FOR_GITEA`
|
||||
|
||||
|
||||
## Persediaan
|
||||
|
||||
Tiada kebergantungan perlu dipasang; aliran kerja hanya menggunakan pustaka standard Python.
|
||||
|
||||
1. Klon repositori:
|
||||
```bash
|
||||
git clone ssh://git@git.tirsystem.com:10022/TirSystem/github-action.git
|
||||
```
|
||||
2. Tambah rahsia yang disenaraikan di bawah [Keperluan](#keperluan) ke tetapan repositori dalam Gitea.
|
||||
3. Konfigurasikan push mirror GitHub dalam tetapan repositori.
|
||||
|
||||
|
||||
## Jalankan
|
||||
|
||||
Aliran kerja berjalan secara automatik pada push ke `main` dan mengikut jadual harian. Untuk menjalankannya secara manual, cetuskan **Sync GitHub mirror metadata** melalui `workflow_dispatch` dari tab Actions dalam Gitea.
|
||||
|
||||
|
||||
## Ujian
|
||||
|
||||
Fail aliran kerja dan skrip dalam `tools/` disahkan oleh ujian luar talian yang tidak memerlukan akses rangkaian dan tidak memerlukan rahsia:
|
||||
|
||||
```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 coverage run -m pytest -q tests
|
||||
python -m coverage report
|
||||
```
|
||||
|
||||
Semakan yang sama dijalankan pada setiap pull request dan setiap push ke `main` melalui [`validate-workflows.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/validate-workflows.yml). Semakan itu menghurai setiap aliran kerja sebagai YAML, memastikan tiada yang menanam Python, mengkompil skrip dalam `tools/`, memerlukan kebenaran kerja yang jelas, dan menguji penghuraian kelayakan (credentials), penghuraian alamat push mirror serta aliran penyegerakan dan penerbitan terhadap API palsu. Larian gagal apabila liputan baris dan cabang `tools/` di bawah 95% (`.coveragerc`).
|
||||
|
||||
Selepas perubahan pada aliran kerja penyegerakan, cetuskan juga **Sync GitHub mirror metadata** secara manual dalam Gitea dan bandingkan penerangan dan topik pada cermin GitHub.
|
||||
@@ -0,0 +1,85 @@
|
||||
<!-- translation of Onboarding.md, source sha256 4de4897fb3b7 -->
|
||||
|
||||
> Dette er en oversættelse af [`Onboarding`](Onboarding). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
|
||||
|
||||
[English](Onboarding) | Dansk | [Bahasa Melayu](Onboarding.ms)
|
||||
|
||||
# Tilslutning af et repository
|
||||
|
||||
Sådan får en DevOps-professionel et TirSystem-repository til at bruge det fælles workflow **Sync GitHub mirror metadata**, og hvilke runners det kræver. Kun dette workflow findes i dag; workflows til kvalitetskontrol og udgivelse er planlagt (se [projektplanen](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/docs/project-plan.md)).
|
||||
|
||||
## Hvad er verificeret
|
||||
|
||||
| Punkt | Status |
|
||||
| --- | --- |
|
||||
| Gitea-version | 1.27.3 |
|
||||
| `.gitea/scoped_workflows/sync-github-metadata.yml` kører i dette repository | Verificeret: kørsel 16, `workflow_dispatch`, gennemført |
|
||||
| Samme workflow gælder automatisk for andre repositories | Verificeret 2026-10-10: det kørte, uden en kopi i repositoryet, i repositories i `TirSystem`, `TirSystem-BashScript`, `vl-staal` og `Tirsvad-Udemy-100-days-of-code` (fx `TirSystem/sqa-qc-checklists` og `TirSystem-BashScript/RepoFoundry`). Scriptet, det kørte, ændrede sig, når dette repositorys script ændrede sig. |
|
||||
|
||||
Leveringen er automatisk, så et repository behøver ingen kopi af workflowet. Secrets deles ikke mellem organisationer: hver organisation skal have sine egne (trin 3).
|
||||
|
||||
## Trin
|
||||
|
||||
1. **Kontroller forudsætningerne** i repositoryet: Actions er aktiveret, og en runner med labelen `ubuntu-latest` og `python3` er online (se [Runners](#runners)).
|
||||
2. **Konfigurer ét GitHub push-spejl** i repositoryets indstillinger (Settings, Repository, Mirror settings, Push mirror). Workflowet fejler, hvis der er flere GitHub-spejle. Hvis der ingen er, lykkes det uden at synkronisere noget.
|
||||
3. **Tilføj de to secrets** i repositoryets (eller organisationens) indstillinger med de scopes, der står i [credentials.md](Credentials.da). Workflowet kører i alle organisationens repositories, så gem secrets én gang pr. organisation; et repository i en anden organisation kan ikke se dem:
|
||||
- `TOKEN_FOR_GITEA`
|
||||
- `PAT_FOR_GITHUB` (kun GitHub-tokenet)
|
||||
4. **Lever workflowet:** scoped workflows gælder for alle repositories på denne instans, så der er intet at kopiere. Kun hvor scoped levering ikke er sat op, kopieres `.gitea/scoped_workflows/sync-github-metadata.yml` fra dette repository til `.gitea/workflows/` i mål-repositoryet; fastlås kopien til en gennemgået version, og kopier igen, når den ændres.
|
||||
5. **Angiv en beskrivelse og emner** på Gitea-repositoryet, så der er noget at synkronisere.
|
||||
6. **Kør det én gang manuelt:** Actions, **Sync GitHub mirror metadata**, Run workflow. Loggen skal slutte med `Synced description and topics to <owner>/<repo>.`, og GitHub-repositoryet skal vise samme beskrivelse og emner.
|
||||
7. Hvis det fejler, brug [troubleshooting.md](Troubleshooting.da).
|
||||
|
||||
## Publicér en wiki (valgfrit)
|
||||
|
||||
Det genbrugelige workflow **Publish wiki pages** kopierer Markdown-siderne i `docs/wiki/` til repositoryets wiki, når en ændring af `docs/wiki/` flettes til `main`. Repositoryet kalder det, så der skrives intet, hvor der ikke findes et kald. Wikien findes som minimum på engelsk og på produktejerens sprog.
|
||||
|
||||
1. Aktivér wikien i repositoryets indstillinger.
|
||||
2. Tilføj Markdown-sider til `docs/wiki/`. Filnavnet er sidens navn: `Home.md` er forsiden. En bindestreg i navnet er et mellemrum i sidens navn: `Home-da.md` er siden "Home da", og et link til den er `[Dansk](Home-da)`.
|
||||
3. Tilføj et workflow, for eksempel `.gitea/workflows/publish-wiki.yml`, der kalder det genbrugelige workflow:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
branches: [ main ]
|
||||
paths: [ "docs/wiki/**" ]
|
||||
jobs:
|
||||
wiki:
|
||||
uses: TirSystem/github-action/.gitea/workflows/publish-wiki-pages.yml@v1
|
||||
with:
|
||||
prune: "true"
|
||||
secrets:
|
||||
TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
|
||||
```
|
||||
|
||||
`wiki_dir` er som standard `docs/wiki`. `prune: "true"` sletter også wiki-sider, der ikke findes i mappen, så wikien altid er lig med mappen; standarden `false` beholder dem.
|
||||
4. Gem `TOKEN_FOR_GITEA_WIKI` som en secret i repositoryets organisation med det scope, der står i [credentials.md](Credentials.da).
|
||||
5. Flet ændringen til `main`. Loggen skal slutte med `Published <n> page(s) to the wiki of <owner>/<repo>`.
|
||||
|
||||
Et repository, der stadig har markøren `wiki/.publish`, publiceres af det ældre scoped workflow, som fjernes, når alle repositories har et kald. Flyt siderne til `docs/wiki/` og tilføj kaldet, før det sker.
|
||||
|
||||
## Runners
|
||||
|
||||
| Punkt | Værdi |
|
||||
| --- | --- |
|
||||
| Label, som workflowet bruger | `ubuntu-latest` |
|
||||
| Labels, som runneren på denne instans tilbyder | `ubuntu-latest`, `ubuntu-24.04`, `ubuntu-22.04` |
|
||||
| Værktøjer, workflowet skal bruge | `python3` (kun standardbiblioteket), udgående HTTPS til Gitea API og `api.github.com` |
|
||||
| Kræves af `actions/checkout` (bruges af valideringsworkflowet) | `git` og Node.js, normalt i runner-imaget |
|
||||
|
||||
**Kontroller, at en passende runner er online** (kræver tilladelse til at se runners):
|
||||
|
||||
```bash
|
||||
curl -s -H "Authorization: token $GITEA_TOKEN" \
|
||||
https://git.tirsystem.com/api/v1/repos/<owner>/<repo>/actions/runners
|
||||
```
|
||||
|
||||
For runners, der deles af hele instansen, bruger en administrator `/api/v1/admin/actions/runners`. På skrivetidspunktet er lister for repository og organisation tomme, og én runner på instansniveau (`36cd20104923`) er `online`.
|
||||
|
||||
**Offline eller inkompatibel runner**
|
||||
|
||||
| Symptom | Sandsynlig årsag | Handling |
|
||||
| --- | --- | --- |
|
||||
| Kørslen bliver stående som `waiting` | Ingen online runner har den label, der står i `runs-on` | Start runneren, eller registrer én med labelen |
|
||||
| Jobbet fejler i starten med en manglende kommando | Runner-imaget mangler `python3`, `git` eller Node.js | Brug et image, der har dem |
|
||||
| Jobbet kan ikke nå API'et | Runneren har ingen udgående HTTPS | Ret runnerens netværks- eller proxyindstillinger |
|
||||
@@ -0,0 +1,119 @@
|
||||
<!-- 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.
|
||||
|
||||
English | [Dansk](Onboarding.da) | [Bahasa Melayu](Onboarding.ms)
|
||||
|
||||
# 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 | 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). 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).
|
||||
|
||||
## Publish a wiki (optional)
|
||||
|
||||
The reusable workflow **Publish wiki pages** copies the Markdown pages in
|
||||
`docs/wiki/` to the repository wiki when a change to `docs/wiki/` is merged to
|
||||
`main`. The repository calls it, so nothing is written where no call exists.
|
||||
The wiki has English and the product owner's language as a minimum.
|
||||
|
||||
1. Enable the wiki in the repository settings.
|
||||
2. Add Markdown pages to `docs/wiki/`. The file name is the page name: `Home.md`
|
||||
is the home page. A hyphen in the name is a space in the page name:
|
||||
`Home-da.md` is the page "Home da", and a link to it is `[Dansk](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/Home-da)`.
|
||||
3. Add a workflow, for example `.gitea/workflows/publish-wiki.yml`, that calls
|
||||
the reusable workflow:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
branches: [ main ]
|
||||
paths: [ "docs/wiki/**" ]
|
||||
jobs:
|
||||
wiki:
|
||||
uses: TirSystem/github-action/.gitea/workflows/publish-wiki-pages.yml@v1
|
||||
with:
|
||||
prune: "true"
|
||||
secrets:
|
||||
TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
|
||||
```
|
||||
|
||||
`wiki_dir` defaults to `docs/wiki`. `prune: "true"` also deletes wiki pages
|
||||
that are not in the folder, so the wiki always equals the folder; the
|
||||
default `false` keeps them.
|
||||
4. Store `TOKEN_FOR_GITEA_WIKI` as a secret of the repository's organization,
|
||||
using the scope in [credentials.md](Credentials).
|
||||
5. Merge the change to `main`. The log must end with `Published <n> page(s) to
|
||||
the wiki of <owner>/<repo>`.
|
||||
|
||||
A repository that still has the marker `wiki/.publish` is published by the
|
||||
older scoped workflow, which is removed once every repository has a call.
|
||||
Move the pages to `docs/wiki/` and add the call before that.
|
||||
|
||||
## 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 |
|
||||
@@ -0,0 +1,85 @@
|
||||
<!-- translation of Onboarding.md, source sha256 4de4897fb3b7 -->
|
||||
|
||||
> Ini ialah terjemahan [`Onboarding`](Onboarding). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
|
||||
|
||||
[English](Onboarding) | [Dansk](Onboarding.da) | Bahasa Melayu
|
||||
|
||||
# Menyertakan sebuah repositori
|
||||
|
||||
Cara seorang profesional DevOps menjadikan repositori TirSystem menggunakan aliran kerja bersama **Sync GitHub mirror metadata**, dan runner yang diperlukannya. Hanya aliran kerja ini yang wujud sekarang; aliran kerja semakan kualiti dan keluaran dirancang (lihat [Pelan Projek](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/docs/project-plan.md)).
|
||||
|
||||
## Perkara yang telah disahkan
|
||||
|
||||
| Perkara | Status |
|
||||
| --- | --- |
|
||||
| Versi Gitea | 1.27.3 |
|
||||
| `.gitea/scoped_workflows/sync-github-metadata.yml` berjalan dalam repositori ini | Disahkan: larian 16, `workflow_dispatch`, berjaya |
|
||||
| Aliran kerja yang sama terpakai pada repositori lain secara automatik | Disahkan pada 2026-10-10: ia berjalan, tanpa salinan dalam repositori, dalam repositori `TirSystem`, `TirSystem-BashScript`, `vl-staal` dan `Tirsvad-Udemy-100-days-of-code` (contohnya `TirSystem/sqa-qc-checklists` dan `TirSystem-BashScript/RepoFoundry`). Skrip yang dijalankannya berubah apabila skrip repositori ini berubah. |
|
||||
|
||||
Penghantaran adalah automatik, jadi repositori tidak memerlukan salinan aliran kerja. Rahsia (secret) tidak dikongsi antara organisasi: setiap organisasi memerlukan rahsianya sendiri (langkah 3).
|
||||
|
||||
## Langkah
|
||||
|
||||
1. **Semak prasyarat** dalam repositori: Actions diaktifkan, dan runner dengan label `ubuntu-latest` dan `python3` berada dalam talian (lihat [Runners](#runners)).
|
||||
2. **Konfigurasikan satu push mirror GitHub** dalam tetapan repositori (Settings, Repository, Mirror settings, Push mirror). Aliran kerja gagal jika terdapat beberapa cermin GitHub. Jika tiada, ia berjaya tanpa menyegerakkan apa-apa.
|
||||
3. **Tambah dua rahsia (secret)** dalam tetapan repositori (atau organisasi), dengan skop yang tertera dalam [credentials.md](Credentials.ms). Aliran kerja berjalan dalam setiap repositori sesebuah organisasi, jadi simpan rahsia sekali bagi setiap organisasi; repositori dalam organisasi lain tidak melihatnya:
|
||||
- `TOKEN_FOR_GITEA`
|
||||
- `PAT_FOR_GITHUB` (token GitHub sahaja)
|
||||
4. **Hantar aliran kerja:** scoped workflow terpakai pada setiap repositori dalam instans ini, jadi tiada apa yang perlu disalin. Hanya jika penghantaran scoped tidak disediakan, salin `.gitea/scoped_workflows/sync-github-metadata.yml` dari repositori ini ke `.gitea/workflows/` dalam repositori sasaran, sematkan salinan itu pada versi yang telah disemak dan salin semula apabila ia berubah.
|
||||
5. **Tetapkan penerangan dan topik** pada repositori Gitea, supaya ada sesuatu untuk disegerakkan.
|
||||
6. **Jalankan sekali secara manual:** Actions, **Sync GitHub mirror metadata**, Run workflow. Log mesti berakhir dengan `Synced description and topics to <owner>/<repo>.` dan repositori GitHub mesti menunjukkan penerangan dan topik yang sama.
|
||||
7. Jika gagal, gunakan [troubleshooting.md](Troubleshooting.ms).
|
||||
|
||||
## Menerbitkan wiki (pilihan)
|
||||
|
||||
Aliran kerja boleh guna semula **Publish wiki pages** menyalin halaman Markdown dalam `docs/wiki/` ke wiki repositori apabila perubahan pada `docs/wiki/` digabungkan ke `main`. Repositori memanggilnya, jadi tiada apa-apa ditulis di tempat yang tiada panggilan. Wiki ada dalam bahasa Inggeris dan bahasa pemilik produk sekurang-kurangnya.
|
||||
|
||||
1. Aktifkan wiki dalam tetapan repositori.
|
||||
2. Tambah halaman Markdown ke `docs/wiki/`. Nama fail ialah nama halaman: `Home.md` ialah halaman utama. Tanda sempang dalam nama ialah ruang dalam nama halaman: `Home-da.md` ialah halaman "Home da", dan pautan kepadanya ialah `[Dansk](Home-da)`.
|
||||
3. Tambah aliran kerja, contohnya `.gitea/workflows/publish-wiki.yml`, yang memanggil aliran kerja boleh guna semula:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
branches: [ main ]
|
||||
paths: [ "docs/wiki/**" ]
|
||||
jobs:
|
||||
wiki:
|
||||
uses: TirSystem/github-action/.gitea/workflows/publish-wiki-pages.yml@v1
|
||||
with:
|
||||
prune: "true"
|
||||
secrets:
|
||||
TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
|
||||
```
|
||||
|
||||
`wiki_dir` lalai ialah `docs/wiki`. `prune: "true"` turut memadam halaman wiki yang tiada dalam folder itu, supaya wiki sentiasa sama dengan folder; lalai `false` mengekalkannya.
|
||||
4. Simpan `TOKEN_FOR_GITEA_WIKI` sebagai secret organisasi repositori, dengan skop yang tertera dalam [credentials.md](Credentials.ms).
|
||||
5. Gabungkan perubahan ke `main`. Log mesti berakhir dengan `Published <n> page(s) to the wiki of <owner>/<repo>`.
|
||||
|
||||
Repositori yang masih mempunyai penanda `wiki/.publish` diterbitkan oleh aliran kerja scoped yang lebih lama, yang dibuang apabila setiap repositori mempunyai panggilan. Alihkan halaman ke `docs/wiki/` dan tambah panggilan sebelum itu.
|
||||
|
||||
## Runners
|
||||
|
||||
| Perkara | Nilai |
|
||||
| --- | --- |
|
||||
| Label yang digunakan oleh aliran kerja | `ubuntu-latest` |
|
||||
| Label yang ditawarkan oleh runner pada instans ini | `ubuntu-latest`, `ubuntu-24.04`, `ubuntu-22.04` |
|
||||
| Alat yang diperlukan oleh aliran kerja | `python3` (pustaka standard sahaja), HTTPS keluar ke API Gitea dan `api.github.com` |
|
||||
| Diperlukan untuk `actions/checkout` (digunakan oleh aliran kerja pengesahan) | `git` dan Node.js, biasanya terdapat dalam imej runner |
|
||||
|
||||
**Semak bahawa runner yang sesuai berada dalam talian** (memerlukan kebenaran untuk melihat runner):
|
||||
|
||||
```bash
|
||||
curl -s -H "Authorization: token $GITEA_TOKEN" \
|
||||
https://git.tirsystem.com/api/v1/repos/<owner>/<repo>/actions/runners
|
||||
```
|
||||
|
||||
Bagi runner yang dikongsi oleh seluruh instans, pentadbir menggunakan `/api/v1/admin/actions/runners`. Pada masa penulisan, senarai repositori dan organisasi kosong dan satu runner peringkat instans (`36cd20104923`) berstatus `online`.
|
||||
|
||||
**Runner luar talian atau tidak serasi**
|
||||
|
||||
| Gejala | Punca yang mungkin | Tindakan |
|
||||
| --- | --- | --- |
|
||||
| Larian kekal `waiting` | Tiada runner dalam talian yang mempunyai label dalam `runs-on` | Mulakan runner, atau daftarkan satu dengan label itu |
|
||||
| Kerja gagal pada permulaan dengan arahan yang tiada | Imej runner tiada `python3`, `git` atau Node.js | Gunakan imej yang mempunyainya |
|
||||
| Kerja tidak dapat mencapai API | Runner tiada HTTPS keluar | Betulkan tetapan rangkaian atau proksi runner |
|
||||
@@ -0,0 +1,85 @@
|
||||
<!-- translation of QualityChecksCSharp.md, source sha256 36e34031e0b9 -->
|
||||
|
||||
> Dette er en oversættelse af [`QualityChecksCSharp`](QualityChecksCSharp). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
|
||||
|
||||
[English](QualityChecksCSharp) | Dansk | [Bahasa Melayu](QualityChecksCSharp.ms)
|
||||
|
||||
# Aflæsning af resultater fra kvalitetskontrol af C#
|
||||
|
||||
Sådan kalder en softwareudvikler den fælles kvalitetskontrol af C#, aflæser en mislykket kørsel og får den til at bestå. Workflowet kontrollerer formateringen og bygger en solution eller et projekt med advarsler som fejl, på et præcist .NET SDK i version 10 eller nyere, ændrer ingen fil og kræver ingen secret. Dets kontrakt er ADR-0008 i dette repository.
|
||||
|
||||
## Kald af workflowet
|
||||
|
||||
```yaml
|
||||
name: Quality C#
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
quality:
|
||||
permissions:
|
||||
contents: read
|
||||
uses: TirSystem/github-action/.gitea/workflows/quality-checks-csharp.yml@v1
|
||||
with:
|
||||
project: src/App.sln
|
||||
```
|
||||
|
||||
| Input | Standard | Betydning |
|
||||
| --- | --- | --- |
|
||||
| `working-directory` | `.` | Mappe, relativt til repositoryets rod, hvis filer kontrolleres |
|
||||
| `project` | tom | Solution- eller projektfil, relativt til `working-directory`; tom bruger den eneste sporede `*.sln` eller `*.slnx`, ellers den eneste `*.csproj`, der er sporet dér |
|
||||
| `dotnet-sdk-version` | `10.0.401` | Præcis version af .NET SDK, 10 eller nyere; en kanal som `10.0`, et interval og en version under 10 afvises |
|
||||
| `tools-ref` | `v1` | Tag eller gren i `TirSystem/github-action`, hvorfra scriptet `tools/quality-checks-csharp.sh` hentes |
|
||||
|
||||
Henvis til workflowet ved major-tagget (`@v1`) eller et præcist tag, aldrig ved `main`. Et kald ved et præcist tag er kun fuldt fastlåst, når `tools-ref` angiver samme tag. Se opgraderingsvejledningen. SDK-versionen er præcis: at hæve standardværdien er en ny udgivelse af dette repository, ikke en stille ændring.
|
||||
|
||||
## Hvad repositoryet skal have
|
||||
|
||||
- En solution eller et projekt, der bygger med SDK'et. Flere kandidater kræver inputtet `project`; C#-filer uden solution eller projekt fejler med `[configuration]`.
|
||||
- Netværk: `dotnet format` og `dotnet build` gendanner projektets NuGet-pakker i kørslen.
|
||||
- Regler i `.editorconfig` (og de analysatorer, projektet slår til, for eksempel med `AnalysisLevel` og `EnforceCodeStyleInBuild`) afgør, hvad et fund er.
|
||||
|
||||
## Hvad der kontrolleres
|
||||
|
||||
| Filer | Værktøj | Hvad det melder |
|
||||
| --- | --- | --- |
|
||||
| solutionen eller projektet | `dotnet format --verify-no-changes` | formatering og stil, der afviger fra `.editorconfig` |
|
||||
| det samme | `dotnet build -warnaserror` | compiler- og analysatoradvarsler, som får bygningen til at fejle |
|
||||
|
||||
Usporede filer kontrolleres ikke. Et repository uden `*.cs`-filer består med en bemærkning. Projektets tests køres ikke.
|
||||
|
||||
## Aflæsning af en kørsel
|
||||
|
||||
1. Åbn statuskontrollen på pull requesten og derefter jobbet `quality-checks-csharp`.
|
||||
2. Hvert værktøj har sin egen logggruppe. Begge kører, selv om det første fejlede, så én kørsel viser alle fund.
|
||||
3. Et værktøj ender med `PASS <værktøj>` eller `FAIL <værktøj>`; sidste linje i en mislykket kørsel nævner dem: `Quality checks failed: dotnet format --verify-no-changes`.
|
||||
4. Et fund skrives af værktøjet selv som `path(line,column): CODE message`. Stien er absolut i runnerens arbejdsområde (`/workspace/<owner>/<repo>/src/Program.cs(8,27)`).
|
||||
|
||||
## Typiske fejl og rettelser
|
||||
|
||||
| Værktøj | Hvad loggen viser | Rettelse |
|
||||
| --- | --- | --- |
|
||||
| `dotnet format --verify-no-changes` | `Program.cs(12,5): error WHITESPACE: Fix whitespace formatting` | Kør `dotnet format <projekt>`, og commit |
|
||||
| `dotnet build -warnaserror` | `CS8602: Dereference of a possibly null reference` | Ret koden (null-kontrol); undertryk ikke advarslen uden en begrundelse |
|
||||
| `dotnet build -warnaserror` | `IDE0005: Using directive is unnecessary` | Fjern direktivet |
|
||||
|
||||
For at gentage en kørsel på din egen maskine skal du bruge samme SDK:
|
||||
|
||||
```bash
|
||||
dotnet --version # 10.0.401
|
||||
dotnet format src/App.sln --verify-no-changes
|
||||
dotnet build src/App.sln -warnaserror
|
||||
```
|
||||
|
||||
## Når workflowet selv fejler
|
||||
|
||||
| Meddelelse | Årsag | Rettelse |
|
||||
| --- | --- | --- |
|
||||
| `[configuration] dotnet-sdk-version '<x>' is not an exact stable version 10 or later` | En kanal, et interval, en preview eller en version under 10 | Angiv en præcis version som `10.0.401` |
|
||||
| `[configuration] working-directory must be a relative path inside the repository.` | En absolut sti eller `..` | Brug en sti inde i repositoryet |
|
||||
| `[configuration] C# files exist but no solution or project was found` | Repositoryet har `*.cs`-filer og ingen `*.sln`, `*.slnx` eller `*.csproj` i arbejdsmappen | Tilføj en, eller sæt `working-directory` |
|
||||
| `[configuration] Several solutions or projects were found` | Mere end én kandidat | Sæt inputtet `project` |
|
||||
| Installationstrinnet fejler | `dot.net` eller runnerens netværk kan ikke nås | Kør jobbet igen; se [troubleshooting.md](troubleshooting.md) |
|
||||
@@ -0,0 +1,103 @@
|
||||
<!-- Generated from guides/quality-checks-csharp.md by tools/build_wiki.py. Edit the source, not this page. -->
|
||||
|
||||
> This page is generated from [`guides/quality-checks-csharp.md`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/quality-checks-csharp.md). Changes made here are overwritten the next time the wiki is published.
|
||||
|
||||
English | [Dansk](QualityChecksCSharp.da) | [Bahasa Melayu](QualityChecksCSharp.ms)
|
||||
|
||||
# Reading C# quality-check results
|
||||
|
||||
How a software engineer calls the shared C# quality checks, reads a failed run
|
||||
and makes it pass. The workflow checks the formatting and builds a solution or
|
||||
project with warnings as errors, on an exact .NET SDK of version 10 or later,
|
||||
changes no file and needs no secret. Its contract is ADR-0008 in this
|
||||
repository.
|
||||
|
||||
## Calling the workflow
|
||||
|
||||
```yaml
|
||||
name: Quality C#
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
quality:
|
||||
permissions:
|
||||
contents: read
|
||||
uses: TirSystem/github-action/.gitea/workflows/quality-checks-csharp.yml@v1
|
||||
with:
|
||||
project: src/App.sln
|
||||
```
|
||||
|
||||
| Input | Default | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `working-directory` | `.` | Directory, relative to the repository root, whose files are checked |
|
||||
| `project` | empty | Solution or project file, relative to `working-directory`; empty uses the single `*.sln` or `*.slnx`, else the single `*.csproj`, that is tracked there |
|
||||
| `dotnet-sdk-version` | `10.0.401` | Exact version of the .NET SDK, 10 or later; a channel such as `10.0`, a range and a version below 10 are refused |
|
||||
| `tools-ref` | `v1` | Tag or branch of `TirSystem/github-action` from which the script `tools/quality-checks-csharp.sh` is fetched |
|
||||
|
||||
Reference the workflow at the major tag (`@v1`) or at an exact tag, never at
|
||||
`main`. A call at an exact tag is pinned completely only when `tools-ref` names
|
||||
the same tag. See the upgrade guide. The SDK version is exact: raising the
|
||||
default is a new release of this repository, not a silent change.
|
||||
|
||||
## What the repository needs
|
||||
|
||||
- A solution or project that builds with the SDK. Several candidates need the
|
||||
`project` input; C# files with no solution or project fail with
|
||||
`[configuration]`.
|
||||
- The network: `dotnet format` and `dotnet build` restore the NuGet packages of
|
||||
the project in the run.
|
||||
- Rules in `.editorconfig` (and the analyzers the project enables, for example
|
||||
with `AnalysisLevel` and `EnforceCodeStyleInBuild`) decide what a finding is.
|
||||
|
||||
## What is checked
|
||||
|
||||
| Files | Tool | What it reports |
|
||||
| --- | --- | --- |
|
||||
| the solution or project | `dotnet format --verify-no-changes` | formatting and style that differ from `.editorconfig` |
|
||||
| the same | `dotnet build -warnaserror` | compiler and analyzer warnings, which fail the build |
|
||||
|
||||
Untracked files are not checked. A repository without `*.cs` files passes with
|
||||
a notice. Project tests are not run.
|
||||
|
||||
## Reading a run
|
||||
|
||||
1. Open the status check on the pull request, then the job
|
||||
`quality-checks-csharp`.
|
||||
2. Each tool has its own log group. Both run even when the first failed, so one
|
||||
run shows all findings.
|
||||
3. A tool ends with `PASS <tool>` or `FAIL <tool>`; the last line of a failed
|
||||
run names them:
|
||||
`Quality checks failed: dotnet format --verify-no-changes`.
|
||||
4. A finding is written by the tool itself as `path(line,column): CODE message`.
|
||||
The path is absolute in the workspace of the runner
|
||||
(`/workspace/<owner>/<repo>/src/Program.cs(8,27)`).
|
||||
|
||||
## Typical failures and fixes
|
||||
|
||||
| Tool | What the log shows | Fix |
|
||||
| --- | --- | --- |
|
||||
| `dotnet format --verify-no-changes` | `Program.cs(12,5): error WHITESPACE: Fix whitespace formatting` | Run `dotnet format <project>` and commit |
|
||||
| `dotnet build -warnaserror` | `CS8602: Dereference of a possibly null reference` | Fix the code (null check), do not suppress the warning without a reason |
|
||||
| `dotnet build -warnaserror` | `IDE0005: Using directive is unnecessary` | Remove the directive |
|
||||
|
||||
To reproduce a run on your machine, use the same SDK:
|
||||
|
||||
```bash
|
||||
dotnet --version # 10.0.401
|
||||
dotnet format src/App.sln --verify-no-changes
|
||||
dotnet build src/App.sln -warnaserror
|
||||
```
|
||||
|
||||
## When the workflow itself fails
|
||||
|
||||
| Message | Cause | Fix |
|
||||
| --- | --- | --- |
|
||||
| `[configuration] dotnet-sdk-version '<x>' is not an exact stable version 10 or later` | A channel, a range, a preview or a version below 10 | Give an exact version such as `10.0.401` |
|
||||
| `[configuration] working-directory must be a relative path inside the repository.` | An absolute path or `..` | Use a path inside the repository |
|
||||
| `[configuration] C# files exist but no solution or project was found` | The repository has `*.cs` files and no `*.sln`, `*.slnx` or `*.csproj` in the working directory | Add one, or set `working-directory` |
|
||||
| `[configuration] Several solutions or projects were found` | More than one candidate | Set the input `project` |
|
||||
| The install step fails | `dot.net` or the runner network is unreachable | Re-run the job; see [troubleshooting.md](Troubleshooting) |
|
||||
@@ -0,0 +1,85 @@
|
||||
<!-- translation of QualityChecksCSharp.md, source sha256 36e34031e0b9 -->
|
||||
|
||||
> Ini ialah terjemahan [`QualityChecksCSharp`](QualityChecksCSharp). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
|
||||
|
||||
[English](QualityChecksCSharp) | [Dansk](QualityChecksCSharp.da) | Bahasa Melayu
|
||||
|
||||
# Membaca keputusan semakan kualiti C#
|
||||
|
||||
Cara seorang jurutera perisian memanggil semakan kualiti bersama untuk C#, membaca larian yang gagal dan menjadikannya lulus. Aliran kerja ini menyemak pemformatan dan membina solution atau projek dengan amaran sebagai ralat, pada .NET SDK versi 10 atau lebih baharu yang tepat, tidak mengubah sebarang fail dan tidak memerlukan secret. Kontraknya ialah ADR-0008 dalam repositori ini.
|
||||
|
||||
## Memanggil aliran kerja
|
||||
|
||||
```yaml
|
||||
name: Quality C#
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
quality:
|
||||
permissions:
|
||||
contents: read
|
||||
uses: TirSystem/github-action/.gitea/workflows/quality-checks-csharp.yml@v1
|
||||
with:
|
||||
project: src/App.sln
|
||||
```
|
||||
|
||||
| Input | Lalai | Maksud |
|
||||
| --- | --- | --- |
|
||||
| `working-directory` | `.` | Direktori, relatif kepada akar repositori, yang failnya disemak |
|
||||
| `project` | kosong | Fail solution atau projek, relatif kepada `working-directory`; kosong menggunakan satu-satunya `*.sln` atau `*.slnx` yang dijejaki, jika tiada maka satu-satunya `*.csproj` yang dijejaki di situ |
|
||||
| `dotnet-sdk-version` | `10.0.401` | Versi tepat .NET SDK, 10 atau lebih baharu; saluran seperti `10.0`, julat dan versi di bawah 10 ditolak |
|
||||
| `tools-ref` | `v1` | Tag atau cabang `TirSystem/github-action` tempat skrip `tools/quality-checks-csharp.sh` diambil |
|
||||
|
||||
Rujuk aliran kerja pada tag major (`@v1`) atau pada tag tepat, jangan sekali-kali pada `main`. Panggilan pada tag tepat hanya disematkan sepenuhnya apabila `tools-ref` menamakan tag yang sama. Lihat panduan naik taraf. Versi SDK adalah tepat: menaikkan nilai lalai ialah keluaran baharu repositori ini, bukan perubahan senyap.
|
||||
|
||||
## Apa yang diperlukan oleh repositori
|
||||
|
||||
- Satu solution atau projek yang boleh dibina dengan SDK. Beberapa calon memerlukan input `project`; fail C# tanpa solution atau projek gagal dengan `[configuration]`.
|
||||
- Rangkaian: `dotnet format` dan `dotnet build` memulihkan pakej NuGet projek dalam larian.
|
||||
- Peraturan dalam `.editorconfig` (dan penganalisis yang diaktifkan projek, contohnya dengan `AnalysisLevel` dan `EnforceCodeStyleInBuild`) menentukan apa yang dikira sebagai dapatan.
|
||||
|
||||
## Apa yang disemak
|
||||
|
||||
| Fail | Alat | Apa yang dilaporkan |
|
||||
| --- | --- | --- |
|
||||
| solution atau projek | `dotnet format --verify-no-changes` | pemformatan dan gaya yang berbeza daripada `.editorconfig` |
|
||||
| yang sama | `dotnet build -warnaserror` | amaran pengkompil dan penganalisis, yang menggagalkan binaan |
|
||||
|
||||
Fail yang tidak dijejaki tidak disemak. Repositori tanpa fail `*.cs` lulus dengan satu notis. Ujian projek tidak dijalankan.
|
||||
|
||||
## Membaca satu larian
|
||||
|
||||
1. Buka semakan status pada pull request, kemudian kerja `quality-checks-csharp`.
|
||||
2. Setiap alat mempunyai kumpulan lognya sendiri. Kedua-duanya dijalankan walaupun yang pertama gagal, jadi satu larian menunjukkan semua dapatan.
|
||||
3. Satu alat berakhir dengan `PASS <alat>` atau `FAIL <alat>`; baris terakhir larian yang gagal menamakannya: `Quality checks failed: dotnet format --verify-no-changes`.
|
||||
4. Satu dapatan ditulis oleh alat itu sendiri sebagai `path(line,column): CODE message`. Laluan itu mutlak dalam ruang kerja runner (`/workspace/<owner>/<repo>/src/Program.cs(8,27)`).
|
||||
|
||||
## Kegagalan biasa dan pembetulan
|
||||
|
||||
| Alat | Apa yang ditunjukkan log | Pembetulan |
|
||||
| --- | --- | --- |
|
||||
| `dotnet format --verify-no-changes` | `Program.cs(12,5): error WHITESPACE: Fix whitespace formatting` | Jalankan `dotnet format <projek>` dan commit |
|
||||
| `dotnet build -warnaserror` | `CS8602: Dereference of a possibly null reference` | Betulkan kod (semakan null); jangan tindas amaran tanpa sebab |
|
||||
| `dotnet build -warnaserror` | `IDE0005: Using directive is unnecessary` | Buang arahan itu |
|
||||
|
||||
Untuk mengulangi satu larian pada mesin anda, gunakan SDK yang sama:
|
||||
|
||||
```bash
|
||||
dotnet --version # 10.0.401
|
||||
dotnet format src/App.sln --verify-no-changes
|
||||
dotnet build src/App.sln -warnaserror
|
||||
```
|
||||
|
||||
## Apabila aliran kerja itu sendiri gagal
|
||||
|
||||
| Mesej | Punca | Pembetulan |
|
||||
| --- | --- | --- |
|
||||
| `[configuration] dotnet-sdk-version '<x>' is not an exact stable version 10 or later` | Saluran, julat, pratonton atau versi di bawah 10 | Berikan versi tepat seperti `10.0.401` |
|
||||
| `[configuration] working-directory must be a relative path inside the repository.` | Laluan mutlak atau `..` | Gunakan laluan di dalam repositori |
|
||||
| `[configuration] C# files exist but no solution or project was found` | Repositori mempunyai fail `*.cs` tetapi tiada `*.sln`, `*.slnx` atau `*.csproj` dalam direktori kerja | Tambah satu, atau tetapkan `working-directory` |
|
||||
| `[configuration] Several solutions or projects were found` | Lebih daripada satu calon | Tetapkan input `project` |
|
||||
| Langkah pemasangan gagal | `dot.net` atau rangkaian runner tidak dapat dicapai | Jalankan semula kerja; lihat [troubleshooting.md](troubleshooting.md) |
|
||||
@@ -0,0 +1,88 @@
|
||||
<!-- translation of QualityChecksCpp.md, source sha256 6faa57183a11 -->
|
||||
|
||||
> Dette er en oversættelse af [`QualityChecksCpp`](QualityChecksCpp). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
|
||||
|
||||
[English](QualityChecksCpp) | Dansk | [Bahasa Melayu](QualityChecksCpp.ms)
|
||||
|
||||
# Aflæsning af resultater fra kvalitetskontrol af C og C++
|
||||
|
||||
Sådan kalder en softwareudvikler den fælles kvalitetskontrol af C og C++, aflæser en mislykket kørsel og får den til at bestå. Workflowet formatkontrollerer og analyserer statisk repositoryets C- og C++-filer med clang-værktøjer i præcise versioner, ændrer ingen fil og kræver ingen secret. Dets kontrakt er ADR-0008 i dette repository.
|
||||
|
||||
## Kald af workflowet
|
||||
|
||||
```yaml
|
||||
name: Quality C++
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
quality:
|
||||
permissions:
|
||||
contents: read
|
||||
uses: TirSystem/github-action/.gitea/workflows/quality-checks-cpp.yml@v1
|
||||
with:
|
||||
std: c++20
|
||||
```
|
||||
|
||||
| Input | Standard | Betydning |
|
||||
| --- | --- | --- |
|
||||
| `working-directory` | `.` | Mappe, relativt til repositoryets rod, hvis filer kontrolleres |
|
||||
| `std` | `c++20` | C++-standard, som clang-tidy får, når der ikke er en compile-database, for eksempel `c++17` eller `gnu++20` |
|
||||
| `compile-commands-dir` | tom | Mappe, relativt til repositoryets rod, med en `compile_commands.json`, som din pipeline har bygget før kaldet; når den er sat, bruger clang-tidy den og ignorerer `std` |
|
||||
| `clang-format-version` | `23.1.3` | Præcis version af pakken clang-format |
|
||||
| `clang-tidy-version` | `22.1.8` | Præcis version af pakken clang-tidy |
|
||||
| `tools-ref` | `v1` | Tag eller gren i `TirSystem/github-action`, hvorfra scriptet `tools/quality-checks-cpp.sh` hentes |
|
||||
|
||||
Henvis til workflowet ved major-tagget (`@v1`) eller et præcist tag, aldrig ved `main`. Et kald ved et præcist tag er kun fuldt fastlåst, når `tools-ref` angiver samme tag. Se opgraderingsvejledningen. Værktøjsversionerne er præcise: en nyere version af et værktøj er en ny udgivelse af dette repository, ikke en stille ændring.
|
||||
|
||||
## Hvad repositoryet skal have
|
||||
|
||||
- En `.clang-format` i arbejdsmappen eller i en mappe over den, op til repositoryets rod. Uden en fejler kørslen med `[configuration]`, og intet værktøj kører.
|
||||
- Eventuelt en `.clang-tidy` med projektets kontroller (for eksempel C++ Core Guidelines). Uden en kører workflowet compilerdiagnostik og den statiske analysator (`clang-diagnostic-*` og `clang-analyzer-*`), fordi clang-tidy selv ikke aktiverer nogen kontrol uden konfiguration.
|
||||
- For præcise statiske kontroller en compile-database: byg den først (for eksempel `cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON`) og angiv `compile-commands-dir: build`. Workflowet bygger ikke dit projekt.
|
||||
|
||||
## Hvad der kontrolleres
|
||||
|
||||
| Filer | Værktøj | Hvad det melder |
|
||||
| --- | --- | --- |
|
||||
| sporede `*.c`, `*.cc`, `*.cpp`, `*.cxx`, `*.h`, `*.hh`, `*.hpp`, `*.hxx` | `clang-format --dry-run -Werror` | formatering, der afviger fra `.clang-format` |
|
||||
| de samme filer | `clang-tidy` | fund fra kontrollerne i `.clang-tidy` (eller fra `clang-diagnostic-*` og `clang-analyzer-*` uden en); `*.c`-filer kontrolleres som C17, de øvrige filer som C++-standarden i `std`; hvert fund er en fejl (`--warnings-as-errors=*`), så en advarsel får kørslen til at fejle |
|
||||
|
||||
Usporede filer kontrolleres ikke. Et repository uden disse filer består med en bemærkning. Der er ingen `cppcheck`: kun en gammel version findes som pakke, og gamle værktøjer køres ikke (ADR-0008).
|
||||
|
||||
## Aflæsning af en kørsel
|
||||
|
||||
1. Åbn statuskontrollen på pull requesten og derefter jobbet `quality-checks-cpp`.
|
||||
2. Hvert værktøj har sin egen logggruppe. Alle værktøjer kører, selv om et tidligere fejlede, så én kørsel viser alle fund.
|
||||
3. Et værktøj ender med `PASS <værktøj>` eller `FAIL <værktøj>`; sidste linje i en mislykket kørsel nævner dem: `Quality checks failed: clang-format`.
|
||||
4. Et fund skrives af værktøjet selv som `path:line:column: message`. `clang-format` skriver stier relative til `working-directory`; `clang-tidy` skriver absolutte stier i runnerens arbejdsområde (`/workspace/<owner>/<repo>/main.cpp:5:18`).
|
||||
|
||||
## Typiske fejl og rettelser
|
||||
|
||||
| Værktøj | Hvad loggen viser | Rettelse |
|
||||
| --- | --- | --- |
|
||||
| `clang-format` | `code should be clang-formatted [-Wclang-format-violations]` | Kør `clang-format -i <fil>` med samme version, og commit |
|
||||
| `clang-tidy` | `warning: ... [modernize-use-nullptr]` | Ret koden, eller slå kontrollen fra i `.clang-tidy` med en begrundelse |
|
||||
| `clang-tidy` | `error: 'x.h' file not found` | Byg compile-databasen og sæt `compile-commands-dir`, eller tilføj include-stien til den |
|
||||
|
||||
For at gentage en kørsel på din egen maskine skal du installere de samme versioner:
|
||||
|
||||
```bash
|
||||
python3 -m venv .qc
|
||||
.qc/bin/pip install clang-format==23.1.3 clang-tidy==22.1.8
|
||||
git ls-files '*.cpp' '*.hpp' | xargs .qc/bin/clang-format --dry-run -Werror
|
||||
```
|
||||
|
||||
## Når workflowet selv fejler
|
||||
|
||||
| Meddelelse | Årsag | Rettelse |
|
||||
| --- | --- | --- |
|
||||
| `[configuration] std '<x>' is not a C++ standard` | `std` er ikke som `c++20` eller `gnu++20` | Ret inputtet |
|
||||
| `[configuration] ... is not an exact version` | En værktøjsversion er et interval, en kanal eller tom | Angiv en præcis version som `23.1.3` |
|
||||
| `[configuration] working-directory must be a relative path inside the repository.` | En absolut sti eller `..` | Brug en sti inde i repositoryet |
|
||||
| `[configuration] No .clang-format found` | Projektet har ingen stilfil | Tilføj en `.clang-format` |
|
||||
| `[configuration] compile-commands-dir '<x>' has no compile_commands.json` | Databasen blev ikke bygget før kaldet | Byg den i et tidligere trin i jobbet eller i et job, det afhænger af |
|
||||
| Installationstrinnet fejler | PyPI eller runnerens netværk kan ikke nås | Kør jobbet igen; se [troubleshooting.md](troubleshooting.md) |
|
||||
@@ -0,0 +1,108 @@
|
||||
<!-- Generated from guides/quality-checks-cpp.md by tools/build_wiki.py. Edit the source, not this page. -->
|
||||
|
||||
> This page is generated from [`guides/quality-checks-cpp.md`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/quality-checks-cpp.md). Changes made here are overwritten the next time the wiki is published.
|
||||
|
||||
English | [Dansk](QualityChecksCpp.da) | [Bahasa Melayu](QualityChecksCpp.ms)
|
||||
|
||||
# Reading C and C++ quality-check results
|
||||
|
||||
How a software engineer calls the shared C and C++ quality checks, reads a
|
||||
failed run and makes it pass. The workflow format-checks and statically checks
|
||||
the C and C++ files of a repository with clang tools at exact versions, changes
|
||||
no file and needs no secret. Its contract is ADR-0008 in this repository.
|
||||
|
||||
## Calling the workflow
|
||||
|
||||
```yaml
|
||||
name: Quality C++
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
quality:
|
||||
permissions:
|
||||
contents: read
|
||||
uses: TirSystem/github-action/.gitea/workflows/quality-checks-cpp.yml@v1
|
||||
with:
|
||||
std: c++20
|
||||
```
|
||||
|
||||
| Input | Default | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `working-directory` | `.` | Directory, relative to the repository root, whose files are checked |
|
||||
| `std` | `c++20` | C++ standard given to clang-tidy when there is no compile database, such as `c++17` or `gnu++20` |
|
||||
| `compile-commands-dir` | empty | Directory, relative to the repository root, with a `compile_commands.json` that your pipeline built before the call; when set, clang-tidy uses it and ignores `std` |
|
||||
| `clang-format-version` | `23.1.3` | Exact version of the clang-format package |
|
||||
| `clang-tidy-version` | `22.1.8` | Exact version of the clang-tidy package |
|
||||
| `tools-ref` | `v1` | Tag or branch of `TirSystem/github-action` from which the script `tools/quality-checks-cpp.sh` is fetched |
|
||||
|
||||
Reference the workflow at the major tag (`@v1`) or at an exact tag, never at
|
||||
`main`. A call at an exact tag is pinned completely only when `tools-ref` names
|
||||
the same tag. See the upgrade guide. The tool versions are exact: a newer
|
||||
version of a tool is a new release of this repository, not a silent change.
|
||||
|
||||
## What the repository needs
|
||||
|
||||
- A `.clang-format` in the working directory or in a directory above it, up to
|
||||
the top of the repository. Without one the run fails with `[configuration]`
|
||||
and no tool runs.
|
||||
- Optionally a `.clang-tidy` with the checks of the project (for example the
|
||||
C++ Core Guidelines). Without one the workflow runs the compiler diagnostics
|
||||
and the static analyzer (`clang-diagnostic-*` and `clang-analyzer-*`),
|
||||
because clang-tidy itself enables no check when there is no configuration.
|
||||
- For precise static checks, a compile database: build it first (for example
|
||||
`cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON`) and pass
|
||||
`compile-commands-dir: build`. The workflow does not build your project.
|
||||
|
||||
## What is checked
|
||||
|
||||
| Files | Tool | What it reports |
|
||||
| --- | --- | --- |
|
||||
| tracked `*.c`, `*.cc`, `*.cpp`, `*.cxx`, `*.h`, `*.hh`, `*.hpp`, `*.hxx` | `clang-format --dry-run -Werror` | formatting that differs from `.clang-format` |
|
||||
| the same files | `clang-tidy` | findings of the checks of `.clang-tidy` (or of `clang-diagnostic-*` and `clang-analyzer-*` without one); `*.c` files are checked as C17, the other files as the C++ standard of `std`; every finding is an error (`--warnings-as-errors=*`), so a warning fails the run |
|
||||
|
||||
Untracked files are not checked. A repository without these files passes with a
|
||||
notice. There is no `cppcheck`: only an old version of it is available as a
|
||||
package, and old tools are not run (ADR-0008).
|
||||
|
||||
## Reading a run
|
||||
|
||||
1. Open the status check on the pull request, then the job `quality-checks-cpp`.
|
||||
2. Each tool has its own log group. Every tool runs even when an earlier one
|
||||
failed, so one run shows all findings.
|
||||
3. A tool ends with `PASS <tool>` or `FAIL <tool>`; the last line of a failed
|
||||
run names them: `Quality checks failed: clang-format`.
|
||||
4. A finding is written by the tool itself as `path:line:column: message`.
|
||||
`clang-format` prints paths relative to `working-directory`; `clang-tidy`
|
||||
prints absolute paths in the workspace of the runner
|
||||
(`/workspace/<owner>/<repo>/main.cpp:5:18`).
|
||||
|
||||
## Typical failures and fixes
|
||||
|
||||
| Tool | What the log shows | Fix |
|
||||
| --- | --- | --- |
|
||||
| `clang-format` | `code should be clang-formatted [-Wclang-format-violations]` | Run `clang-format -i <file>` with the same version and commit |
|
||||
| `clang-tidy` | `warning: ... [modernize-use-nullptr]` | Fix the code, or switch the check off in `.clang-tidy` with a reason |
|
||||
| `clang-tidy` | `error: 'x.h' file not found` | Build the compile database and set `compile-commands-dir`, or add the include path to it |
|
||||
|
||||
To reproduce a run on your machine, install the same versions:
|
||||
|
||||
```bash
|
||||
python3 -m venv .qc
|
||||
.qc/bin/pip install clang-format==23.1.3 clang-tidy==22.1.8
|
||||
git ls-files '*.cpp' '*.hpp' | xargs .qc/bin/clang-format --dry-run -Werror
|
||||
```
|
||||
|
||||
## When the workflow itself fails
|
||||
|
||||
| Message | Cause | Fix |
|
||||
| --- | --- | --- |
|
||||
| `[configuration] std '<x>' is not a C++ standard` | `std` is not like `c++20` or `gnu++20` | Correct the input |
|
||||
| `[configuration] ... is not an exact version` | A tool version is a range, a channel or empty | Give an exact version such as `23.1.3` |
|
||||
| `[configuration] working-directory must be a relative path inside the repository.` | An absolute path or `..` | Use a path inside the repository |
|
||||
| `[configuration] No .clang-format found` | The project has no style file | Add a `.clang-format` |
|
||||
| `[configuration] compile-commands-dir '<x>' has no compile_commands.json` | The database was not built before the call | Build it in an earlier step of the job or in a job it depends on |
|
||||
| The install step fails | PyPI or the runner network is unreachable | Re-run the job; see [troubleshooting.md](Troubleshooting) |
|
||||
@@ -0,0 +1,88 @@
|
||||
<!-- translation of QualityChecksCpp.md, source sha256 6faa57183a11 -->
|
||||
|
||||
> Ini ialah terjemahan [`QualityChecksCpp`](QualityChecksCpp). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
|
||||
|
||||
[English](QualityChecksCpp) | [Dansk](QualityChecksCpp.da) | Bahasa Melayu
|
||||
|
||||
# Membaca keputusan semakan kualiti C dan C++
|
||||
|
||||
Cara seorang jurutera perisian memanggil semakan kualiti bersama untuk C dan C++, membaca larian yang gagal dan menjadikannya lulus. Aliran kerja ini menyemak format dan menganalisis secara statik fail C dan C++ sesebuah repositori dengan alat clang pada versi yang tepat, tidak mengubah sebarang fail dan tidak memerlukan secret. Kontraknya ialah ADR-0008 dalam repositori ini.
|
||||
|
||||
## Memanggil aliran kerja
|
||||
|
||||
```yaml
|
||||
name: Quality C++
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
quality:
|
||||
permissions:
|
||||
contents: read
|
||||
uses: TirSystem/github-action/.gitea/workflows/quality-checks-cpp.yml@v1
|
||||
with:
|
||||
std: c++20
|
||||
```
|
||||
|
||||
| Input | Lalai | Maksud |
|
||||
| --- | --- | --- |
|
||||
| `working-directory` | `.` | Direktori, relatif kepada akar repositori, yang failnya disemak |
|
||||
| `std` | `c++20` | Piawaian C++ yang diberikan kepada clang-tidy apabila tiada pangkalan data kompilasi, seperti `c++17` atau `gnu++20` |
|
||||
| `compile-commands-dir` | kosong | Direktori, relatif kepada akar repositori, dengan `compile_commands.json` yang dibina oleh saluran paip anda sebelum panggilan; apabila ditetapkan, clang-tidy menggunakannya dan mengabaikan `std` |
|
||||
| `clang-format-version` | `23.1.3` | Versi tepat pakej clang-format |
|
||||
| `clang-tidy-version` | `22.1.8` | Versi tepat pakej clang-tidy |
|
||||
| `tools-ref` | `v1` | Tag atau cabang `TirSystem/github-action` tempat skrip `tools/quality-checks-cpp.sh` diambil |
|
||||
|
||||
Rujuk aliran kerja pada tag major (`@v1`) atau pada tag tepat, jangan sekali-kali pada `main`. Panggilan pada tag tepat hanya disematkan sepenuhnya apabila `tools-ref` menamakan tag yang sama. Lihat panduan naik taraf. Versi alat adalah tepat: versi alat yang lebih baharu ialah keluaran baharu repositori ini, bukan perubahan senyap.
|
||||
|
||||
## Apa yang diperlukan oleh repositori
|
||||
|
||||
- Satu `.clang-format` dalam direktori kerja atau dalam direktori di atasnya, sehingga akar repositori. Tanpanya larian gagal dengan `[configuration]` dan tiada alat dijalankan.
|
||||
- Pilihan: satu `.clang-tidy` dengan semakan projek (contohnya C++ Core Guidelines). Tanpanya aliran kerja menjalankan diagnostik pengkompil dan penganalisis statik (`clang-diagnostic-*` dan `clang-analyzer-*`), kerana clang-tidy sendiri tidak mengaktifkan sebarang semakan tanpa konfigurasi.
|
||||
- Untuk semakan statik yang tepat, satu pangkalan data kompilasi: bina dahulu (contohnya `cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON`) dan berikan `compile-commands-dir: build`. Aliran kerja tidak membina projek anda.
|
||||
|
||||
## Apa yang disemak
|
||||
|
||||
| Fail | Alat | Apa yang dilaporkan |
|
||||
| --- | --- | --- |
|
||||
| `*.c`, `*.cc`, `*.cpp`, `*.cxx`, `*.h`, `*.hh`, `*.hpp`, `*.hxx` yang dijejaki | `clang-format --dry-run -Werror` | pemformatan yang berbeza daripada `.clang-format` |
|
||||
| fail yang sama | `clang-tidy` | dapatan semakan dalam `.clang-tidy` (atau `clang-diagnostic-*` dan `clang-analyzer-*` tanpanya); fail `*.c` disemak sebagai C17, fail lain sebagai piawaian C++ dalam `std`; setiap dapatan ialah ralat (`--warnings-as-errors=*`), jadi amaran menggagalkan larian |
|
||||
|
||||
Fail yang tidak dijejaki tidak disemak. Repositori tanpa fail ini lulus dengan satu notis. Tiada `cppcheck`: hanya versi lama tersedia sebagai pakej, dan alat lama tidak dijalankan (ADR-0008).
|
||||
|
||||
## Membaca satu larian
|
||||
|
||||
1. Buka semakan status pada pull request, kemudian kerja `quality-checks-cpp`.
|
||||
2. Setiap alat mempunyai kumpulan lognya sendiri. Setiap alat dijalankan walaupun yang terdahulu gagal, jadi satu larian menunjukkan semua dapatan.
|
||||
3. Satu alat berakhir dengan `PASS <alat>` atau `FAIL <alat>`; baris terakhir larian yang gagal menamakannya: `Quality checks failed: clang-format`.
|
||||
4. Satu dapatan ditulis oleh alat itu sendiri sebagai `path:line:column: message`. `clang-format` menulis laluan relatif kepada `working-directory`; `clang-tidy` menulis laluan mutlak dalam ruang kerja runner (`/workspace/<owner>/<repo>/main.cpp:5:18`).
|
||||
|
||||
## Kegagalan biasa dan pembetulan
|
||||
|
||||
| Alat | Apa yang ditunjukkan log | Pembetulan |
|
||||
| --- | --- | --- |
|
||||
| `clang-format` | `code should be clang-formatted [-Wclang-format-violations]` | Jalankan `clang-format -i <fail>` dengan versi yang sama dan commit |
|
||||
| `clang-tidy` | `warning: ... [modernize-use-nullptr]` | Betulkan kod, atau matikan semakan itu dalam `.clang-tidy` dengan sebab |
|
||||
| `clang-tidy` | `error: 'x.h' file not found` | Bina pangkalan data kompilasi dan tetapkan `compile-commands-dir`, atau tambah laluan include kepadanya |
|
||||
|
||||
Untuk mengulangi satu larian pada mesin anda, pasang versi yang sama:
|
||||
|
||||
```bash
|
||||
python3 -m venv .qc
|
||||
.qc/bin/pip install clang-format==23.1.3 clang-tidy==22.1.8
|
||||
git ls-files '*.cpp' '*.hpp' | xargs .qc/bin/clang-format --dry-run -Werror
|
||||
```
|
||||
|
||||
## Apabila aliran kerja itu sendiri gagal
|
||||
|
||||
| Mesej | Punca | Pembetulan |
|
||||
| --- | --- | --- |
|
||||
| `[configuration] std '<x>' is not a C++ standard` | `std` bukan seperti `c++20` atau `gnu++20` | Betulkan input |
|
||||
| `[configuration] ... is not an exact version` | Versi alat ialah julat, saluran atau kosong | Berikan versi tepat seperti `23.1.3` |
|
||||
| `[configuration] working-directory must be a relative path inside the repository.` | Laluan mutlak atau `..` | Gunakan laluan di dalam repositori |
|
||||
| `[configuration] No .clang-format found` | Projek tiada fail gaya | Tambah `.clang-format` |
|
||||
| `[configuration] compile-commands-dir '<x>' has no compile_commands.json` | Pangkalan data tidak dibina sebelum panggilan | Bina dalam langkah terdahulu kerja itu atau dalam kerja yang menjadi tanggungannya |
|
||||
| Langkah pemasangan gagal | PyPI atau rangkaian runner tidak dapat dicapai | Jalankan semula kerja; lihat [troubleshooting.md](troubleshooting.md) |
|
||||
@@ -0,0 +1,98 @@
|
||||
<!-- translation of QualityChecksPythonShell.md, source sha256 2a0c9d43c77d -->
|
||||
|
||||
> Dette er en oversættelse af [`QualityChecksPythonShell`](QualityChecksPythonShell). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
|
||||
|
||||
[English](QualityChecksPythonShell) | Dansk | [Bahasa Melayu](QualityChecksPythonShell.ms)
|
||||
|
||||
# Aflæsning af resultater fra kvalitetskontrol
|
||||
|
||||
Sådan kalder en softwareudvikler den fælles kvalitetskontrol, aflæser en mislykket kørsel og får den til at bestå. Workflowet kører lint og formatkontrol på repositoryets Python- og shell-filer med fastlåste værktøjer, ændrer ingen fil og kræver ingen secret. Dets kontrakt er ADR-0005 i dette repository.
|
||||
|
||||
## Kald af workflowet
|
||||
|
||||
```yaml
|
||||
name: Quality
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
quality:
|
||||
permissions:
|
||||
contents: read
|
||||
uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1
|
||||
with:
|
||||
languages: python,shell
|
||||
```
|
||||
|
||||
| Input | Standard | Betydning |
|
||||
| --- | --- | --- |
|
||||
| `languages` | `python,shell` | Kommasepareret liste over de sprog, der kontrolleres |
|
||||
| `working-directory` | `.` | Mappe, relativt til repositoryets rod, hvis filer kontrolleres |
|
||||
| `ruff-version` | `0.6.9` | Version af ruff |
|
||||
| `mypy-version` | `1.11.2` | Version af mypy |
|
||||
| `shellcheck-py-version` | `0.10.0.1` | Version af pakken shellcheck-py (ShellCheck 0.10.0) |
|
||||
| `shfmt-py-version` | `3.11.0.2` | Version af pakken shfmt-py (shfmt 3.11.0) |
|
||||
| `tools-ref` | `v1` | Tag eller gren i `TirSystem/github-action`, hvorfra scriptet `tools/quality-checks.sh` hentes |
|
||||
|
||||
Henvis til workflowet ved major-tagget (`@v1`) eller et præcist tag (`@v1.0.0`), aldrig ved `main` og aldrig ved en pull requests gren: den gren slettes, når pull requesten flettes, og henvisningen holder op med at virke. Se opgraderingsvejledningen for, hvad hvert valg modtager.
|
||||
|
||||
Workflowfilen kalder et script i dette repository, hentet ved `tools-ref`. Et kald ved et præcist tag er kun fuldt fastlåst, når `tools-ref` angiver samme tag, for eksempel `@v1.0.1` med `tools-ref: v1.0.1`; med standardværdien følger scriptet `v1`.
|
||||
|
||||
## Hvad der kontrolleres
|
||||
|
||||
| Sprog | Filer | Værktøjer |
|
||||
| --- | --- | --- |
|
||||
| Python | sporede `*.py` under arbejdsmappen | `ruff check`, `ruff format --check`, `mypy --strict` |
|
||||
| Shell | sporede `*.sh` under arbejdsmappen | `shellcheck`, `shfmt -d` |
|
||||
|
||||
Ikke-sporede filer kontrolleres ikke. Et sprog uden filer springes over med en meddelelse og tæller som bestået. Projektets tests køres ikke.
|
||||
|
||||
## Aflæsning af en kørsel
|
||||
|
||||
1. Åbn statuskontrollen på pull requesten og derefter jobbet `quality-checks`.
|
||||
2. Hvert værktøj har sin egen logsektion med værktøjets navn. Hvert værktøj kører, selv om et tidligere fejlede, så én kørsel viser alle fund.
|
||||
3. Et værktøj slutter med `PASS <værktøj>` eller `FAIL <værktøj>`. Sidste linje i en mislykket kørsel nævner de værktøjer, der fejlede: `Quality checks failed: ruff check shellcheck`.
|
||||
4. Et fund skrives af værktøjet selv som `sti:linje:kolonne: KODE meddelelse`. Stier er relative til `working-directory`.
|
||||
|
||||
## Typiske fejl og rettelser
|
||||
|
||||
| Værktøj | Hvad loggen viser | Rettelse |
|
||||
| --- | --- | --- |
|
||||
| `ruff check` | `F401 ... imported but unused` | Fjern importen, eller brug den |
|
||||
| `ruff format --check` | `Would reformat: <fil>` | Kør `ruff format <fil>` og commit |
|
||||
| `mypy --strict` | `Function is missing a type annotation` | Tilføj typer til parametre og returværdi |
|
||||
| `shellcheck` | `SC2086 ... Double quote to prevent globbing` | Sæt udvidelsen i anførselstegn: `"$1"` |
|
||||
| `shfmt -d` | en forskel mellem `<fil>.orig` og `<fil>` | Kør `shfmt -w <fil>` med projektets indstillinger og commit |
|
||||
|
||||
For at gentage en kørsel på din egen maskine skal du installere de samme versioner og køre kommandoerne fra tabellen:
|
||||
|
||||
```bash
|
||||
python3 -m venv .qc
|
||||
.qc/bin/pip install ruff==0.6.9 mypy==1.11.2 shellcheck-py==0.10.0.1 shfmt-py==3.11.0.2
|
||||
.qc/bin/ruff check . && .qc/bin/ruff format --check .
|
||||
```
|
||||
|
||||
## Konfiguration af værktøjerne
|
||||
|
||||
Workflowet tilføjer ingen konfiguration; det kører fra repositoryets rod, så projektets egne filer gælder:
|
||||
|
||||
| Værktøj | Fil | Eksempel |
|
||||
| --- | --- | --- |
|
||||
| ruff | `pyproject.toml` | `[tool.ruff]` med `line-length = 100` |
|
||||
| mypy | `pyproject.toml` | `[tool.mypy]` med `ignore_missing_imports` pr. modul |
|
||||
| shellcheck | `.shellcheckrc` | `external-sources=true` og `source-path=SCRIPTDIR` |
|
||||
| shfmt | `.editorconfig` | `[*.sh]` med `indent_size = 2` og `switch_case_indent = true` |
|
||||
|
||||
shfmt følger et projekts stil kun gennem `.editorconfig`. Et shell-projekt, der formaterer med egne flag (fx `shfmt -i 2 -ci`), bør forvente en formateringsfejl ved første kørsel og udtrykke flagene dér; ved den første tilslutning (RepoFoundry) var én linje, `switch_case_indent = true`, nok, og intet script blev ændret.
|
||||
|
||||
## Når selve workflowet fejler
|
||||
|
||||
| Meddelelse | Årsag | Rettelse |
|
||||
| --- | --- | --- |
|
||||
| `[configuration] Unknown language '<x>'` | `languages` har en anden værdi end `python` eller `shell` | Ret inputtet |
|
||||
| `[configuration] working-directory must be a relative path inside the repository.` | En absolut sti eller `..` | Brug en sti inde i repositoryet |
|
||||
| `[configuration] working-directory '<x>' does not exist.` | Mappen findes ikke i repositoryet | Ret inputtet |
|
||||
| Installationstrinnet fejler | PyPI eller runnerens netværk kan ikke nås | Kør jobbet igen; se [troubleshooting.md](Troubleshooting.da) |
|
||||
@@ -0,0 +1,118 @@
|
||||
<!-- Generated from guides/quality-checks.md by tools/build_wiki.py. Edit the source, not this page. -->
|
||||
|
||||
> This page is generated from [`guides/quality-checks.md`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/quality-checks.md). Changes made here are overwritten the next time the wiki is published.
|
||||
|
||||
English | [Dansk](QualityChecksPythonShell.da) | [Bahasa Melayu](QualityChecksPythonShell.ms)
|
||||
|
||||
# Reading quality-check results
|
||||
|
||||
How a software engineer calls the shared quality checks, reads a failed run and
|
||||
makes it pass. The workflow lints and format-checks the Python and shell files
|
||||
of a repository with pinned tools, changes no file and needs no secret. Its
|
||||
contract is ADR-0005 in this repository.
|
||||
|
||||
## Calling the workflow
|
||||
|
||||
```yaml
|
||||
name: Quality
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
quality:
|
||||
permissions:
|
||||
contents: read
|
||||
uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1
|
||||
with:
|
||||
languages: python,shell
|
||||
```
|
||||
|
||||
| Input | Default | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `languages` | `python,shell` | Comma list of the languages to check |
|
||||
| `working-directory` | `.` | Directory, relative to the repository root, whose files are checked |
|
||||
| `ruff-version` | `0.6.9` | Version of ruff |
|
||||
| `mypy-version` | `1.11.2` | Version of mypy |
|
||||
| `shellcheck-py-version` | `0.10.0.1` | Version of the shellcheck-py package (ShellCheck 0.10.0) |
|
||||
| `shfmt-py-version` | `3.11.0.2` | Version of the shfmt-py package (shfmt 3.11.0) |
|
||||
| `tools-ref` | `v1` | Tag or branch of `TirSystem/github-action` from which the script `tools/quality-checks.sh` is fetched |
|
||||
|
||||
Reference the workflow at the major tag (`@v1`) or at an exact tag
|
||||
(`@v1.0.0`), never at `main` and never at the branch of a pull request: that
|
||||
branch is deleted when the pull request is merged and the reference stops
|
||||
working. See the upgrade guide for what each choice receives.
|
||||
|
||||
The workflow file calls a script of this repository, fetched at `tools-ref`. A
|
||||
call at an exact tag is pinned completely only when `tools-ref` names the same
|
||||
tag, for example `@v1.0.1` with `tools-ref: v1.0.1`; with the default the
|
||||
script follows `v1`.
|
||||
|
||||
## What is checked
|
||||
|
||||
| Language | Files | Tools |
|
||||
| --- | --- | --- |
|
||||
| Python | tracked `*.py` under the working directory | `ruff check`, `ruff format --check`, `mypy --strict` |
|
||||
| Shell | tracked `*.sh` under the working directory | `shellcheck`, `shfmt -d` |
|
||||
|
||||
Untracked files are not checked. A language without files is skipped with a
|
||||
notice and counts as a pass. Project tests are not run.
|
||||
|
||||
## Reading a run
|
||||
|
||||
1. Open the status check on the pull request, then the job `quality-checks`.
|
||||
2. Each tool has its own log group named after it. Every tool runs even when an
|
||||
earlier one failed, so one run shows all findings.
|
||||
3. A tool ends with `PASS <tool>` or `FAIL <tool>`. The last line of a failed
|
||||
run names the tools that failed:
|
||||
`Quality checks failed: ruff check shellcheck`.
|
||||
4. A finding is written by the tool itself as `path:line:column: CODE message`.
|
||||
Paths are relative to `working-directory`.
|
||||
|
||||
## Typical failures and fixes
|
||||
|
||||
| Tool | What the log shows | Fix |
|
||||
| --- | --- | --- |
|
||||
| `ruff check` | `F401 ... imported but unused` | Remove the import, or use it |
|
||||
| `ruff format --check` | `Would reformat: <file>` | Run `ruff format <file>` and commit |
|
||||
| `mypy --strict` | `Function is missing a type annotation` | Add parameter and return types |
|
||||
| `shellcheck` | `SC2086 ... Double quote to prevent globbing` | Quote the expansion: `"$1"` |
|
||||
| `shfmt -d` | a diff of `<file>.orig` and `<file>` | Run `shfmt -w <file>` with the project's options and commit |
|
||||
|
||||
To reproduce a run on your machine, install the same versions and run the
|
||||
commands of the table:
|
||||
|
||||
```bash
|
||||
python3 -m venv .qc
|
||||
.qc/bin/pip install ruff==0.6.9 mypy==1.11.2 shellcheck-py==0.10.0.1 shfmt-py==3.11.0.2
|
||||
.qc/bin/ruff check . && .qc/bin/ruff format --check .
|
||||
```
|
||||
|
||||
## Configuring the tools
|
||||
|
||||
The workflow adds no configuration; it runs from the repository root, so the
|
||||
files of the project apply:
|
||||
|
||||
| Tool | File | Example |
|
||||
| --- | --- | --- |
|
||||
| ruff | `pyproject.toml` | `[tool.ruff]` with `line-length = 100` |
|
||||
| mypy | `pyproject.toml` | `[tool.mypy]` with per-module `ignore_missing_imports` |
|
||||
| shellcheck | `.shellcheckrc` | `external-sources=true` and `source-path=SCRIPTDIR` |
|
||||
| shfmt | `.editorconfig` | `[*.sh]` with `indent_size = 2` and `switch_case_indent = true` |
|
||||
|
||||
shfmt follows a project's style only through `.editorconfig`. A shell project
|
||||
that formats with its own flags (for example `shfmt -i 2 -ci`) should expect a
|
||||
first formatting failure and express the flags there; in the first adoption
|
||||
(RepoFoundry) one line, `switch_case_indent = true`, was enough and no script
|
||||
changed.
|
||||
|
||||
## When the workflow itself fails
|
||||
|
||||
| Message | Cause | Fix |
|
||||
| --- | --- | --- |
|
||||
| `[configuration] Unknown language '<x>'` | `languages` has a value other than `python` or `shell` | Correct the input |
|
||||
| `[configuration] working-directory must be a relative path inside the repository.` | An absolute path or `..` | Use a path inside the repository |
|
||||
| `[configuration] working-directory '<x>' does not exist.` | The directory is not in the repository | Correct the input |
|
||||
| The install step fails | PyPI or the runner network is unreachable | Re-run the job; see [troubleshooting.md](Troubleshooting) |
|
||||
@@ -0,0 +1,98 @@
|
||||
<!-- translation of QualityChecksPythonShell.md, source sha256 2a0c9d43c77d -->
|
||||
|
||||
> Ini ialah terjemahan [`QualityChecksPythonShell`](QualityChecksPythonShell). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
|
||||
|
||||
[English](QualityChecksPythonShell) | [Dansk](QualityChecksPythonShell.da) | Bahasa Melayu
|
||||
|
||||
# Membaca keputusan semakan kualiti
|
||||
|
||||
Cara seorang jurutera perisian memanggil semakan kualiti bersama, membaca larian yang gagal dan menjadikannya lulus. Aliran kerja ini menjalankan lint dan semakan format ke atas fail Python dan shell sesebuah repositori dengan alat yang disematkan versinya, tidak mengubah sebarang fail dan tidak memerlukan secret. Kontraknya ialah ADR-0005 dalam repositori ini.
|
||||
|
||||
## Memanggil aliran kerja
|
||||
|
||||
```yaml
|
||||
name: Quality
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
quality:
|
||||
permissions:
|
||||
contents: read
|
||||
uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1
|
||||
with:
|
||||
languages: python,shell
|
||||
```
|
||||
|
||||
| Input | Lalai | Maksud |
|
||||
| --- | --- | --- |
|
||||
| `languages` | `python,shell` | Senarai bahasa yang disemak, dipisahkan koma |
|
||||
| `working-directory` | `.` | Direktori, relatif kepada akar repositori, yang failnya disemak |
|
||||
| `ruff-version` | `0.6.9` | Versi ruff |
|
||||
| `mypy-version` | `1.11.2` | Versi mypy |
|
||||
| `shellcheck-py-version` | `0.10.0.1` | Versi pakej shellcheck-py (ShellCheck 0.10.0) |
|
||||
| `shfmt-py-version` | `3.11.0.2` | Versi pakej shfmt-py (shfmt 3.11.0) |
|
||||
| `tools-ref` | `v1` | Tag atau cabang `TirSystem/github-action` tempat skrip `tools/quality-checks.sh` diambil |
|
||||
|
||||
Rujuk aliran kerja pada tag major (`@v1`) atau pada tag tepat (`@v1.0.0`), jangan sekali-kali pada `main` dan jangan pada cabang pull request: cabang itu dipadam apabila pull request digabungkan dan rujukan itu berhenti berfungsi. Lihat panduan naik taraf untuk apa yang diterima oleh setiap pilihan.
|
||||
|
||||
Fail aliran kerja memanggil skrip dalam repositori ini, yang diambil pada `tools-ref`. Panggilan pada tag tepat hanya disematkan sepenuhnya apabila `tools-ref` menamakan tag yang sama, contohnya `@v1.0.1` dengan `tools-ref: v1.0.1`; dengan nilai lalai skrip mengikuti `v1`.
|
||||
|
||||
## Perkara yang disemak
|
||||
|
||||
| Bahasa | Fail | Alat |
|
||||
| --- | --- | --- |
|
||||
| Python | `*.py` yang dijejaki di bawah direktori kerja | `ruff check`, `ruff format --check`, `mypy --strict` |
|
||||
| Shell | `*.sh` yang dijejaki di bawah direktori kerja | `shellcheck`, `shfmt -d` |
|
||||
|
||||
Fail yang tidak dijejaki tidak disemak. Bahasa tanpa fail dilangkau dengan notis dan dikira lulus. Ujian projek tidak dijalankan.
|
||||
|
||||
## Membaca satu larian
|
||||
|
||||
1. Buka semakan status pada pull request, kemudian kerja `quality-checks`.
|
||||
2. Setiap alat mempunyai kumpulan lognya sendiri yang dinamakan sempena alat itu. Setiap alat dijalankan walaupun alat sebelumnya gagal, jadi satu larian menunjukkan semua dapatan.
|
||||
3. Satu alat berakhir dengan `PASS <alat>` atau `FAIL <alat>`. Baris terakhir larian yang gagal menamakan alat yang gagal: `Quality checks failed: ruff check shellcheck`.
|
||||
4. Satu dapatan ditulis oleh alat itu sendiri sebagai `laluan:baris:lajur: KOD mesej`. Laluan relatif kepada `working-directory`.
|
||||
|
||||
## Kegagalan biasa dan pembetulan
|
||||
|
||||
| Alat | Apa yang ditunjukkan log | Pembetulan |
|
||||
| --- | --- | --- |
|
||||
| `ruff check` | `F401 ... imported but unused` | Buang import itu, atau gunakannya |
|
||||
| `ruff format --check` | `Would reformat: <fail>` | Jalankan `ruff format <fail>` dan commit |
|
||||
| `mypy --strict` | `Function is missing a type annotation` | Tambah jenis bagi parameter dan nilai pulangan |
|
||||
| `shellcheck` | `SC2086 ... Double quote to prevent globbing` | Letakkan pengembangan dalam tanda petikan: `"$1"` |
|
||||
| `shfmt -d` | perbezaan antara `<fail>.orig` dan `<fail>` | Jalankan `shfmt -w <fail>` dengan pilihan projek dan commit |
|
||||
|
||||
Untuk mengulang satu larian pada mesin anda, pasang versi yang sama dan jalankan arahan dalam jadual:
|
||||
|
||||
```bash
|
||||
python3 -m venv .qc
|
||||
.qc/bin/pip install ruff==0.6.9 mypy==1.11.2 shellcheck-py==0.10.0.1 shfmt-py==3.11.0.2
|
||||
.qc/bin/ruff check . && .qc/bin/ruff format --check .
|
||||
```
|
||||
|
||||
## Mengkonfigur alat
|
||||
|
||||
Aliran kerja tidak menambah sebarang konfigurasi; ia berjalan dari akar repositori, jadi fail projek itu sendiri terpakai:
|
||||
|
||||
| Alat | Fail | Contoh |
|
||||
| --- | --- | --- |
|
||||
| ruff | `pyproject.toml` | `[tool.ruff]` dengan `line-length = 100` |
|
||||
| mypy | `pyproject.toml` | `[tool.mypy]` dengan `ignore_missing_imports` bagi setiap modul |
|
||||
| shellcheck | `.shellcheckrc` | `external-sources=true` dan `source-path=SCRIPTDIR` |
|
||||
| shfmt | `.editorconfig` | `[*.sh]` dengan `indent_size = 2` dan `switch_case_indent = true` |
|
||||
|
||||
shfmt mengikut gaya sesebuah projek hanya melalui `.editorconfig`. Projek shell yang memformat dengan bendera sendiri (contohnya `shfmt -i 2 -ci`) patut menjangka kegagalan format pada larian pertama dan menyatakan bendera itu di sana; pada penerimaan pertama (RepoFoundry) satu baris, `switch_case_indent = true`, sudah mencukupi dan tiada skrip diubah.
|
||||
|
||||
## Apabila aliran kerja itu sendiri gagal
|
||||
|
||||
| Mesej | Punca | Pembetulan |
|
||||
| --- | --- | --- |
|
||||
| `[configuration] Unknown language '<x>'` | `languages` mempunyai nilai selain `python` atau `shell` | Betulkan input |
|
||||
| `[configuration] working-directory must be a relative path inside the repository.` | Laluan mutlak atau `..` | Gunakan laluan di dalam repositori |
|
||||
| `[configuration] working-directory '<x>' does not exist.` | Direktori itu tiada dalam repositori | Betulkan input |
|
||||
| Langkah pemasangan gagal | PyPI atau rangkaian runner tidak dapat dicapai | Jalankan semula kerja itu; lihat [troubleshooting.md](Troubleshooting.ms) |
|
||||
@@ -0,0 +1,66 @@
|
||||
<!-- translation of Troubleshooting.md, source sha256 c68827295812 -->
|
||||
|
||||
> Dette er en oversættelse af [`Troubleshooting`](Troubleshooting). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
|
||||
|
||||
[English](Troubleshooting) | Dansk | [Bahasa Melayu](Troubleshooting.ms)
|
||||
|
||||
# Fejlfinding af en mislykket kørsel
|
||||
|
||||
Åbn kørslen i Gitea (Actions) og læs de sidste linjer i det trin, der fejler. Hver fejl fra synkroniseringsscriptet skrives som
|
||||
|
||||
```
|
||||
ERROR: [<category>] <message>
|
||||
```
|
||||
|
||||
Kategorien fortæller, hvor du skal kigge. En fejl uden for scriptet (jobbet starter aldrig eller stopper før trinnet) er et **runner**-problem.
|
||||
|
||||
| Kategori | Betydning | Første ting at kontrollere |
|
||||
| --- | --- | --- |
|
||||
| `configuration` | En secret eller en repository-indstilling mangler eller er forkert udformet | Secretnavne og format, opsætning af push-spejl |
|
||||
| `credentials` | En tjeneste afviste tokenet (HTTP 401) | Token er udløbet, tilbagekaldt eller forkert indtastet |
|
||||
| `permissions` | Tokenet er gyldigt, men har ikke tilladelse (HTTP 403, eller ingen GitHub-administrationsadgang) | Token-scopes og repository-adgang |
|
||||
| `api` | En anden HTTP-fejl, eller tjenesten kunne ikke nås | Tjenestens status, runnerens netværk |
|
||||
| runner | Ingen `ERROR:`-linje; kørslen venter, eller jobbet fejler før scriptet | Runner online, label, værktøjer |
|
||||
|
||||
## Meddelelser og løsninger
|
||||
|
||||
| Meddelelse (begyndelsen) | Kategori | Årsag og løsning |
|
||||
| --- | --- | --- |
|
||||
| `PAT_FOR_GITHUB is missing or empty.` | configuration | Tilføj secreten |
|
||||
| `TOKEN_FOR_GITEA is missing or empty.` | configuration | Tilføj secreten |
|
||||
| `Could not determine the Gitea source repository.` | configuration | Kørslen har intet repositorynavn; meld det som en defekt |
|
||||
| `Expected at most one GitHub push mirror ... found N` | configuration | Behold ét GitHub push-spejl |
|
||||
| `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Kun wiki-publicering: repositoryet kalder workflowet, men dets organisation har ingen sådan secret, eller kaldet sender den ikke; gem den og send den i `secrets:` (se [credentials.md](Credentials.da)) |
|
||||
| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Kun wiki-publicering gennem det ældre scoped workflow: lad markøren være tom, eller skriv kun ordet `prune` i den |
|
||||
| `The prune input must be 'true' or 'false'` | configuration | Kun wiki-publicering: sæt `prune` i kaldet til `"true"` eller `"false"` |
|
||||
| `The wiki folder ... does not exist` | configuration | Kun wiki-publicering: sæt `wiki_dir` i kaldet til mappen med siderne (standard `docs/wiki`) |
|
||||
| `... HTTP 403 ...` ved publicering af wikien | permissions | Kun wiki-publicering: tokenet skal have `write:repository` og skriveadgang til dette repository |
|
||||
| `The wiki is not enabled on <repo>` | configuration | Kun wiki-publicering: aktivér wikien i repositoryets indstillinger |
|
||||
| `The wiki source directory ... has no Markdown pages` | configuration | Kun wiki-publicering: mappen har ingen Markdown-sider; intet blev ændret |
|
||||
| `Could not determine the GitHub owner and repository ...` | configuration | Spejlets adresse skal se ud som `https://github.com/<owner>/<repo>.git` |
|
||||
| `Gitea API request failed with HTTP 401` | credentials | Opret et nyt Gitea-token, og opdatér `TOKEN_FOR_GITEA` |
|
||||
| `GitHub API request failed with HTTP 401` | credentials | Opret et nyt GitHub-token, og opdatér `PAT_FOR_GITHUB`; værdien skal kun være tokenet (intet navn, ingen anførselstegn eller JSON) |
|
||||
| `... HTTP 403 ...` (Gitea) | permissions | Tokenet skal have `read:repository`, og dets bruger skal være administrator af repositoryet |
|
||||
| `... HTTP 403 ...` (GitHub) | permissions | Tokenet skal have Administration read and write på spejl-repositoryet |
|
||||
| `The GitHub token cannot administer <repo>` | permissions | Som ovenfor; tokenet kan læse repositoryet, men ikke redigere det |
|
||||
| `... HTTP 404 ...` | configuration | Repositoryet blev ikke fundet, eller tokenet kan ikke se det; kontroller spejlets adresse og tokenets adgang til repositoryet |
|
||||
| `... HTTP 5xx ...` | api | Problem hos tjenesten; kør igen senere |
|
||||
| `... API is unreachable ...` | api | Netværks-, DNS- eller proxyproblem på runneren |
|
||||
|
||||
## Ikke en fejl
|
||||
|
||||
`No GitHub push mirror configured for <repo>; nothing to sync.` efterfulgt af `Skipped`. Kørslen lykkes. Ikke alle Gitea-repositories har et GitHub-spejl, så det er forventet for dem. Hvis repositoryet skal have et, så tilføj det i repositoryets indstillinger.
|
||||
|
||||
`WARNING: Gitea returned an invalid push mirror list; GitHub metadata was not synced.` Kørslen lykkes, men intet blev synkroniseret. Kontroller, at Gitea-versionen understøtter push mirror-API'et, og kør igen.
|
||||
|
||||
`No wiki/.publish marker in <owner>/<repo>; wiki publishing is not enabled for this repository.` Kørslen af det ældre scoped Publish wiki lykkes og skriver intet. Repositoryet har ikke meldt sig til; kald det genbrugelige workflow **Publish wiki pages** (se [onboarding.md](Onboarding.da)), hvis det skal publicere.
|
||||
|
||||
`<n> page(s) are in the wiki but not in <folder>/ and were kept; set the prune input to true to delete them.` Kørslen lykkes. Sider, der kun findes i wikien, lades i fred, medmindre kaldet sætter `prune: "true"` (med det ældre scoped workflow: ordet `prune` i `wiki/.publish`).
|
||||
|
||||
## Runner-problemer
|
||||
|
||||
Se afsnittet [Runners](Onboarding.da#runners). Kort sagt: hvis kørslen bliver stående som `waiting`, har ingen online runner labelen; hvis jobbet fejler før scriptet, mangler runner-imaget et værktøj.
|
||||
|
||||
## Ny kørsel
|
||||
|
||||
Brug **Run workflow** (`workflow_dispatch`), når årsagen er rettet. Synkroniseringen kan trygt gentages: den overskriver GitHub-beskrivelsen og -emnerne med værdierne fra Gitea.
|
||||
@@ -0,0 +1,83 @@
|
||||
<!-- 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.
|
||||
|
||||
English | [Dansk](Troubleshooting.da) | [Bahasa Melayu](Troubleshooting.ms)
|
||||
|
||||
# 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 |
|
||||
| --- | --- | --- |
|
||||
| `PAT_FOR_GITHUB is missing or empty.` | configuration | Add the secret |
|
||||
| `TOKEN_FOR_GITEA is missing or empty.` | configuration | Add the secret |
|
||||
| `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 |
|
||||
| `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Wiki publishing only: the repository calls the workflow but its organization has no such secret, or the call does not pass it; store it and pass it in `secrets:` (see [credentials.md](Credentials)) |
|
||||
| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Wiki publishing through the older scoped workflow only: leave the marker empty, or put only the word `prune` in it |
|
||||
| `The prune input must be 'true' or 'false'` | configuration | Wiki publishing only: set `prune` in the call to `"true"` or `"false"` |
|
||||
| `The wiki folder ... does not exist` | configuration | Wiki publishing only: set `wiki_dir` in the call to the folder with the pages (default `docs/wiki`) |
|
||||
| `... HTTP 403 ...` while publishing the wiki | permissions | Wiki publishing only: the token needs `write:repository` and write access to this repository |
|
||||
| `The wiki is not enabled on <repo>` | configuration | Wiki publishing only: enable the wiki in the repository settings |
|
||||
| `The wiki source directory ... has no Markdown pages` | configuration | Wiki publishing only: the folder has no Markdown pages; nothing was changed |
|
||||
| `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 `PAT_FOR_GITHUB`; the value must be the token only (no name, quotes or JSON) |
|
||||
| `... 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.` followed by
|
||||
`Skipped`. 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.
|
||||
|
||||
`No wiki/.publish marker in <owner>/<repo>; wiki publishing is not enabled for
|
||||
this repository.` The older scoped Publish wiki run succeeds and writes
|
||||
nothing. The repository has not opted in; call the reusable workflow
|
||||
**Publish wiki pages** (see [onboarding.md](Onboarding)) if it should publish.
|
||||
|
||||
`<n> page(s) are in the wiki but not in <folder>/ and were kept; set the prune
|
||||
input to true to delete them.` The run succeeds. Pages that exist only in the
|
||||
wiki are left alone unless the call sets `prune: "true"` (with the older scoped
|
||||
workflow: the word `prune` in `wiki/.publish`).
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,66 @@
|
||||
<!-- translation of Troubleshooting.md, source sha256 c68827295812 -->
|
||||
|
||||
> Ini ialah terjemahan [`Troubleshooting`](Troubleshooting). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
|
||||
|
||||
[English](Troubleshooting) | [Dansk](Troubleshooting.da) | Bahasa Melayu
|
||||
|
||||
# Mendiagnosis larian yang gagal
|
||||
|
||||
Buka larian dalam Gitea (Actions) dan baca baris terakhir langkah yang gagal. Setiap kegagalan daripada skrip penyegerakan ditulis sebagai
|
||||
|
||||
```
|
||||
ERROR: [<category>] <message>
|
||||
```
|
||||
|
||||
Kategori menunjukkan di mana perlu dilihat. Kegagalan di luar skrip (kerja tidak pernah bermula, atau berhenti sebelum langkah itu) ialah masalah **runner**.
|
||||
|
||||
| Kategori | Maksud | Perkara pertama yang disemak |
|
||||
| --- | --- | --- |
|
||||
| `configuration` | Secret atau tetapan repositori tiada atau tidak betul bentuknya | Nama dan format secret, penyediaan push mirror |
|
||||
| `credentials` | Satu perkhidmatan menolak token (HTTP 401) | Token tamat tempoh, dibatalkan atau tersalah taip |
|
||||
| `permissions` | Token sah tetapi tidak dibenarkan (HTTP 403, atau tiada akses pentadbiran GitHub) | Skop token dan akses repositori |
|
||||
| `api` | Ralat HTTP lain, atau perkhidmatan tidak dapat dicapai | Status perkhidmatan, rangkaian runner |
|
||||
| runner | Tiada baris `ERROR:`; larian menunggu, atau kerja gagal sebelum skrip | Runner dalam talian, label, alat |
|
||||
|
||||
## Mesej dan pembetulan
|
||||
|
||||
| Mesej (permulaan) | Kategori | Punca dan pembetulan |
|
||||
| --- | --- | --- |
|
||||
| `PAT_FOR_GITHUB is missing or empty.` | configuration | Tambah secret |
|
||||
| `TOKEN_FOR_GITEA is missing or empty.` | configuration | Tambah secret |
|
||||
| `Could not determine the Gitea source repository.` | configuration | Larian tiada nama repositori; laporkan sebagai kecacatan |
|
||||
| `Expected at most one GitHub push mirror ... found N` | configuration | Kekalkan satu push mirror GitHub |
|
||||
| `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Penerbitan wiki sahaja: repositori memanggil aliran kerja tetapi organisasinya tiada secret itu, atau panggilan tidak menghantarnya; simpannya dan hantar dalam `secrets:` (lihat [credentials.md](Credentials.ms)) |
|
||||
| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Penerbitan wiki melalui aliran kerja scoped yang lebih lama sahaja: biarkan penanda kosong, atau letakkan hanya perkataan `prune` di dalamnya |
|
||||
| `The prune input must be 'true' or 'false'` | configuration | Penerbitan wiki sahaja: tetapkan `prune` dalam panggilan kepada `"true"` atau `"false"` |
|
||||
| `The wiki folder ... does not exist` | configuration | Penerbitan wiki sahaja: tetapkan `wiki_dir` dalam panggilan kepada folder yang mengandungi halaman (lalai `docs/wiki`) |
|
||||
| `... HTTP 403 ...` semasa menerbitkan wiki | permissions | Penerbitan wiki sahaja: token memerlukan `write:repository` dan akses tulis kepada repositori ini |
|
||||
| `The wiki is not enabled on <repo>` | configuration | Penerbitan wiki sahaja: aktifkan wiki dalam tetapan repositori |
|
||||
| `The wiki source directory ... has no Markdown pages` | configuration | Penerbitan wiki sahaja: folder itu tiada halaman Markdown; tiada apa-apa diubah |
|
||||
| `Could not determine the GitHub owner and repository ...` | configuration | Alamat cermin mesti kelihatan seperti `https://github.com/<owner>/<repo>.git` |
|
||||
| `Gitea API request failed with HTTP 401` | credentials | Cipta token Gitea baharu dan kemas kini `TOKEN_FOR_GITEA` |
|
||||
| `GitHub API request failed with HTTP 401` | credentials | Cipta token GitHub baharu dan kemas kini `PAT_FOR_GITHUB`; nilai mesti token sahaja (tiada nama, tanda petikan atau JSON) |
|
||||
| `... HTTP 403 ...` (Gitea) | permissions | Token memerlukan `read:repository`, dan penggunanya mesti pentadbir repositori |
|
||||
| `... HTTP 403 ...` (GitHub) | permissions | Token memerlukan Administration read and write pada repositori cermin |
|
||||
| `The GitHub token cannot administer <repo>` | permissions | Sama seperti di atas; token boleh membaca repositori tetapi tidak boleh mengeditnya |
|
||||
| `... HTTP 404 ...` | configuration | Repositori tidak ditemui, atau token tidak dapat melihatnya; semak alamat cermin dan akses repositori token |
|
||||
| `... HTTP 5xx ...` | api | Masalah perkhidmatan; jalankan semula kemudian |
|
||||
| `... API is unreachable ...` | api | Masalah rangkaian, DNS atau proksi pada runner |
|
||||
|
||||
## Bukan satu ralat
|
||||
|
||||
`No GitHub push mirror configured for <repo>; nothing to sync.` diikuti oleh `Skipped`. Larian berjaya. Tidak semua repositori Gitea mempunyai cermin GitHub, jadi ini dijangka bagi repositori tersebut. Jika repositori itu sepatutnya mempunyainya, tambahkannya dalam tetapan repositori.
|
||||
|
||||
`WARNING: Gitea returned an invalid push mirror list; GitHub metadata was not synced.` Larian berjaya tetapi tiada apa-apa disegerakkan. Semak bahawa versi Gitea menyokong API push mirror dan jalankan semula.
|
||||
|
||||
`No wiki/.publish marker in <owner>/<repo>; wiki publishing is not enabled for this repository.` Larian Publish wiki scoped yang lebih lama berjaya dan tidak menulis apa-apa. Repositori belum memilih menyertainya; panggil aliran kerja boleh guna semula **Publish wiki pages** (lihat [onboarding.md](Onboarding.ms)) jika ia sepatutnya menerbitkan.
|
||||
|
||||
`<n> page(s) are in the wiki but not in <folder>/ and were kept; set the prune input to true to delete them.` Larian berjaya. Halaman yang hanya ada dalam wiki dibiarkan melainkan panggilan menetapkan `prune: "true"` (dengan aliran kerja scoped yang lebih lama: perkataan `prune` dalam `wiki/.publish`).
|
||||
|
||||
## Masalah runner
|
||||
|
||||
Lihat bahagian [Runners](Onboarding.ms#runners). Ringkasnya: jika larian kekal `waiting`, tiada runner dalam talian yang mempunyai label itu; jika kerja gagal sebelum skrip, imej runner tiada satu alat.
|
||||
|
||||
## Menjalankan semula
|
||||
|
||||
Gunakan **Run workflow** (`workflow_dispatch`) selepas puncanya dibetulkan. Penyegerakan selamat diulang: ia menimpa penerangan dan topik GitHub dengan nilai daripada Gitea.
|
||||
@@ -0,0 +1,61 @@
|
||||
<!-- translation of Upgrading.md, source sha256 7fba937279b1 -->
|
||||
|
||||
> Dette er en oversættelse af [`Upgrading`](Upgrading). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
|
||||
|
||||
[English](Upgrading) | Dansk | [Bahasa Melayu](Upgrading.ms)
|
||||
|
||||
# Opgradering til en ny version af de fælles workflows
|
||||
|
||||
Sådan tager en softwareudvikler en ny udgivelse af de fælles workflows i brug uden risiko: læs changelog, prøv opdateringen ét sted, og gå tilbage, hvis den fejler. Versionsreglerne er udgivelsesprocessens: én version for hele repositoryet, tags `vMAJOR.MINOR.PATCH` og et flytbart major-tag `vMAJOR`.
|
||||
|
||||
## Hvilken version du følger
|
||||
|
||||
| I din `uses:`-linje | Du modtager | Brug den, når |
|
||||
| --- | --- | --- |
|
||||
| `@v1.2.0` | aldrig noget nyt | en pipeline ikke må ændre sig |
|
||||
| `@v1` | kun kompatible udgivelser (minor og patch) | standardvalget for et projekt |
|
||||
| `@main` | alt, også uudgivet | aldrig; kun til dette repositorys egne tests |
|
||||
|
||||
En udgivelse, der bryder kompatibiliteten, får en ny major-version (`v2`), så en pipeline på `@v1` aldrig modtager den, før du selv ændrer linjen.
|
||||
|
||||
Kvalitetskontrol-workflowene (`quality-checks.yml`, `quality-checks-cpp.yml` og `quality-checks-csharp.yml`) henter deres script ved deres input `tools-ref`, som som standard er `v1`. For at fastlåse et helt skal du kalde det ved et præcist tag og sætte `tools-ref` til samme tag; ellers følger scriptet major-tagget.
|
||||
|
||||
De to scoped workflows (**Sync GitHub mirror metadata** og **Publish wiki**) leveres af instansen og står ikke i dine `uses:`-linjer; du kan ikke fastlåse dem, men de henter deres scripts ved major-tagget.
|
||||
|
||||
## Aflæsning af en changelog-post
|
||||
|
||||
Åbn `CHANGELOG.md` i `TirSystem/github-action` eller tagget udgivelsesside. En post har op til fire grupper:
|
||||
|
||||
| Gruppe | Hvad den betyder for dig |
|
||||
| --- | --- |
|
||||
| Breaking | Du skal handle: et navn, et input, en secret eller en standardværdi er ændret. En udgivelse med denne gruppe har en ny major-version |
|
||||
| Added | Intet at gøre; et nyt valgfrit input, workflow eller en ny funktion |
|
||||
| Changed | Intet at gøre; ingen synlig virkning for eksisterende kaldere |
|
||||
| Fixed | Intet at gøre; en rettelse, du modtager på `@v1` |
|
||||
|
||||
En post, der ændrer credentials, tokens eller tilladelser, siger det; kontroller dine secrets, før du opgraderer.
|
||||
|
||||
## Afprøvning af en opdatering
|
||||
|
||||
1. Ændr versionen i **ét** repository på en gren:
|
||||
```yaml
|
||||
jobs:
|
||||
quality:
|
||||
uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v2
|
||||
```
|
||||
2. Åbn en pull request, og læs kørslen. En mislykket kontrol viser værktøj, fil og meddelelse (se vejledningen til aflæsning af kvalitetskontrollens resultater).
|
||||
3. For en udgivelse, der bryder kompatibiliteten, følges opgraderingsnoterne i changelog-posten, og trinnet gentages.
|
||||
4. Når pull requesten er grøn, foretages den samme ændring i de øvrige repositories.
|
||||
|
||||
## Tilbage igen
|
||||
|
||||
1. Ret linjen tilbage til det forrige præcise tag, fx `@v1.2.0`, og flet. Præcise tags slettes eller flyttes aldrig, så det virker altid.
|
||||
2. Fortæl vedligeholderne, hvilken udgivelse der fejlede, og hvad du så, så major-tagget kan flyttes tilbage og en rettelse udgives.
|
||||
|
||||
## Når noget er uklart
|
||||
|
||||
| Symptom | Sandsynlig årsag | Rettelse |
|
||||
| --- | --- | --- |
|
||||
| Kørslen siger, at workflowet ikke kan findes | Tagget findes ikke, eller stien er forkert | Kontroller tagget på udgivelsessiden og stien `.gitea/workflows/quality-checks.yml` |
|
||||
| En grøn pipeline blev rød efter en udgivelse på `@v1` | En kompatibel udgivelse burde ikke gøre det | Fastlås det forrige præcise tag, og meld det som en defekt |
|
||||
| Et input accepteres ikke længere | En udgivelse, der bryder kompatibiliteten, har omdøbt det | Læs gruppen Breaking i posten |
|
||||
@@ -0,0 +1,77 @@
|
||||
<!-- Generated from guides/upgrading.md by tools/build_wiki.py. Edit the source, not this page. -->
|
||||
|
||||
> This page is generated from [`guides/upgrading.md`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/upgrading.md). Changes made here are overwritten the next time the wiki is published.
|
||||
|
||||
English | [Dansk](Upgrading.da) | [Bahasa Melayu](Upgrading.ms)
|
||||
|
||||
# Upgrading to a new version of the shared workflows
|
||||
|
||||
How a software engineer adopts a new release of the shared workflows safely:
|
||||
read the changelog, try the update in one place, and go back if it fails. The
|
||||
version rules are those of the release process: one version for the whole
|
||||
repository, tags `vMAJOR.MINOR.PATCH` and a moving major tag `vMAJOR`.
|
||||
|
||||
## Which version you follow
|
||||
|
||||
| In your `uses:` line | You receive | When to use it |
|
||||
| --- | --- | --- |
|
||||
| `@v1.2.0` | nothing new, ever | a pipeline that must not change |
|
||||
| `@v1` | compatible releases only (minor and patch) | the default for a project |
|
||||
| `@main` | everything, unreleased | never; only for this repository's own tests |
|
||||
|
||||
A breaking release gets a new major version (`v2`), so a pipeline on `@v1`
|
||||
never receives it until you change the line yourself.
|
||||
|
||||
The quality-checks workflows (`quality-checks.yml`, `quality-checks-cpp.yml` and
|
||||
`quality-checks-csharp.yml`) fetch their script at their input `tools-ref`, which
|
||||
defaults to `v1`. To pin one completely, call it at an exact tag and set
|
||||
`tools-ref` to the same tag; otherwise the script follows the major tag.
|
||||
|
||||
The two scoped workflows (**Sync GitHub mirror metadata** and **Publish
|
||||
wiki**) are delivered by the instance and are not in your `uses:` lines; you
|
||||
cannot pin them, but they fetch their scripts at the major tag.
|
||||
|
||||
## Reading a changelog entry
|
||||
|
||||
Open `CHANGELOG.md` of `TirSystem/github-action`, or the release page of the tag.
|
||||
An entry has up to four groups:
|
||||
|
||||
| Group | What it means for you |
|
||||
| --- | --- |
|
||||
| Breaking | You must act: a name, an input, a secret or a default changed. A release with this group has a new major version |
|
||||
| Added | Nothing to do; a new optional input, workflow or capability |
|
||||
| Changed | Nothing to do; no visible effect for existing callers |
|
||||
| Fixed | Nothing to do; a fix you receive on `@v1` |
|
||||
|
||||
An entry that changes credentials, tokens or permissions says so; check your
|
||||
secrets before you upgrade.
|
||||
|
||||
## Trying an update
|
||||
|
||||
1. Change the version in **one** repository, on a branch:
|
||||
```yaml
|
||||
jobs:
|
||||
quality:
|
||||
uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v2
|
||||
```
|
||||
2. Open a pull request and read the run. A failing check shows the tool, the
|
||||
file and the message (see the guide for reading quality-check results).
|
||||
3. For a breaking release, follow the upgrade notes of the changelog entry,
|
||||
then repeat.
|
||||
4. When the pull request is green, make the same change in the other
|
||||
repositories.
|
||||
|
||||
## Going back
|
||||
|
||||
1. Change the line back to the previous exact tag, for example `@v1.2.0`, and
|
||||
merge it. Exact tags are never deleted or moved, so this always works.
|
||||
2. Tell the maintainers which release failed and what you saw, so that the
|
||||
major tag can be moved back and a fix released.
|
||||
|
||||
## When something is unclear
|
||||
|
||||
| Symptom | Likely cause | Fix |
|
||||
| --- | --- | --- |
|
||||
| The run says the workflow cannot be found | The tag does not exist, or the path is wrong | Check the tag on the release page and the path `.gitea/workflows/quality-checks.yml` |
|
||||
| A green pipeline turned red after a release on `@v1` | A compatible release should not do this | Pin the previous exact tag and report it as a defect |
|
||||
| An input is no longer accepted | A breaking release renamed it | Read the Breaking group of the entry |
|
||||
@@ -0,0 +1,61 @@
|
||||
<!-- translation of Upgrading.md, source sha256 7fba937279b1 -->
|
||||
|
||||
> Ini ialah terjemahan [`Upgrading`](Upgrading). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
|
||||
|
||||
[English](Upgrading) | [Dansk](Upgrading.da) | Bahasa Melayu
|
||||
|
||||
# Menaik taraf kepada versi baharu aliran kerja bersama
|
||||
|
||||
Cara seorang jurutera perisian menerima keluaran baharu aliran kerja bersama dengan selamat: baca changelog, cuba kemas kini di satu tempat, dan berpatah balik jika gagal. Peraturan versi ialah peraturan proses keluaran: satu versi untuk seluruh repositori, tag `vMAJOR.MINOR.PATCH` dan tag major yang boleh digerakkan `vMAJOR`.
|
||||
|
||||
## Versi yang anda ikuti
|
||||
|
||||
| Dalam baris `uses:` anda | Anda menerima | Gunakan apabila |
|
||||
| --- | --- | --- |
|
||||
| `@v1.2.0` | tiada apa-apa yang baharu, selama-lamanya | saluran paip tidak boleh berubah |
|
||||
| `@v1` | keluaran serasi sahaja (minor dan patch) | pilihan lalai untuk sesebuah projek |
|
||||
| `@main` | semuanya, termasuk yang belum dikeluarkan | jangan sekali-kali; hanya untuk ujian repositori ini sendiri |
|
||||
|
||||
Keluaran yang memecahkan keserasian mendapat versi major baharu (`v2`), jadi saluran paip pada `@v1` tidak menerimanya sehingga anda sendiri menukar baris itu.
|
||||
|
||||
Aliran kerja semakan kualiti (`quality-checks.yml`, `quality-checks-cpp.yml` dan `quality-checks-csharp.yml`) mengambil skripnya pada inputnya `tools-ref`, yang lalai ialah `v1`. Untuk menyematkan satu sepenuhnya, panggil pada tag tepat dan tetapkan `tools-ref` kepada tag yang sama; jika tidak, skrip mengikuti tag major.
|
||||
|
||||
Dua aliran kerja scoped (**Sync GitHub mirror metadata** dan **Publish wiki**) dihantar oleh instans dan tidak terdapat dalam baris `uses:` anda; anda tidak boleh menyematkannya, tetapi ia mengambil skripnya pada tag major.
|
||||
|
||||
## Membaca satu catatan changelog
|
||||
|
||||
Buka `CHANGELOG.md` bagi `TirSystem/github-action`, atau halaman keluaran tag itu. Satu catatan mempunyai sehingga empat kumpulan:
|
||||
|
||||
| Kumpulan | Maksudnya untuk anda |
|
||||
| --- | --- |
|
||||
| Breaking | Anda mesti bertindak: nama, input, secret atau nilai lalai telah berubah. Keluaran dengan kumpulan ini mempunyai versi major baharu |
|
||||
| Added | Tiada apa-apa untuk dibuat; input pilihan, aliran kerja atau keupayaan baharu |
|
||||
| Changed | Tiada apa-apa untuk dibuat; tiada kesan yang kelihatan bagi pemanggil sedia ada |
|
||||
| Fixed | Tiada apa-apa untuk dibuat; pembetulan yang anda terima pada `@v1` |
|
||||
|
||||
Catatan yang mengubah kelayakan (credentials), token atau kebenaran menyatakannya; semak secret anda sebelum menaik taraf.
|
||||
|
||||
## Mencuba satu kemas kini
|
||||
|
||||
1. Tukar versi dalam **satu** repositori, pada satu cabang:
|
||||
```yaml
|
||||
jobs:
|
||||
quality:
|
||||
uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v2
|
||||
```
|
||||
2. Buka pull request dan baca larian. Semakan yang gagal menunjukkan alat, fail dan mesej (lihat panduan membaca keputusan semakan kualiti).
|
||||
3. Bagi keluaran yang memecahkan keserasian, ikut nota naik taraf dalam catatan changelog, kemudian ulang.
|
||||
4. Apabila pull request hijau, buat perubahan yang sama dalam repositori lain.
|
||||
|
||||
## Berpatah balik
|
||||
|
||||
1. Tukar baris itu kembali kepada tag tepat yang terdahulu, contohnya `@v1.2.0`, dan gabungkan. Tag tepat tidak pernah dipadam atau digerakkan, jadi ini sentiasa berfungsi.
|
||||
2. Beritahu penyelenggara keluaran mana yang gagal dan apa yang anda lihat, supaya tag major boleh digerakkan balik dan pembetulan dikeluarkan.
|
||||
|
||||
## Apabila ada yang tidak jelas
|
||||
|
||||
| Gejala | Punca yang mungkin | Pembetulan |
|
||||
| --- | --- | --- |
|
||||
| Larian menyatakan aliran kerja tidak ditemui | Tag tidak wujud, atau laluan salah | Semak tag pada halaman keluaran dan laluan `.gitea/workflows/quality-checks.yml` |
|
||||
| Saluran paip hijau menjadi merah selepas keluaran pada `@v1` | Keluaran serasi tidak sepatutnya berbuat demikian | Sematkan tag tepat yang terdahulu dan laporkan sebagai kecacatan |
|
||||
| Satu input tidak lagi diterima | Keluaran yang memecahkan keserasian menamakannya semula | Baca kumpulan Breaking dalam catatan itu |
|
||||
@@ -0,0 +1,39 @@
|
||||
<!-- Generated by tools/build_wiki.py. Edit the generator, not this page. -->
|
||||
|
||||
**TirSystem GitHub Actions**
|
||||
|
||||
**English**
|
||||
|
||||
- [Home](Home)
|
||||
- [Onboarding](Onboarding)
|
||||
- [Credentials](Credentials)
|
||||
- [Troubleshooting](Troubleshooting)
|
||||
- [Quality checks (Python, shell)](QualityChecksPythonShell)
|
||||
- [Quality checks (C and C++)](QualityChecksCpp)
|
||||
- [Quality checks (C#)](QualityChecksCSharp)
|
||||
- [Upgrading](Upgrading)
|
||||
- [Capabilities](Capabilities)
|
||||
|
||||
**Dansk**
|
||||
|
||||
- [Hjem](Home.da)
|
||||
- [Tilslutning](Onboarding.da)
|
||||
- [Credentials](Credentials.da)
|
||||
- [Fejlfinding](Troubleshooting.da)
|
||||
- [Kvalitetskontrol (Python, shell)](QualityChecksPythonShell.da)
|
||||
- [Kvalitetskontrol (C og C++)](QualityChecksCpp.da)
|
||||
- [Kvalitetskontrol (C#)](QualityChecksCSharp.da)
|
||||
- [Opgradering](Upgrading.da)
|
||||
- [Kapabiliteter](Capabilities.da)
|
||||
|
||||
**Bahasa Melayu**
|
||||
|
||||
- [Utama](Home.ms)
|
||||
- [Menyertakan](Onboarding.ms)
|
||||
- [Kelayakan](Credentials.ms)
|
||||
- [Diagnosis](Troubleshooting.ms)
|
||||
- [Semakan kualiti (Python, shell)](QualityChecksPythonShell.ms)
|
||||
- [Semakan kualiti (C dan C++)](QualityChecksCpp.ms)
|
||||
- [Semakan kualiti (C#)](QualityChecksCSharp.ms)
|
||||
- [Menaik taraf](Upgrading.ms)
|
||||
- [Keupayaan](Capabilities.ms)
|
||||
Reference in New Issue
Block a user