TirSystem/git-workflows
0
2
Fork 0
Code Issues 40 Pull Requests Actions Packages Projects Releases 11 Wiki Activity

Scoped wiki publishing (MIL-014) and rename to git-workflows (MIL-015) #219

Merged
Tirsvad merged 13 commits from mil-014-scoped-wiki-publishing into main 2026-10-27 16:34:30 +01:00
Conversation 0 Commits 13 Files Changed 41
+110 -150
6 changed files with 110 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit e8ca0073a6 - Show all commits
.gitea/scoped_workflows/publish-wiki-pages.yml
+52
View File
@@ -0,0 +1,52 @@
name: Publish wiki
# Scoped workflow: it runs in every repository of an organization, so there is
# no caller and no input. A repository opts in by having a docs/wiki folder; a
# repository without one is skipped. It publishes the Markdown pages of
# docs/wiki to the wiki of the repository, creating and updating pages and
# keeping the pages that are not in the folder. The script is a file of
# TirSystem/github-action (tools/publish_wiki.py), fetched at v2.
on:
push:
branches: [ main ]
paths:
- "docs/wiki/**"
workflow_dispatch:
jobs:
publish-wiki:
permissions:
contents: read
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Check out the repository
uses: actions/checkout@v4.2.2
- name: Look for the wiki folder
id: source
run: |
if [ -d docs/wiki ]; then
echo "found=true" >> "$GITHUB_OUTPUT"
else
echo "found=false" >> "$GITHUB_OUTPUT"
echo "No docs/wiki folder in this repository; nothing to publish."
fi
- name: Fetch the shared script
if: steps.source.outputs.found == 'true'
uses: actions/checkout@v4.2.2
with:
repository: TirSystem/github-action
ref: v2
path: shared-scripts
- name: Publish the pages to the wiki
if: steps.source.outputs.found == 'true'
env:
GITEA_API_URL: ${{ gitea.api_url }}
SOURCE_REPOSITORY: ${{ gitea.repository }}
WIKI_CREDENTIALS: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
WIKI_DIR: docs/wiki
WIKI_PRUNE: "false"
run: python3 shared-scripts/tools/publish_wiki.py
.gitea/workflows/publish-own-wiki.yml
-25
View File
@@ -1,25 +0,0 @@
name: Publish own wiki
# Publishes the wiki of this repository from docs/wiki/ by calling the
# reusable workflow of this repository (ADR-0009, MIL-008 task 4). It is the
# caller a project copies from framework/templates/ci/publish-wiki.yml, with
# two differences: the reusable workflow is called by its local path, and
# tools-ref is main so that the script that is run is the one of this commit.
on:
push:
branches: [ main ]
paths:
- "docs/wiki/**"
workflow_dispatch:
jobs:
wiki:
permissions:
contents: read
uses: ./.gitea/workflows/publish-wiki-pages.yml
with:
wiki_dir: docs/wiki
prune: "true"
tools-ref: main
secrets:
TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
.gitea/workflows/publish-wiki-pages.yml
-64
View File
@@ -1,64 +0,0 @@
name: Publish wiki
# Reusable workflow (ADR-0009, MIL-008). A repository calls it with
#
# 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 }}
#
# The caller file is the opt-in; there is no marker file. It publishes the
# Markdown pages of wiki_dir to the wiki of the calling repository, creating
# and updating pages, and deleting pages that are not in the folder only when
# prune is true. The script is a file of this repository
# (tools/publish_wiki.py), fetched at tools-ref.
on:
workflow_call:
inputs:
wiki_dir:
description: "Directory, relative to the repository root, with the wiki pages"
type: string
default: "docs/wiki"
prune:
description: "true deletes wiki pages that are not in the folder; false keeps them"
type: string
default: "false"
tools-ref:
description: "Tag or branch of TirSystem/github-action whose tools/publish_wiki.py is run; pin it to the exact tag together with the workflow"
type: string
default: "v2"
secrets:
TOKEN_FOR_GITEA_WIKI:
description: "Gitea token with write access to the wiki of the calling repository"
required: true
jobs:
publish-wiki:
permissions:
contents: read
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Check out the repository
uses: actions/checkout@v4.2.2
- name: Fetch the shared script
uses: actions/checkout@v4.2.2
with:
repository: TirSystem/github-action
ref: ${{ inputs.tools-ref }}
path: shared-scripts
- name: Publish the pages to the wiki
env:
GITEA_API_URL: ${{ gitea.api_url }}
SOURCE_REPOSITORY: ${{ gitea.repository }}
WIKI_CREDENTIALS: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
WIKI_DIR: ${{ inputs.wiki_dir }}
WIKI_PRUNE: ${{ inputs.prune }}
run: python3 shared-scripts/tools/publish_wiki.py
tests/fixtures/comments/english.tsv
Vendored
+9 -19
View File
@@ -3,7 +3,6 @@ en "string", "char" (a literal of one character) or "none" tools/count_loc.py
en (ADR-0008). The workflow checks out the calling repository, fetches this file tools/quality-checks-cpp.sh en (ADR-0008). The workflow checks out the calling repository, fetches this file tools/quality-checks-cpp.sh
en (MIL-004 task 6). The repository is public, so no token is needed. .gitea/scoped_workflows/sync-github-metadata.yml en (MIL-004 task 6). The repository is public, so no token is needed. .gitea/scoped_workflows/sync-github-metadata.yml
en (compile-commands-dir) are optional. .gitea/workflows/quality-checks-cpp.yml en (compile-commands-dir) are optional. .gitea/workflows/quality-checks-cpp.yml
en (tools/publish_wiki.py), fetched at tools-ref. .gitea/workflows/publish-wiki-pages.yml
en ----------------------------------------------------------------- helpers tests/test_quality_workflows_cpp_csharp.py en ----------------------------------------------------------------- helpers tests/test_quality_workflows_cpp_csharp.py
en --------------------------------------------------------------------- C# tests/test_quality_workflows_cpp_csharp.py en --------------------------------------------------------------------- C# tests/test_quality_workflows_cpp_csharp.py
en --------------------------------------------------------------------- C++ tests/test_quality_workflows_cpp_csharp.py en --------------------------------------------------------------------- C++ tests/test_quality_workflows_cpp_csharp.py
@@ -17,7 +16,7 @@ en A script run: the finished process and the tool calls the stubs logged. tests
en A source file or section needed for a page is missing. tools/build_wiki.py en A source file or section needed for a page is missing. tools/build_wiki.py
en A translation has the same code blocks, table rows and heading levels. tests/test_build_wiki.py en A translation has the same code blocks, table rows and heading levels. tests/test_build_wiki.py
en A wiki that already has pages named with spaces, as Gitea stores them. tests/test_publish_wiki.py en A wiki that already has pages named with spaces, as Gitea stores them. tests/test_publish_wiki.py
en ADR-0009, MIL-009: the scoped publish-wiki.yml and the marker are removed. tests/test_publish_wiki.py en ADR-0009: the marker file is removed. tests/test_publish_wiki.py
en An exact stable version of the .NET SDK, 10 or later (no channel, no range). tools/quality-checks-csharp.sh en An exact stable version of the .NET SDK, 10 or later (no channel, no range). tools/quality-checks-csharp.sh
en An input is invalid; the message is printed as a `[configuration]` failure. tools/badges.py en An input is invalid; the message is printed as a `[configuration]` failure. tools/badges.py
en Answers like the Gitea repository and wiki endpoints. tests/test_publish_wiki.py en Answers like the Gitea repository and wiki endpoints. tests/test_publish_wiki.py
@@ -60,7 +59,6 @@ en Leading emoji and symbols in README headings; removed so anchors stay stable.
en Link text of the sidebar: English, then one list per translation code. tools/build_wiki.py en Link text of the sidebar: English, then one list per translation code. tools/build_wiki.py
en Lint the shell scripts of the composite actions (MIL-012 task 6): shellcheck, tools/lint-action-scripts.sh en Lint the shell scripts of the composite actions (MIL-012 task 6): shellcheck, tools/lint-action-scripts.sh
en MIL-004 Go/No-Go criterion 5: every script is a file under tools/. tests/test_workflows.py en MIL-004 Go/No-Go criterion 5: every script is a file under tools/. tests/test_workflows.py
en Markdown pages of wiki_dir to the wiki of the calling repository, creating .gitea/workflows/publish-wiki-pages.yml
en Needs: bash, find, shellcheck, shfmt tools/lint-action-scripts.sh en Needs: bash, find, shellcheck, shfmt tools/lint-action-scripts.sh
en No translation follows an older version of its English page. tests/test_build_wiki.py en No translation follows an older version of its English page. tests/test_build_wiki.py
en Offline tests for the composite action actions/connect-tailscale. tests/test_connect_tailscale.py en Offline tests for the composite action actions/connect-tailscale. tests/test_connect_tailscale.py
@@ -82,7 +80,6 @@ en One `## [x]` section of the changelog. tools/changelog.py
en One generated wiki page. tools/build_wiki.py en One generated wiki page. tools/build_wiki.py
en Publish accepted milestones to the git host. .gitea/workflows/sync-milestones.yml en Publish accepted milestones to the git host. .gitea/workflows/sync-milestones.yml
en Publish the pages of a folder to the Gitea wiki of the repository. tools/publish_wiki.py en Publish the pages of a folder to the Gitea wiki of the repository. tools/publish_wiki.py
en Publishes the wiki of this repository from docs/wiki/ by calling the .gitea/workflows/publish-own-wiki.yml
en Publishing an empty directory would delete the whole wiki. tools/publish_wiki.py en Publishing an empty directory would delete the whole wiki. tools/publish_wiki.py
en PyYAML reads `on` as True tests/test_code_metrics.py en PyYAML reads `on` as True tests/test_code_metrics.py
en QC_DOTNET_INSTALL_SCRIPT, QC_DOTNET for tests). tools/quality-checks-csharp.sh en QC_DOTNET_INSTALL_SCRIPT, QC_DOTNET for tests). tools/quality-checks-csharp.sh
@@ -125,7 +122,6 @@ en Return the workflow files of this repository that a caller can use. tests/tes
en Return {page key: content} for every Markdown file in wiki_dir. tools/publish_wiki.py en Return {page key: content} for every Markdown file in wiki_dir. tools/publish_wiki.py
en Reusable workflow (ADR-0005). A repository calls it with .gitea/workflows/quality-checks.yml en Reusable workflow (ADR-0005). A repository calls it with .gitea/workflows/quality-checks.yml
en Reusable workflow (ADR-0008). A repository calls it with .gitea/workflows/quality-checks-cpp.yml en Reusable workflow (ADR-0008). A repository calls it with .gitea/workflows/quality-checks-cpp.yml
en Reusable workflow (ADR-0009, MIL-008). A repository calls it with .gitea/workflows/publish-wiki-pages.yml
en Reusable workflow (ADR-0010). A repository calls it with .gitea/workflows/code-metrics.yml en Reusable workflow (ADR-0010). A repository calls it with .gitea/workflows/code-metrics.yml
en Run a tool as `python tools/<name>` with only the given environment. tests/test_tool_entrypoints.py en Run a tool as `python tools/<name>` with only the given environment. tests/test_tool_entrypoints.py
en Run it once by hand from the Actions page with dry_run left on: it prints .gitea/workflows/sync-milestones.yml en Run it once by hand from the Actions page with dry_run left on: it prints .gitea/workflows/sync-milestones.yml
@@ -133,6 +129,7 @@ en Run the generator; return the process exit code. tools/build_wiki.py
en Run the script with a stub wg-quick that records its arguments. tests/test_connect_wireguard.py en Run the script with a stub wg-quick that records its arguments. tests/test_connect_wireguard.py
en SHELLCHECK_PY_VERSION, SHFMT_PY_VERSION, QC_VENV (and QC_BIN for tests). tools/quality-checks.sh en SHELLCHECK_PY_VERSION, SHFMT_PY_VERSION, QC_VENV (and QC_BIN for tests). tools/quality-checks.sh
en Scan one line; return (has_code, has_comment) and update the state. tools/count_loc.py en Scan one line; return (has_code, has_comment) and update the state. tools/count_loc.py
en Scoped workflow: it runs in every repository of an organization, so there is .gitea/scoped_workflows/publish-wiki-pages.yml
en Scoped workflow: it runs in every repository of an organization. The script .gitea/scoped_workflows/sync-github-metadata.yml en Scoped workflow: it runs in every repository of an organization. The script .gitea/scoped_workflows/sync-github-metadata.yml
en Secret: TOKEN_FOR_GITEA, the bare Gitea token of the organization (no JSON). .gitea/workflows/sync-milestones.yml en Secret: TOKEN_FOR_GITEA, the bare Gitea token of the organization (no JSON). .gitea/workflows/sync-milestones.yml
en Settings come from the environment, never from interpolated expressions: tools/code-metrics.sh en Settings come from the environment, never from interpolated expressions: tools/code-metrics.sh
@@ -145,7 +142,6 @@ en Steps of the reusable workflow .gitea/workflows/quality-checks-csharp.yml too
en Steps of the reusable workflow .gitea/workflows/quality-checks.yml (ADR-0005). tools/quality-checks.sh en Steps of the reusable workflow .gitea/workflows/quality-checks.yml (ADR-0005). tools/quality-checks.sh
en Strip heading emoji and rewrite links, leaving fenced code untouched. tools/build_wiki.py en Strip heading emoji and rewrite links, leaving fenced code untouched. tools/build_wiki.py
en Succeeds when one of the named files exists in the working directory or above tools/quality-checks-cpp.sh en Succeeds when one of the named files exists in the working directory or above tools/quality-checks-cpp.sh
en TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }} .gitea/workflows/publish-wiki-pages.yml
en TS_ARGS is split on spaces on purpose: it holds flags, never a secret actions/connect-tailscale/connect-tailscale.sh en TS_ARGS is split on spaces on purpose: it holds flags, never a secret actions/connect-tailscale/connect-tailscale.sh
en TS_AUTHKEY, TS_OAUTH_SECRET, TS_TAGS, TS_HOSTNAME, TS_VERSION, TS_USERSPACE, actions/connect-tailscale/connect-tailscale.sh en TS_AUTHKEY, TS_OAUTH_SECRET, TS_TAGS, TS_HOSTNAME, TS_VERSION, TS_USERSPACE, actions/connect-tailscale/connect-tailscale.sh
en TS_SHA256, TS_ARGS, TS_TIMEOUT, TS_HEALTH_CHECK_HOST. TS_TAILSCALE, actions/connect-tailscale/connect-tailscale.sh en TS_SHA256, TS_ARGS, TS_TIMEOUT, TS_HEALTH_CHECK_HOST. TS_TAILSCALE, actions/connect-tailscale/connect-tailscale.sh
@@ -154,16 +150,16 @@ en TS_WAIT_INTERVAL (seconds) name the commands, the work folder and the waits,
en The Home page names each workflow file of the repository and draws it. tests/test_build_wiki.py en The Home page names each workflow file of the repository and draws it. tests/test_build_wiki.py
en The `if __name__ == "__main__"` block: exit code 1 and ERROR: on stderr. tests/test_tool_entrypoints.py en The `if __name__ == "__main__"` block: exit code 1 and ERROR: on stderr. tests/test_tool_entrypoints.py
en The auth key is passed to tailscale in a file of mode 600, never on a command actions/connect-tailscale/connect-tailscale.sh en The auth key is passed to tailscale in a file of mode 600, never on a command actions/connect-tailscale/connect-tailscale.sh
en The caller file is the opt-in; there is no marker file. It publishes the .gitea/workflows/publish-wiki-pages.yml
en The comment and string rules of one language. tools/count_loc.py en The comment and string rules of one language. tools/count_loc.py
en The commit is the tip of the branch and its validation run is green. tools/release.py en The commit is the tip of the branch and its validation run is green. tools/release.py
en The default `tools-ref` of every reusable workflow names the current major. tests/test_tools_ref.py en The default `tools-ref` of every reusable workflow names the current major. tests/test_tools_ref.py
en The exclude patterns of the caller; a pattern without `/` matches a name anywhere. tools/count_loc.py en The exclude patterns of the caller; a pattern without `/` matches a name anywhere. tools/count_loc.py
en The page a link to a source file should point to. The README is the home page. tools/build_wiki.py en The page a link to a source file should point to. The README is the home page. tools/build_wiki.py
en The pages in wiki/ match what README.md and guides/ produce. tests/test_build_wiki.py en The pages in wiki/ match what README.md and guides/ produce. tests/test_build_wiki.py
en The reusable workflow sets WIKI_PRUNE: the caller is the opt-in (MIL-008). tests/test_publish_wiki.py en The scoped workflow sets WIKI_PRUNE: the docs/wiki folder is the opt-in. tests/test_publish_wiki.py
en The wiki of this repository equals docs/wiki/ (ADR-0009, MIL-008 task 4). tests/test_publish_wiki.py en The wiki of this repository equals docs/wiki/ (ADR-0009): the folder is the opt-in. tests/test_publish_wiki.py
en The workflow checks out the calling repository, fetches this file into tools/code-metrics.sh en The workflow checks out the calling repository, fetches this file into tools/code-metrics.sh
en TirSystem/github-action (tools/publish_wiki.py), fetched at v2. .gitea/scoped_workflows/publish-wiki-pages.yml
en Translate an exclude pattern: `*` stops at `/`, `**` crosses it, `?` is one character. tools/count_loc.py en Translate an exclude pattern: `*` stops at `/`, `**` crosses it, `?` is one character. tools/count_loc.py
en Translations (ADR-0001): `<Page>.<code>` written by hand in docs/wiki/. tools/build_wiki.py en Translations (ADR-0001): `<Page>.<code>` written by hand in docs/wiki/. tools/build_wiki.py
en True when the tag holds the file; True when the tag is not in this checkout. tests/test_tools_ref.py en True when the tag holds the file; True when the tag is not in this checkout. tests/test_tools_ref.py
@@ -196,12 +192,9 @@ en and `dotnet build` (warnings as errors) on an exact .NET SDK 10 or later, .gi
en and blank lines are not counted), reads an optional Cobertura XML coverage .gitea/workflows/code-metrics.yml en and blank lines are not counted), reads an optional Cobertura XML coverage .gitea/workflows/code-metrics.yml
en and nothing when none of them changed tools/code-metrics.sh en and nothing when none of them changed tools/code-metrics.sh
en and shfmt in the format .editorconfig sets (two spaces, indented case labels). tools/lint-action-scripts.sh en and shfmt in the format .editorconfig sets (two spaces, indented case labels). tools/lint-action-scripts.sh
en and updating pages, and deleting pages that are not in the folder only when .gitea/workflows/publish-wiki-pages.yml
en branches: [ main ] .gitea/workflows/publish-wiki-pages.yml
en branches: [main] .gitea/workflows/code-metrics.yml en branches: [main] .gitea/workflows/code-metrics.yml
en by default); WG_QUICK, WG_SUDO and WG_PING name the commands, for the tests. actions/connect-wireguard/connect-wireguard.sh en by default); WG_QUICK, WG_SUDO and WG_PING name the commands, for the tests. actions/connect-wireguard/connect-wireguard.sh
en by hand with the version to release; it creates the version tag, the release .gitea/workflows/release.yml en by hand with the version to release; it creates the version tag, the release .gitea/workflows/release.yml
en caller a project copies from framework/templates/ci/publish-wiki.yml, with .gitea/workflows/publish-own-wiki.yml
en changes no file and needs no secret. .gitea/workflows/quality-checks.yml en changes no file and needs no secret. .gitea/workflows/quality-checks.yml
en changes no file and needs no secret. The package restore needs the network. .gitea/workflows/quality-checks-csharp.yml en changes no file and needs no secret. The package restore needs the network. .gitea/workflows/quality-checks-csharp.yml
en clang-tidy at exact versions, changes no file and needs no secret. The .gitea/workflows/quality-checks-cpp.yml en clang-tidy at exact versions, changes no file and needs no secret. The .gitea/workflows/quality-checks-cpp.yml
@@ -222,6 +215,7 @@ en connect-wireguard.sh up write the configuration and bring the tunnel up actio
en contents: write .gitea/workflows/code-metrics.yml en contents: write .gitea/workflows/code-metrics.yml
en deleted. Each run updates the issues of every accepted milestone (the sync is .gitea/workflows/sync-milestones.yml en deleted. Each run updates the issues of every accepted milestone (the sync is .gitea/workflows/sync-milestones.yml
en directory under RUNNER_TEMP by default). tools/code-metrics.sh en directory under RUNNER_TEMP by default). tools/code-metrics.sh
en docs/wiki to the wiki of the repository, creating and updating pages and .gitea/scoped_workflows/publish-wiki-pages.yml
en env keeps the userspace variable through sudo; the file holds the key, so actions/connect-wireguard/connect-wireguard.sh en env keeps the userspace variable through sudo; the file holds the key, so actions/connect-wireguard/connect-wireguard.sh
en finding must fail the check, as a failing tool does for the other languages. tools/quality-checks-cpp.sh en finding must fail the check, as a failing tool does for the other languages. tools/quality-checks-cpp.sh
en for the tests. actions/connect-tailscale/connect-tailscale.sh en for the tests. actions/connect-tailscale/connect-tailscale.sh
@@ -232,6 +226,7 @@ en is a file of TirSystem/github-action (tools/sync_github_metadata.py), fetched
en is created or updated as a Milestone with its tasks as Issues. A Proposed .gitea/workflows/sync-milestones.yml en is created or updated as a Milestone with its tasks as Issues. A Proposed .gitea/workflows/sync-milestones.yml
en it is removed when the interface does not come up actions/connect-wireguard/connect-wireguard.sh en it is removed when the interface does not come up actions/connect-wireguard/connect-wireguard.sh
en it, up to the top of the repository: clang-format and clang-tidy find their tools/quality-checks-cpp.sh en it, up to the top of the repository: clang-format and clang-tidy find their tools/quality-checks-cpp.sh
en keeping the pages that are not in the folder. The script is a file of .gitea/scoped_workflows/publish-wiki-pages.yml
en latest Version History row is Accepted and whose latest review record is a Go .gitea/workflows/sync-milestones.yml en latest Version History row is Accepted and whose latest review record is a Go .gitea/workflows/sync-milestones.yml
en line, and nothing else, so the rest of the log stays readable actions/connect-wireguard/connect-wireguard.sh en line, and nothing else, so the rest of the log stays readable actions/connect-wireguard/connect-wireguard.sh
en line. Every failure is printed as ::error::[category] message. actions/connect-tailscale/connect-tailscale.sh en line. Every failure is printed as ::error::[category] message. actions/connect-tailscale/connect-tailscale.sh
@@ -239,6 +234,7 @@ en metrics: .gitea/workflows/code-metrics.yml
en milestone, or one without a Go review, is skipped. Nothing is closed or .gitea/workflows/sync-milestones.yml en milestone, or one without a Go review, is skipped. Nothing is closed or .gitea/workflows/sync-milestones.yml
en name -> (source, code, comment, blank), counted by hand. tests/test_count_loc.py en name -> (source, code, comment, blank), counted by hand. tests/test_count_loc.py
en names that start with GITEA_ or GITHUB_. .gitea/workflows/sync-milestones.yml en names that start with GITEA_ or GITHUB_. .gitea/workflows/sync-milestones.yml
en no caller and no input. A repository opts in by having a docs/wiki folder; a .gitea/scoped_workflows/publish-wiki-pages.yml
en no final newline tests/test_count_loc.py en no final newline tests/test_count_loc.py
en often has no sudo. TS_SUDO overrides it (empty for none). actions/connect-tailscale/connect-tailscale.sh en often has no sudo. TS_SUDO overrides it (empty for none). actions/connect-tailscale/connect-tailscale.sh
en often has no sudo. WG_SUDO overrides it (empty for none). actions/connect-wireguard/connect-wireguard.sh en often has no sudo. WG_SUDO overrides it (empty for none). actions/connect-wireguard/connect-wireguard.sh
@@ -249,10 +245,8 @@ en only the probe ran: no second daemon, no up tests/test_connect_tailscale.py
en outside this repository, so it gets a copy of the repository's file tests/test_lint_action_scripts.py en outside this repository, so it gets a copy of the repository's file tests/test_lint_action_scripts.py
en page from the changelog entry and moves the major tag, and only when the .gitea/workflows/release.yml en page from the changelog entry and moves the major tag, and only when the .gitea/workflows/release.yml
en parsed YAML has no fixed shape tests/test_quality_workflows_cpp_csharp.py en parsed YAML has no fixed shape tests/test_quality_workflows_cpp_csharp.py
en paths: [ "docs/wiki/**" ] .gitea/workflows/publish-wiki-pages.yml
en permissions: .gitea/workflows/code-metrics.yml en permissions: .gitea/workflows/code-metrics.yml
en pretend the kernel has WireGuard and the tools are present tests/test_connect_wireguard.py en pretend the kernel has WireGuard and the tools are present tests/test_connect_wireguard.py
en prune is true. The script is a file of this repository .gitea/workflows/publish-wiki-pages.yml
en quality-checks-cpp.sh install install the exact clang tool versions into a venv tools/quality-checks-cpp.sh en quality-checks-cpp.sh install install the exact clang tool versions into a venv tools/quality-checks-cpp.sh
en quality-checks-cpp.sh run run clang-format and clang-tidy on the tracked files tools/quality-checks-cpp.sh en quality-checks-cpp.sh run run clang-format and clang-tidy on the tracked files tools/quality-checks-cpp.sh
en quality-checks-cpp.sh validate check the inputs, before anything is installed tools/quality-checks-cpp.sh en quality-checks-cpp.sh validate check the inputs, before anything is installed tools/quality-checks-cpp.sh
@@ -267,11 +261,10 @@ en real/a.py only, not link.py tests/test_count_loc.py
en render_config: the wg-quick configuration on stdout actions/connect-wireguard/connect-wireguard.sh en render_config: the wg-quick configuration on stdout actions/connect-wireguard/connect-wireguard.sh
en report (an artifact of an earlier job of the caller, or a file of the .gitea/workflows/code-metrics.yml en report (an artifact of an earlier job of the caller, or a file of the .gitea/workflows/code-metrics.yml
en repository needs a .clang-format; a .clang-tidy and a compile database .gitea/workflows/quality-checks-cpp.yml en repository needs a .clang-format; a .clang-tidy and a compile database .gitea/workflows/quality-checks-cpp.yml
en repository without one is skipped. It publishes the Markdown pages of .gitea/scoped_workflows/publish-wiki-pages.yml
en repository) and commits three SVG badges to a branch of the calling .gitea/workflows/code-metrics.yml en repository) and commits three SVG badges to a branch of the calling .gitea/workflows/code-metrics.yml
en repository, which is checked out as a submodule. Gitea does not accept secret .gitea/workflows/sync-milestones.yml en repository, which is checked out as a submodule. Gitea does not accept secret .gitea/workflows/sync-milestones.yml
en repository. .gitea/workflows/code-metrics.yml en repository. .gitea/workflows/code-metrics.yml
en reusable workflow of this repository (ADR-0009, MIL-008 task 4). It is the .gitea/workflows/publish-own-wiki.yml
en secrets: .gitea/workflows/publish-wiki-pages.yml
en shared-scripts/ and runs one command per step: tools/code-metrics.sh en shared-scripts/ and runs one command per step: tools/code-metrics.sh
en shellcheck disable=SC2206 actions/connect-tailscale/connect-tailscale.sh en shellcheck disable=SC2206 actions/connect-tailscale/connect-tailscale.sh
en shfmt reads .editorconfig from the folder upwards; a temporary folder is tests/test_lint_action_scripts.py en shfmt reads .editorconfig from the folder upwards; a temporary folder is tests/test_lint_action_scripts.py
@@ -284,12 +277,9 @@ en the plan and creates nothing. Turn dry_run off only for a real run. .gitea/wo
en the project gets the compiler diagnostics and the static analyzer. tools/quality-checks-cpp.sh en the project gets the compiler diagnostics and the static analyzer. tools/quality-checks-cpp.sh
en the stub records its arguments and, for `up`, the content of the key file tests/test_connect_tailscale.py en the stub records its arguments and, for `up`, the content of the key file tests/test_connect_tailscale.py
en the tools are in the virtual environment of the interpreter that runs the tests tests/test_lint_action_scripts.py en the tools are in the virtual environment of the interpreter that runs the tests tests/test_lint_action_scripts.py
en tools-ref is main so that the script that is run is the one of this commit. .gitea/workflows/publish-own-wiki.yml
en two differences: the reusable workflow is called by its local path, and .gitea/workflows/publish-own-wiki.yml
en type: ignore[index] tools/changelog.py en type: ignore[index] tools/changelog.py
en type: ignore[return-value] tools/changelog.py en type: ignore[return-value] tools/changelog.py
en uses: TirSystem/github-action/.gitea/workflows/code-metrics.yml@v2 .gitea/workflows/code-metrics.yml en uses: TirSystem/github-action/.gitea/workflows/code-metrics.yml@v2 .gitea/workflows/code-metrics.yml
en uses: TirSystem/github-action/.gitea/workflows/publish-wiki-pages.yml@v1 .gitea/workflows/publish-wiki-pages.yml
en uses: TirSystem/github-action/.gitea/workflows/quality-checks-cpp.yml@v1 .gitea/workflows/quality-checks-cpp.yml en uses: TirSystem/github-action/.gitea/workflows/quality-checks-cpp.yml@v1 .gitea/workflows/quality-checks-cpp.yml
en uses: TirSystem/github-action/.gitea/workflows/quality-checks-csharp.yml@v1 .gitea/workflows/quality-checks-csharp.yml en uses: TirSystem/github-action/.gitea/workflows/quality-checks-csharp.yml@v1 .gitea/workflows/quality-checks-csharp.yml
en uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1 .gitea/workflows/quality-checks.yml en uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1 .gitea/workflows/quality-checks.yml
Can't render this file because it contains an unexpected character in line 2 and column 11.
tests/test_publish_wiki.py
+44 -38
View File
@@ -9,7 +9,7 @@ import yaml
from workflow_source import REPO_ROOT, load_publish_module from workflow_source import REPO_ROOT, load_publish_module
REUSABLE_WORKFLOW = REPO_ROOT / ".gitea" / "workflows" / "publish-wiki-pages.yml" SCOPED_WORKFLOW = REPO_ROOT / ".gitea" / "scoped_workflows" / "publish-wiki-pages.yml"
API = "https://git.example.test/api/v1" API = "https://git.example.test/api/v1"
REPO_URL = f"{API}/repos/TirSystem/repo" REPO_URL = f"{API}/repos/TirSystem/repo"
@@ -383,7 +383,7 @@ class TestRequestJson:
class TestExplicitPrune: class TestExplicitPrune:
"""The reusable workflow sets WIKI_PRUNE: the caller is the opt-in (MIL-008).""" """The scoped workflow sets WIKI_PRUNE: the docs/wiki folder is the opt-in."""
@pytest.fixture() @pytest.fixture()
def explicit(self, environment, monkeypatch): def explicit(self, environment, monkeypatch):
@@ -428,7 +428,7 @@ class TestExplicitPrune:
monkeypatch.setenv("WIKI_DIR", str(tmp_path / "docs" / "wiki")) monkeypatch.setenv("WIKI_DIR", str(tmp_path / "docs" / "wiki"))
gitea = FakeGitea(publish_wiki) gitea = FakeGitea(publish_wiki)
with pytest.raises(publish_wiki.WorkflowError, match="wiki_dir") as caught: with pytest.raises(publish_wiki.WorkflowError, match="WIKI_DIR") as caught:
run_main(publish_wiki, gitea) run_main(publish_wiki, gitea)
assert caught.value.category == "configuration" assert caught.value.category == "configuration"
@@ -460,59 +460,65 @@ class TestExplicitPrune:
assert gitea.calls == [] assert gitea.calls == []
class TestReusableWorkflow: class TestScopedWorkflow:
@pytest.fixture() @pytest.fixture()
def document(self): def document(self):
return yaml.safe_load(REUSABLE_WORKFLOW.read_text(encoding="utf-8")) return yaml.safe_load(SCOPED_WORKFLOW.read_text(encoding="utf-8"))
def test_is_called_and_has_no_other_trigger(self, document): @pytest.fixture()
assert list(document[True]) == ["workflow_call"] def steps(self, document):
return {step.get("id", step["name"]): step for step in document["jobs"]["publish-wiki"]["steps"]}
def test_the_folder_defaults_to_docs_wiki_and_nothing_is_pruned_by_default(self, document): def test_runs_on_a_push_to_main_and_by_hand_without_inputs(self, document):
inputs = document[True]["workflow_call"]["inputs"] triggers = document[True]
assert inputs["wiki_dir"]["default"] == "docs/wiki" assert list(triggers) == ["push", "workflow_dispatch"]
assert inputs["prune"]["default"] == "false" assert triggers["push"]["branches"] == ["main"]
assert not triggers["workflow_dispatch"]
def test_the_token_is_a_declared_secret_without_a_fallback(self, document): def test_a_push_runs_only_when_docs_wiki_changes(self, document):
text = REUSABLE_WORKFLOW.read_text(encoding="utf-8") assert document[True]["push"]["paths"] == ["docs/wiki/**"]
assert document[True]["workflow_call"]["secrets"]["TOKEN_FOR_GITEA_WIKI"]["required"]
def test_the_token_is_read_from_the_secret_without_a_fallback(self, document):
text = SCOPED_WORKFLOW.read_text(encoding="utf-8")
step = document["jobs"]["publish-wiki"]["steps"][-1]
assert step["env"]["WIKI_CREDENTIALS"] == "${{ secrets.TOKEN_FOR_GITEA_WIKI }}"
assert "secrets.TOKEN_FOR_GITEA }}" not in text assert "secrets.TOKEN_FOR_GITEA }}" not in text
assert "github.token" not in text assert "github.token" not in text
def test_job_has_read_only_permissions(self, document): def test_job_has_read_only_permissions(self, document):
assert document["jobs"]["publish-wiki"]["permissions"] == {"contents": "read"} assert document["jobs"]["publish-wiki"]["permissions"] == {"contents": "read"}
def test_the_inputs_reach_the_script_through_the_environment(self, document): def test_the_settings_reach_the_script_through_the_environment(self, document):
step = document["jobs"]["publish-wiki"]["steps"][-1] step = document["jobs"]["publish-wiki"]["steps"][-1]
assert step["env"]["WIKI_DIR"] == "${{ inputs.wiki_dir }}" assert step["env"]["WIKI_DIR"] == "docs/wiki"
assert step["env"]["WIKI_PRUNE"] == "${{ inputs.prune }}" assert step["env"]["WIKI_PRUNE"] == "false"
assert step["env"]["WIKI_CREDENTIALS"] == "${{ secrets.TOKEN_FOR_GITEA_WIKI }}"
assert step["run"] == "python3 shared-scripts/tools/publish_wiki.py" assert step["run"] == "python3 shared-scripts/tools/publish_wiki.py"
assert "inputs." not in step["run"] assert "inputs." not in step["run"]
def test_the_script_is_fetched_at_the_tools_ref(self, document): def test_the_script_is_fetched_at_v2(self, steps):
fetch = document["jobs"]["publish-wiki"]["steps"][1]["with"] fetch = steps["Fetch the shared script"]["with"]
assert fetch["repository"] == "TirSystem/github-action" assert fetch["repository"] == "TirSystem/github-action"
assert fetch["ref"] == "${{ inputs.tools-ref }}" assert fetch["ref"] == "v2"
def test_the_folder_check_decides_whether_the_fetch_and_publish_steps_run(self, steps):
assert steps["source"]["name"] == "Look for the wiki folder"
assert "-d docs/wiki" in steps["source"]["run"]
condition = "steps.source.outputs.found == 'true'"
assert steps["Fetch the shared script"]["if"] == condition
assert steps["Publish the pages to the wiki"]["if"] == condition
def test_the_scoped_workflow_is_gone_and_the_script_has_no_marker_path(): def test_this_repository_publishes_docs_wiki_through_the_scoped_workflow():
"""ADR-0009, MIL-009: the scoped publish-wiki.yml and the marker are removed.""" """The wiki of this repository equals docs/wiki/ (ADR-0009): the folder is the opt-in."""
assert not (REPO_ROOT / ".gitea" / "scoped_workflows" / "publish-wiki.yml").exists() assert SCOPED_WORKFLOW.is_file()
assert not (REPO_ROOT / ".gitea" / "workflows" / "publish-own-wiki.yml").exists()
assert not (REPO_ROOT / ".gitea" / "workflows" / "publish-wiki-pages.yml").exists()
assert not (REPO_ROOT / "wiki").exists()
assert (REPO_ROOT / "docs" / "wiki" / "Home.md").is_file()
def test_the_script_has_no_marker_path():
"""ADR-0009: the marker file is removed."""
source = (REPO_ROOT / "tools" / "publish_wiki.py").read_text(encoding="utf-8") source = (REPO_ROOT / "tools" / "publish_wiki.py").read_text(encoding="utf-8")
assert "MARKER_NAME" not in source assert "MARKER_NAME" not in source
assert "parse_marker" not in source assert "parse_marker" not in source
def test_this_repository_publishes_docs_wiki_through_the_reusable_workflow():
"""The wiki of this repository equals docs/wiki/ (ADR-0009, MIL-008 task 4)."""
assert not (REPO_ROOT / "wiki").exists()
assert (REPO_ROOT / "docs" / "wiki" / "Home.md").is_file()
caller = yaml.safe_load(
(REPO_ROOT / ".gitea" / "workflows" / "publish-own-wiki.yml").read_text(encoding="utf-8")
)
job = caller["jobs"]["wiki"]
assert job["uses"] == "./.gitea/workflows/publish-wiki-pages.yml"
assert job["with"]["wiki_dir"] == "docs/wiki"
assert job["with"]["prune"] == "true"
assert caller[True]["push"]["paths"] == ["docs/wiki/**"]
tools/publish_wiki.py
+5 -4
View File
@@ -1,8 +1,9 @@
"""Publish the pages of a folder to the Gitea wiki of the repository. """Publish the pages of a folder to the Gitea wiki of the repository.
Run by the reusable workflow publish-wiki-pages.yml, which a repository calls Run by the scoped workflow publish-wiki-pages.yml, which runs in every
(ADR-0009). The caller is the opt-in: the workflow sets WIKI_PRUNE and the repository of the organization. A repository opts in by having the docs/wiki
folder must exist. It reads its settings from the environment: folder; the workflow sets WIKI_PRUNE. It reads its settings from the
environment:
GITEA_API_URL Gitea API base, for example https://host/api/v1 GITEA_API_URL Gitea API base, for example https://host/api/v1
SOURCE_REPOSITORY owner/repo of the repository whose wiki is written SOURCE_REPOSITORY owner/repo of the repository whose wiki is written
@@ -244,7 +245,7 @@ def main():
raise WorkflowError( raise WorkflowError(
"configuration", "configuration",
f"The wiki folder {wiki_dir} does not exist in {owner}/{repo}; " f"The wiki folder {wiki_dir} does not exist in {owner}/{repo}; "
"set the wiki_dir input to the folder with the pages.", "create the folder with the pages, or set WIKI_DIR to it.",
) )
pages = read_pages(wiki_dir) pages = read_pages(wiki_dir)