Repository navigation
236 lines (214 loc) · 12.4 KB
/
Copy pathobject-reference-sync.yml
File metadata and controls
236 lines (214 loc) · 12.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
name: Sync API docs to iron-websites
# When new API docs reach `main` (usually the merged nightly PR), copy them into the website
# repo and open ONE pull request there, into `develop`. Nothing merges by itself.
#
# What runs (both scripts live in iron-websites, not here):
# 1. `manage:products:sync -- --apply --sync-changelog` sets each product's site version to the
# newest release on its package registry, and adds that release to the product's English
# changelog page if the page does not list it yet.
# 2. `manage:docs:sync -- --match-site --no-generate` copies the API docs for that version from
# THIS commit into the site and splices in the site's header.
#
# The PR always comes from the `sync/object-reference` branch, rebuilt from `develop` and
# force-pushed on every run, so an open PR is refreshed rather than duplicated — and anything
# pushed to that branch by hand is lost on the next run. No change: no push, and an open sync PR
# is closed as out of date.
#
# The run turns red, after the PR is opened, when a product's site version has no matching docs
# in this repo: the PR then moves the version ahead of its docs, and its body says so.
#
# Needs the secret IRON_WEBSITES_PR_TOKEN: a fine-grained token on iron-software/iron-websites
# with Contents and Pull requests read/write. The job's own GITHUB_TOKEN cannot write to
# another repository.
#
# The "Run workflow" button only works from the default branch (`main`); to test a copy of
# this file on another branch, use `gh workflow run object-reference-sync.yml --ref <branch>`.
on:
push:
branches: [main]
paths: ["object-reference/**"]
workflow_dispatch:
inputs:
dry_run:
description: "Run both syncs and show the diff. Pushes nothing, opens no PR."
type: boolean
default: false
# Dry runs get their own group: GitHub keeps one waiting run per group, so a dry run in the
# shared group could cancel a real run that is queued behind the current one.
concurrency:
group: object-reference-sync${{ inputs.dry_run && '-dry-run' || '' }}
cancel-in-progress: false
env:
WEBSITE_REPO: iron-software/iron-websites
BASE: develop
BRANCH: sync/object-reference
jobs:
sync:
runs-on: ubuntu-latest
timeout-minutes: 60
# GITHUB_TOKEN only reads this repository. Every write to iron-websites uses the PAT.
permissions:
contents: read
steps:
- name: Check the secret this job needs
env:
PR_TOKEN: ${{ secrets.IRON_WEBSITES_PR_TOKEN }}
run: |
if [ -z "$PR_TOKEN" ]; then
echo "::error title=Sync API docs::Missing repository secret IRON_WEBSITES_PR_TOKEN. Set it under Settings > Secrets and variables > Actions (needs a repository admin). Nothing was synced."
exit 1
fi
# The commit that triggered the run. The docs sync copies a version only when the site does
# not already have it: a tree already at its recorded version is skipped, so docs rebuilt in
# place under an existing version do not reach the site.
# LFS stays off: nothing under `object-reference/` is LFS-tracked here; only the generator
# toolchain under `scaffolds/` is.
- name: Check out the API docs (this commit)
uses: actions/checkout@v4
with:
ref: ${{ github.sha }}
path: github-io
lfs: false
persist-credentials: false
# persist-credentials: false, or the checkout login stays in git config and is sent on
# the push below instead of the PAT (iron-websites' helpcenter sync failed on a 403 this way).
# lfs: false so the website's LFS files are not downloaded on every run (LFS bandwidth is
# billed). They stay as pointers, which the sync leaves alone.
- name: Check out iron-websites (develop)
uses: actions/checkout@v4
with:
repository: ${{ env.WEBSITE_REPO }}
ref: ${{ env.BASE }}
path: iron-websites
token: ${{ secrets.IRON_WEBSITES_PR_TOKEN }}
lfs: false
persist-credentials: false
# iron-websites tracks *.jar and *.zip with LFS, and the Java API docs include some (the
# javadoc jar and the search-index zips). A Java version bump replaces them, so `git add`
# must store them as LFS pointers, and the push must upload the files to LFS.
# --skip-smudge keeps the existing pointers from being downloaded.
- name: Store the website's LFS files as pointers
working-directory: iron-websites
run: git lfs install --local --skip-smudge
- uses: actions/setup-node@v4
with:
node-version: "24.18.0"
cache: npm
cache-dependency-path: iron-websites/package-lock.json
- name: Install the website's dependencies
working-directory: iron-websites
run: npm ci --no-audit --no-fund
# A registry that does not answer makes this step fail, but the docs sync still runs; the
# run turns red in the last step.
#
# Keep `--sync-changelog`: without it the site shows the new version while the changelog
# page still ends at the previous release. Release notes come from NuGet; products on
# other registries get a "Release notes pending" line instead. The PR body lists those
# pages, so the notes can be added in a separate PR (pushing to this PR's branch is lost).
- name: Update product versions and changelogs from the package registries
id: products
continue-on-error: true
working-directory: iron-websites
run: npm run manage:products:sync -- --apply --sync-changelog
# `--no-generate`: this runner has no DocFX toolchain. A product whose site version has no
# docs here is listed under "⚠ no source version" and its tree is left as it was. Those with
# "no archive version" or "no archive dir" are collected for the PR body and the last step.
# "no site-declared version" is not: it means the site does not publish that product's docs.
- name: Copy the API docs into the site
working-directory: iron-websites
run: |
set -o pipefail
npm run manage:docs:sync -- --source "$GITHUB_WORKSPACE/github-io" --match-site --no-generate \
| tee "$RUNNER_TEMP/docs-sync.log"
awk '/^⚠ no source version/ { inblock = 1; next }
inblock && /^ - / { if ($0 ~ /: no archive (version under|dir)/) print; next }
{ inblock = 0 }' "$RUNNER_TEMP/docs-sync.log" > "$RUNNER_TEMP/missing-docs.txt"
if [ -s "$RUNNER_TEMP/missing-docs.txt" ]; then
{
echo "**No docs in this repo for the site's version of:**"
sed 's/^ //' "$RUNNER_TEMP/missing-docs.txt"
} | tee -a "$GITHUB_STEP_SUMMARY"
fi
- name: Commit, and open, refresh or close the PR
working-directory: iron-websites
env:
GH_TOKEN: ${{ secrets.IRON_WEBSITES_PR_TOKEN }}
DRY_RUN: ${{ inputs.dry_run }}
SOURCE_URL: ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}
run: |
open_pr=$(gh pr list --repo "$WEBSITE_REPO" --head "$BRANCH" --base "$BASE" --state open --json number --jq '.[0].number // empty')
git add -A -- src
# Some *.zip / *.jar files are committed as ordinary files, not LFS pointers. With the LFS
# filter installed, `git add` stages them as pointers even when the sync never touched
# them. Unstage every file whose bytes on disk are still what `develop` has.
git diff --cached --name-only -z --diff-filter=M | while IFS= read -r -d '' f; do
if [ "$(git hash-object --no-filters -- "$f")" = "$(git rev-parse "HEAD:$f")" ]; then
git restore --staged -- "$f"
fi
done
# Changelog pages this sync added an entry to, and those whose new entry has no release
# notes yet (the script writes "Release notes pending" when the registry has none).
git diff --cached --name-only -- ':(glob)src/content/markdown/products/en/**/changelog.md' \
> "$RUNNER_TEMP/changelogs.txt"
: > "$RUNNER_TEMP/changelogs-pending.txt"
while IFS= read -r f; do
if git diff --cached -U0 -- "$f" | grep -q '^+.*Release notes pending'; then
echo "$f" >> "$RUNNER_TEMP/changelogs-pending.txt"
fi
done < "$RUNNER_TEMP/changelogs.txt"
if git diff --cached --quiet; then
echo "No change to the website. Nothing pushed." | tee -a "$GITHUB_STEP_SUMMARY"
# An open sync PR now holds changes `develop` already has, or no longer wants.
if [ -n "$open_pr" ] && [ "$DRY_RUN" != "true" ]; then
gh pr close "$open_pr" --repo "$WEBSITE_REPO" \
--comment "Closed by the sync workflow: ${SOURCE_URL} found nothing to change on \`develop\`, so this PR is out of date."
echo "Closed out-of-date PR #$open_pr." | tee -a "$GITHUB_STEP_SUMMARY"
fi
exit 0
fi
git diff --cached --stat | tail -n 1 | tee -a "$GITHUB_STEP_SUMMARY"
if [ "$DRY_RUN" = "true" ]; then
git diff --cached --stat | head -n 50
echo "Dry run: nothing pushed." | tee -a "$GITHUB_STEP_SUMMARY"
exit 0
fi
git config user.name "iron-apidocs-bot"
git config user.email "docs-bot@ironsoftware.com"
git commit -q -m "Sync API docs from iron-software.github.io ${GITHUB_SHA::10}"
# Rebuilt from develop each run, so the force-push replaces the previous sync.
git push --force "https://x-access-token:${GH_TOKEN}@github.com/${WEBSITE_REPO}.git" "HEAD:refs/heads/${BRANCH}"
{
printf '%s\n\n' "***New API docs from iron-software.github.io, plus the product versions to match.***"
printf '%s\n\n' "This PR copies the API reference pages for each new version from ${SOURCE_URL} into the site, updates each product's version to its newest release, and adds that release to the product's English changelog page. Pages rebuilt under a version the site already has are not copied. Opened by a workflow; review and merge by hand."
if [ -s "$RUNNER_TEMP/missing-docs.txt" ]; then
printf '%s\n\n' "**Warning: this PR moves these products to a version with no API docs yet.** Their API reference stays on the old version until the docs reach iron-software.github.io, and the API reference link in their new changelog entry returns 404 until then:"
sed 's/^ //' "$RUNNER_TEMP/missing-docs.txt"
printf '\n'
fi
if [ -s "$RUNNER_TEMP/changelogs-pending.txt" ]; then
printf '%s\n\n' "**These changelog entries say \"Release notes pending\".** Their registry publishes no release notes. Copy the notes from the release post in #product-engineering-releases, in a separate PR after this one merges:"
sed 's/^/- /' "$RUNNER_TEMP/changelogs-pending.txt"
printf '\n'
fi
printf '%s\n\n' "Do not push fixes to \`${BRANCH}\`: the next run rebuilds it from \`${BASE}\` and force-pushes, which discards them. Fix things in a separate PR."
printf '%s\n' "Check: open one changed \`object-reference\` page on staging, the product page whose version changed, and its changelog page."
} > pr-body.md
if [ -n "$open_pr" ]; then
gh pr edit "$open_pr" --repo "$WEBSITE_REPO" --body-file pr-body.md
echo "Refreshed PR #$open_pr." | tee -a "$GITHUB_STEP_SUMMARY"
else
gh pr create --repo "$WEBSITE_REPO" --base "$BASE" --head "$BRANCH" \
--title "[WEB-DEV] Sync the API docs from iron-software.github.io" --body-file pr-body.md
fi
# After the PR step, so the docs that did sync are still offered for review.
- name: Fail the run if a product's version has no docs
run: |
if [ -s "$RUNNER_TEMP/missing-docs.txt" ]; then
echo "::error title=Sync API docs::A product's site version has no API docs in this repo. Its docs were left on the old version; see the run summary."
exit 1
fi
- name: Fail the run if the product version update failed
if: ${{ !cancelled() && steps.products.outcome == 'failure' }}
run: |
echo "::error title=Sync API docs::manage:products:sync failed (registry error or bad arguments). The docs were still synced; see that step's log."
exit 1