Skip to content

Commit c0b9861

Browse files
imorlandimorland
authored
Open a docs PR with updated download links after building packages (#2)
* Open a docs PR with updated download links after building packages After the build commits the packages for a version, automatically update the install archive download table in flarum/docs to point at them. - bin/update-docs-table.sh regenerates the "Installing by unpacking an archive" table in a docs install.md from the package files actually built (PHP versions x bundles x formats), rewriting only the table block. Shows the latest built version. - A new `docs-pr` job (needs: build) mints a short-lived token from the flarum-docs-updater GitHub App, checks out flarum/docs, regenerates the table for the built version (2.x -> docs/install.md, older -> versioned_docs), and opens a PR. No auto-merge — left for manual review. Requires the DOCS_APP_ID and DOCS_APP_PRIVATE_KEY secrets. * Check out the running ref in docs-pr, not main The generator script lives on the workflow's branch and the build job commits packages to that same ref, so hardcoding main missed both on branch runs. * Bump workflow actions and tidy generated table spacing - checkout@v4 -> v7 (clears the Node 20 deprecation warning), and the actions added for the docs PR: create-github-app-token@v1 -> v3, create-pull-request@v6 -> v8. - Drop the generator's trailing newline so the regenerated table doesn't leave a double blank line before the next section. * Auto-merge the docs PR flarum/docs `main` is unprotected and deploys on merge, so squash-merge the freshly-opened install-links PR straight away using the App token. Only merges when a PR was actually created or updated.
1 parent dbe257f commit c0b9861

2 files changed

Lines changed: 186 additions & 1 deletion

File tree

‎.github/workflows/build.yml‎

Lines changed: 87 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ jobs:
4040
name: Build Flarum ${{ inputs.flarum_version }} - ${{ matrix.bundle.name }} Bundle - PHP ${{ inputs.php_versions }}
4141

4242
steps:
43-
- uses: actions/checkout@v4
43+
- uses: actions/checkout@v7
4444

4545
- name: Setup PHP
4646
uses: shivammathur/setup-php@v2
@@ -57,3 +57,89 @@ jobs:
5757
PHP_VERSIONS: ${{ inputs.php_versions }}
5858
BUNDLE_NAME: ${{ matrix.bundle.name }}
5959
BUNDLE_VALUE: ${{ matrix.bundle.value }}
60+
61+
# After all packages for this version are built and committed, open a PR to
62+
# flarum/docs updating the install.md download table to point at them.
63+
docs-pr:
64+
needs: build
65+
runs-on: ubuntu-latest
66+
67+
steps:
68+
- name: Check out installation-packages (for the built files + generator)
69+
uses: actions/checkout@v7
70+
with:
71+
# Check out the ref the workflow ran on: the `build` job committed the
72+
# freshly-built packages to it, and it carries the generator script.
73+
ref: ${{ github.ref }}
74+
75+
- name: Derive version paths
76+
id: vars
77+
run: |
78+
FULL="v${FLARUM_VERSION#v}"
79+
MAJOR="${FULL#v}"; MAJOR="${MAJOR%%.*}.x"
80+
echo "full=$FULL" >> "$GITHUB_OUTPUT"
81+
echo "major=$MAJOR" >> "$GITHUB_OUTPUT"
82+
echo "packages_dir=packages/v$MAJOR/$FULL" >> "$GITHUB_OUTPUT"
83+
# 2.x is the current (unversioned) docs; older majors are versioned.
84+
if [ "$MAJOR" = "2.x" ]; then
85+
echo "install_md=docs/install.md" >> "$GITHUB_OUTPUT"
86+
else
87+
echo "install_md=versioned_docs/version-$MAJOR/install.md" >> "$GITHUB_OUTPUT"
88+
fi
89+
env:
90+
FLARUM_VERSION: ${{ inputs.flarum_version }}
91+
92+
# Mint a short-lived token from the flarum GitHub App so we can open a PR
93+
# in the separate flarum/docs repo. Requires the DOCS_APP_ID and
94+
# DOCS_APP_PRIVATE_KEY secrets (App scoped to flarum/docs +
95+
# installation-packages with Contents + Pull requests write).
96+
- name: Generate docs App token
97+
id: docs-token
98+
uses: actions/create-github-app-token@v3
99+
with:
100+
app-id: ${{ secrets.DOCS_APP_ID }}
101+
private-key: ${{ secrets.DOCS_APP_PRIVATE_KEY }}
102+
owner: flarum
103+
repositories: docs
104+
105+
- name: Check out flarum/docs
106+
uses: actions/checkout@v7
107+
with:
108+
repository: flarum/docs
109+
token: ${{ steps.docs-token.outputs.token }}
110+
path: docs-repo
111+
112+
- name: Regenerate the download table
113+
run: |
114+
FLARUM_VERSION='${{ inputs.flarum_version }}' \
115+
PACKAGES_DIR='${{ steps.vars.outputs.packages_dir }}' \
116+
INSTALL_MD='docs-repo/${{ steps.vars.outputs.install_md }}' \
117+
bin/update-docs-table.sh
118+
119+
- name: Open PR to flarum/docs
120+
id: docs-pr
121+
uses: peter-evans/create-pull-request@v8
122+
with:
123+
token: ${{ steps.docs-token.outputs.token }}
124+
path: docs-repo
125+
branch: update-install-links-${{ steps.vars.outputs.full }}
126+
base: main
127+
commit-message: "Update ${{ steps.vars.outputs.major }} install download links for ${{ steps.vars.outputs.full }}"
128+
title: "Update ${{ steps.vars.outputs.major }} install download links for ${{ steps.vars.outputs.full }}"
129+
body: |
130+
Updates the install archive download table for **${{ steps.vars.outputs.major }}** to point at the newly built packages for `${{ steps.vars.outputs.full }}`.
131+
132+
Generated automatically by the `flarum/installation-packages` build workflow.
133+
delete-branch: true
134+
135+
# flarum/docs `main` is unprotected and deploys on merge, so merge the
136+
# freshly-opened PR straight away. Only runs when a PR was actually
137+
# created or updated (skips when the table was already up to date).
138+
- name: Merge the docs PR
139+
if: steps.docs-pr.outputs.pull-request-operation == 'created' || steps.docs-pr.outputs.pull-request-operation == 'updated'
140+
env:
141+
GH_TOKEN: ${{ steps.docs-token.outputs.token }}
142+
run: |
143+
gh pr merge "${{ steps.docs-pr.outputs.pull-request-number }}" \
144+
--repo flarum/docs \
145+
--squash --delete-branch

‎bin/update-docs-table.sh‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
#!/bin/bash -l
2+
3+
# Regenerates the "Installing by unpacking an archive" download table in a
4+
# Flarum docs `install.md` so it points at the freshly-built packages for a
5+
# given version.
6+
#
7+
# The table is rebuilt from the package files that actually exist on disk, so
8+
# it always matches what was produced (PHP versions x bundles x formats). Only
9+
# the markdown table block is rewritten; the rest of the file is untouched.
10+
#
11+
# Usage:
12+
# FLARUM_VERSION=v2.0.0-rc.5 \
13+
# PACKAGES_DIR=packages/v2.x/v2.0.0-rc.5 \
14+
# INSTALL_MD=/path/to/docs/install.md \
15+
# bin/update-docs-table.sh
16+
#
17+
# The version label shown in the first column is the major line (e.g. 2.x).
18+
19+
set -euo pipefail
20+
21+
: "${FLARUM_VERSION:?FLARUM_VERSION is required (e.g. v2.0.0-rc.5)}"
22+
: "${PACKAGES_DIR:?PACKAGES_DIR is required (dir containing the built packages)}"
23+
: "${INSTALL_MD:?INSTALL_MD is required (path to the docs install.md)}"
24+
25+
# Normalise: ensure a single leading 'v'.
26+
full_version="v${FLARUM_VERSION#v}"
27+
28+
# Major line for the first column and the raw URL path, e.g. "2.x".
29+
version_no_v="${full_version#v}"
30+
IFS='.' read -ra parts <<< "$version_no_v"
31+
major_line="${parts[0]}.x"
32+
33+
repo_raw="https://github.com/flarum/installation-packages/raw/main"
34+
35+
# Build the table rows from the files present in PACKAGES_DIR.
36+
# File format: flarum-<full_version>[-no-public-dir]-php<X>.<zip|tar.gz>
37+
rows=""
38+
# Sort for deterministic output.
39+
for file in $(ls "$PACKAGES_DIR" | sort); do
40+
# Only consider our package archives.
41+
case "$file" in
42+
flarum-*.zip|flarum-*.tar.gz) ;;
43+
*) continue ;;
44+
esac
45+
46+
# PHP version: the digits after "-php" up to the extension.
47+
php=$(echo "$file" | sed -E 's/.*-php([0-9]+\.[0-9]+)\.(zip|tar\.gz)$/\1/')
48+
49+
# Public path: "No" when the no-public-dir bundle, "Yes" otherwise.
50+
if [[ "$file" == *"-no-public-dir-"* ]]; then
51+
public="No"
52+
else
53+
public="Yes"
54+
fi
55+
56+
# Type from the extension.
57+
case "$file" in
58+
*.zip) type="ZIP" ;;
59+
*.tar.gz) type="TAR.GZ" ;;
60+
esac
61+
62+
url="$repo_raw/$PACKAGES_DIR/$file"
63+
rows+="| $major_line | $php | $public | $type | [$file]($url) |"$'\n'
64+
done
65+
66+
if [ -z "$rows" ]; then
67+
echo "No package files found in $PACKAGES_DIR" >&2
68+
exit 1
69+
fi
70+
71+
# Drop the trailing newline so the generated block doesn't leave a blank line
72+
# before the following section.
73+
rows=${rows%$'\n'}
74+
75+
header="| Flarum Version | PHP Version | Public Path | Type | Archive |"
76+
divider="|----------------|-------------|-------------|--------|---------|"
77+
78+
# Replace the existing table (header row + divider + all following table rows)
79+
# with the freshly generated one, using awk so surrounding prose is preserved.
80+
tmp=$(mktemp)
81+
TABLE="$header"$'\n'"$divider"$'\n'"$rows" awk '
82+
# Detect the start of the archive table by its header row.
83+
/^\| Flarum Version \| PHP Version \|/ && !done {
84+
print ENVIRON["TABLE"]
85+
intable = 1
86+
done = 1
87+
next
88+
}
89+
# While inside the old table, skip its rows (lines starting with "|").
90+
intable {
91+
if ($0 ~ /^\|/) next
92+
intable = 0
93+
}
94+
{ print }
95+
' "$INSTALL_MD" > "$tmp"
96+
97+
mv "$tmp" "$INSTALL_MD"
98+
99+
echo "Updated $INSTALL_MD table for $major_line ($full_version)"

0 commit comments

Comments
 (0)