Skip to content

Commit dc02ec5

Browse files
yeoldegroveyeoldegrove
committed
ci: add reusable docs CI orchestrator for aggregated repositories
Centralize the documentation CI so aggregated repositories only need a thin caller workflow. The new reusable workflow aggregated-repo-docs.yml runs detect-changes, docs-checks, the gate, and the notify dispatch, and notifies docs only when a PR actually touched documentation-relevant paths (no docs preview PR for unrelated merges). Documentation-relevant paths are derived from repos-config.json (docs_path + root_files) with an optional docs_paths override, so the path definitions live in a single place instead of in every repository. - add .github/workflows/aggregated-repo-docs.yml (paths-filter based) - add RepoConfig.docs_paths and resolved_docs_paths, persist on save - add unit tests for docs_paths round-trip and derivation Signed-off-by: Eike Waldt <waldt@b1-systems.de> On-behalf-of: SAP <eike.waldt@sap.com> Assisted-by: Kilo:claude-sonnet-4-6
1 parent 59b5762 commit dc02ec5

9 files changed

Lines changed: 546 additions & 111 deletions

File tree

‎.github/workflows/aggregated-repo-docs.yml‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
name: Aggregated Repository Documentation CI
2+
3+
# Reusable orchestrator for documentation CI in aggregated repositories.
4+
#
5+
# Aggregated repositories call this workflow from a thin `.github/workflows/
6+
# docs-check.yml` caller. All documentation-path logic and the notify/commit-lock
7+
# decision live here, using `repos-config.json` in this repository as the single
8+
# source of truth for "what counts as documentation".
9+
#
10+
# The documentation-relevant paths per repository are derived from
11+
# `docs_path` + `root_files` (or an explicit `docs_paths` override) and written
12+
# to a `dorny/paths-filter` configuration at runtime.
13+
14+
on:
15+
workflow_call:
16+
inputs:
17+
repo:
18+
description: 'Repository name as it appears in repos-config.json (e.g. gardenlinux)'
19+
required: true
20+
type: string
21+
secrets:
22+
DOCS_BOT_APP_ID:
23+
required: true
24+
DOCS_BOT_PRIVATE_KEY:
25+
required: true
26+
27+
permissions:
28+
contents: read
29+
30+
jobs:
31+
detect-changes:
32+
name: Detect docs path changes
33+
runs-on: ubuntu-24.04
34+
permissions:
35+
contents: read
36+
pull-requests: read
37+
outputs:
38+
docs: ${{ steps.filter.outputs.docs }}
39+
steps:
40+
# paths-filter detects changes in pull requests via the REST API, but for
41+
# push events it uses git and needs the source repository checked out.
42+
- name: Checkout source repository
43+
if: github.event_name != 'pull_request'
44+
uses: actions/checkout@v4
45+
46+
- name: Checkout docs registry
47+
uses: actions/checkout@v4
48+
with:
49+
repository: gardenlinux/docs
50+
path: .docs
51+
52+
- name: Generate docs path filter from registry
53+
env:
54+
REPO: ${{ inputs.repo }}
55+
run: |
56+
python3 - <<'PY'
57+
import json
58+
import os
59+
60+
repo = os.environ["REPO"]
61+
with open(".docs/repos-config.json", encoding="utf-8") as handle:
62+
config = json.load(handle)
63+
64+
entry = next((r for r in config["repos"] if r["name"] == repo), None)
65+
if entry is None:
66+
raise SystemExit(f"Repository '{repo}' not found in repos-config.json")
67+
68+
patterns = entry.get("docs_paths") or [
69+
f"{entry['docs_path']}/**",
70+
*entry.get("root_files", []),
71+
]
72+
print(f"Docs path patterns for {repo}: {patterns}")
73+
74+
with open(".docs-filter.yml", "w", encoding="utf-8") as handle:
75+
handle.write("docs:\n")
76+
for pattern in patterns:
77+
handle.write(f" - '{pattern}'\n")
78+
PY
79+
80+
- name: Check for docs path changes
81+
id: filter
82+
uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
83+
with:
84+
filters: .docs-filter.yml
85+
86+
docs-checks:
87+
name: Docs checks
88+
needs: [detect-changes]
89+
if: needs.detect-changes.outputs.docs == 'true' && (github.event_name != 'pull_request' || github.event.action != 'closed')
90+
permissions:
91+
contents: read
92+
pull-requests: read
93+
uses: gardenlinux/docs/.github/workflows/docs-checks.yml@main
94+
with:
95+
override-repo: ${{ inputs.repo }}
96+
override-ref: ${{ github.head_ref || github.ref_name }}
97+
override-commit: ${{ github.event.pull_request.head.sha || github.sha }}
98+
99+
docs-checks-gate:
100+
name: Docs checks gate
101+
needs: [detect-changes, docs-checks]
102+
if: always() && (github.event_name != 'pull_request' || github.event.action != 'closed')
103+
runs-on: ubuntu-24.04
104+
steps:
105+
- name: Evaluate docs checks result
106+
run: |
107+
DOCS_CHANGED="${{ needs.detect-changes.outputs.docs }}"
108+
DOCS_RESULT="${{ needs.docs-checks.result }}"
109+
if [[ "$DOCS_CHANGED" != "true" ]]; then
110+
echo "Docs paths not changed; skipping docs checks — gate passes."
111+
exit 0
112+
fi
113+
if [[ "$DOCS_RESULT" == "success" ]]; then
114+
echo "Docs checks passed."
115+
exit 0
116+
fi
117+
echo "Docs checks result: $DOCS_RESULT"
118+
exit 1
119+
120+
notify-docs:
121+
name: Notify docs
122+
needs: [detect-changes, docs-checks]
123+
runs-on: ubuntu-24.04
124+
# Only notify for PR events and only when the PR actually touched docs.
125+
# Run after checks pass for open PRs, OR immediately for merged PRs.
126+
if: |
127+
always() &&
128+
github.event_name == 'pull_request' &&
129+
needs.detect-changes.outputs.docs == 'true' &&
130+
(
131+
(github.event.action == 'closed' && github.event.pull_request.merged == true) ||
132+
(github.event.action != 'closed' && needs.docs-checks.result == 'success')
133+
)
134+
steps:
135+
- name: Generate GitHub App token
136+
id: app-token
137+
uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
138+
with:
139+
app-id: ${{ secrets.DOCS_BOT_APP_ID }}
140+
private-key: ${{ secrets.DOCS_BOT_PRIVATE_KEY }}
141+
repositories: docs
142+
143+
- name: Send repository dispatch to docs
144+
uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
145+
with:
146+
github-token: ${{ steps.app-token.outputs.token }}
147+
script: |
148+
const isMergedPR = context.payload.action === 'closed' &&
149+
context.payload.pull_request.merged === true;
150+
151+
// For merged PRs, use the base branch (the branch it was merged into)
152+
// For open PRs, use the head branch (feature branch)
153+
const ref = isMergedPR
154+
? context.payload.pull_request.base.ref
155+
: context.payload.pull_request.head.ref;
156+
157+
await github.rest.repos.createDispatchEvent({
158+
owner: 'gardenlinux',
159+
repo: 'docs',
160+
event_type: 'docs-pr',
161+
client_payload: {
162+
repo: '${{ inputs.repo }}',
163+
pr_number: `${context.payload.pull_request.number}`,
164+
commit_sha: isMergedPR
165+
? context.payload.pull_request.merge_commit_sha
166+
: context.payload.pull_request.head.sha,
167+
ref: ref,
168+
event: isMergedPR ? 'merged' : 'pr_success'
169+
}
170+
});
171+
core.info('Repository dispatch sent to docs');

‎docs/contributing/documentation/adding-repos.md‎

Lines changed: 38 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,14 +44,21 @@ Edit `repos-config.json` and add a new entry to the `repos` array:
4444

4545
- **`name`**: Unique identifier for the repository
4646
- **`url`**: Git URL or `file://` path for local development
47-
- **`docs_path`**: Path to docs directory within the repository
47+
- **`docs_path`**: Path to docs directory within the repository. Set explicitly
48+
for every repository in `repos-config.json` (defaults to `"docs"` if omitted,
49+
but do not rely on the default)
4850
- **`ref`**: Git branch or tag to fetch from
4951

5052
### Optional Fields
5153

5254
- **`commit`**: Lock to a specific commit hash for reproducibility
5355
- **`root_files`**: List of root-level files to copy (e.g.,
5456
`["README.md", "CONTRIBUTING.md"]`)
57+
- **`docs_paths`**: Explicit override for the documentation-relevant glob
58+
patterns used by the documentation CI to detect documentation changes. By
59+
default this is derived as `["<docs_path>/**", ...root_files]`; only set it
60+
when a repository's documentation paths differ from that default (e.g.
61+
`daily`)
5562
- **`structure`**: Directory mapping strategy (`"flat"` or `"sphinx"`; see below)
5663
- **`media_directories`**: List of media directories to copy (e.g.,
5764
`[".media", "_static", "assets"]`)
@@ -146,6 +153,36 @@ Or manually add the commit hash:
146153
}
147154
```
148155

156+
## Step 6: Install the Documentation CI Caller Workflow
157+
158+
Add a thin caller workflow at `.github/workflows/docs-check.yml` in the
159+
repository. It delegates all documentation CI (change detection, quality checks,
160+
the merge gate, and the notify/commit-lock dispatch) to the reusable
161+
orchestrator in `gardenlinux/docs`:
162+
163+
```yaml
164+
name: Documentation Quality Check
165+
166+
on:
167+
pull_request:
168+
branches: [main]
169+
types: [opened, synchronize, reopened, closed]
170+
push:
171+
branches: [main]
172+
173+
jobs:
174+
docs:
175+
uses: gardenlinux/docs/.github/workflows/aggregated-repo-docs.yml@main
176+
with:
177+
repo: new-repo
178+
secrets: inherit
179+
```
180+
181+
Replace `new-repo` with the repository's `name` from `repos-config.json` and
182+
adjust the branch to the repository's default branch. See
183+
[CI Workflows Reference](./ci-workflows-reference.md) for details and required
184+
secrets.
185+
149186
## Advanced Configuration
150187

151188
### Media Directories
@@ -196,7 +233,6 @@ Here's a complete configuration:
196233
"media_directories": [".media", "images"]
197234
}
198235
```
199-
200236
The `docs_path` field defaults to `"docs"` and may be omitted when the documentation lives in a `docs/` directory.
201237

202238
## Troubleshooting

0 commit comments

Comments
 (0)