Skip to content

Commit 62e0c67

Browse files
ben-fornefeldben-fornefeld
authored
Feature: Add SDK Reference Cron Job (#154)
* feature: add sdk reference cron * Apply suggestion from @ben-fornefeld * docs: address sdk reference sync workflow feedback
1 parent 7c299e9 commit 62e0c67

5 files changed

Lines changed: 250 additions & 39 deletions

File tree

‎.github/workflows/sdk-reference-generator-test.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,11 @@ on:
44
pull_request:
55
paths:
66
- "sdk-reference-generator/**"
7+
- ".github/workflows/sdk-reference-sync.yml"
8+
- ".github/workflows/sdk-reference-generator-test.yml"
9+
- "requirements.txt"
10+
- "docs.json"
11+
- "docs/sdk-reference/**"
712

813
jobs:
914
test:

‎.github/workflows/sdk-reference-sync.yml‎

Lines changed: 52 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ on:
2626

2727
repository_dispatch:
2828
types: [sdk-release]
29+
schedule:
30+
- cron: "*/15 * * * *"
2931

3032
# prevent concurrent runs that could conflict
3133
concurrency:
@@ -38,6 +40,7 @@ jobs:
3840
timeout-minutes: 30
3941
permissions:
4042
contents: write
43+
pull-requests: write
4144

4245
steps:
4346
- name: Checkout docs repo
@@ -78,7 +81,7 @@ jobs:
7881
- name: Install Python dependencies
7982
run: pip install -r requirements.txt
8083

81-
- name: Determine SDK and Version
84+
- name: Resolve generation inputs from trigger
8285
id: params
8386
env:
8487
EVENT_NAME: ${{ github.event_name }}
@@ -89,23 +92,7 @@ jobs:
8992
PAYLOAD_SDK: ${{ github.event.client_payload.sdk }}
9093
PAYLOAD_VERSION: ${{ github.event.client_payload.version }}
9194
PAYLOAD_LIMIT: ${{ github.event.client_payload.limit }}
92-
run: |
93-
if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
94-
SDK="$INPUT_SDK"
95-
VERSION="$INPUT_VERSION"
96-
LIMIT="$INPUT_LIMIT"
97-
FORCE="$INPUT_FORCE"
98-
elif [[ "$EVENT_NAME" == "repository_dispatch" ]]; then
99-
SDK="$PAYLOAD_SDK"
100-
VERSION="${PAYLOAD_VERSION:-latest}"
101-
LIMIT="${PAYLOAD_LIMIT:-5}"
102-
FORCE="false"
103-
fi
104-
105-
echo "sdk=${SDK:-all}" >> $GITHUB_OUTPUT
106-
echo "version=${VERSION:-latest}" >> $GITHUB_OUTPUT
107-
echo "limit=${LIMIT:-5}" >> $GITHUB_OUTPUT
108-
echo "force=${FORCE:-false}" >> $GITHUB_OUTPUT
95+
run: bash scripts/resolve-sdk-reference-sync-params.sh
10996

11097
- name: Generate SDK Reference
11198
working-directory: sdk-reference-generator
@@ -128,47 +115,75 @@ jobs:
128115
129116
pnpm run generate $ARGS
130117
131-
- name: Commit and push changes
132-
id: commit
133-
env:
134-
SDK_NAME: ${{ steps.params.outputs.sdk }}
135-
SDK_VERSION: ${{ steps.params.outputs.version }}
118+
- name: Collect change details
119+
id: changes
136120
run: |
137-
git config user.name "github-actions[bot]"
138-
git config user.email "github-actions[bot]@users.noreply.github.com"
139-
140-
git add docs/sdk-reference/
141-
git add docs.json
121+
CHANGED_FILES="$(git status --porcelain -- docs/sdk-reference docs.json | wc -l | tr -d ' ')"
122+
TOTAL_MDX_FILES="$(find docs/sdk-reference -type f -name '*.mdx' | wc -l | tr -d ' ')"
142123
143-
if git diff --staged --quiet; then
144-
echo "No changes to commit"
124+
if [[ "$CHANGED_FILES" == "0" ]]; then
145125
echo "changes=false" >> $GITHUB_OUTPUT
146126
else
147-
git commit -m "docs: update SDK reference for $SDK_NAME $SDK_VERSION"
148-
git push
149127
echo "changes=true" >> $GITHUB_OUTPUT
150128
fi
151129
130+
echo "changed_files=$CHANGED_FILES" >> $GITHUB_OUTPUT
131+
echo "total_mdx_files=$TOTAL_MDX_FILES" >> $GITHUB_OUTPUT
132+
133+
- name: Commit changes and manage pull request
134+
if: steps.changes.outputs.changes == 'true'
135+
id: pr
136+
env:
137+
GH_TOKEN: ${{ github.token }}
138+
BASE_BRANCH: ${{ github.ref_name }}
139+
BRANCH_NAME: automation/sdk-reference-sync
140+
TRIGGER: ${{ steps.params.outputs.trigger }}
141+
SDK_NAME: ${{ steps.params.outputs.sdk }}
142+
SDK_VERSION: ${{ steps.params.outputs.version }}
143+
LIMIT_DISPLAY: ${{ steps.params.outputs.limit_display }}
144+
FORCE: ${{ steps.params.outputs.force }}
145+
CHANGED_FILES: ${{ steps.changes.outputs.changed_files }}
146+
TOTAL_MDX_FILES: ${{ steps.changes.outputs.total_mdx_files }}
147+
WORKFLOW_NAME: ${{ github.workflow }}
148+
REPOSITORY: ${{ github.repository }}
149+
RUN_ID: ${{ github.run_id }}
150+
run: bash scripts/create-sdk-reference-sync-pr.sh
151+
152152
- name: Summary
153153
env:
154+
TRIGGER: ${{ steps.params.outputs.trigger }}
154155
SDK_NAME: ${{ steps.params.outputs.sdk }}
155156
SDK_VERSION: ${{ steps.params.outputs.version }}
156-
LIMIT: ${{ steps.params.outputs.limit }}
157-
CHANGES: ${{ steps.commit.outputs.changes }}
157+
LIMIT: ${{ steps.params.outputs.limit_display }}
158+
FORCE: ${{ steps.params.outputs.force }}
159+
CHANGES: ${{ steps.changes.outputs.changes }}
160+
CHANGED_FILES: ${{ steps.changes.outputs.changed_files }}
161+
TOTAL_MDX_FILES: ${{ steps.changes.outputs.total_mdx_files }}
162+
PR_OPERATION: ${{ steps.pr.outputs.operation }}
163+
PR_URL: ${{ steps.pr.outputs.url }}
158164
run: |
159165
echo "## SDK Reference Generation Complete" >> $GITHUB_STEP_SUMMARY
160166
echo "" >> $GITHUB_STEP_SUMMARY
161167
echo "| Parameter | Value |" >> $GITHUB_STEP_SUMMARY
162168
echo "|-----------|-------|" >> $GITHUB_STEP_SUMMARY
169+
echo "| Trigger | $TRIGGER |" >> $GITHUB_STEP_SUMMARY
163170
echo "| SDK | $SDK_NAME |" >> $GITHUB_STEP_SUMMARY
164171
echo "| Version | $SDK_VERSION |" >> $GITHUB_STEP_SUMMARY
165-
echo "| Limit | ${LIMIT:-No limit} |" >> $GITHUB_STEP_SUMMARY
166-
echo "| Changes committed | $CHANGES |" >> $GITHUB_STEP_SUMMARY
172+
echo "| Limit | $LIMIT |" >> $GITHUB_STEP_SUMMARY
173+
echo "| Force | $FORCE |" >> $GITHUB_STEP_SUMMARY
174+
echo "| Changes detected | $CHANGES |" >> $GITHUB_STEP_SUMMARY
175+
echo "| Changed files | ${CHANGED_FILES:-0} |" >> $GITHUB_STEP_SUMMARY
176+
echo "| PR operation | ${PR_OPERATION:-No PR created} |" >> $GITHUB_STEP_SUMMARY
177+
if [[ -n "$PR_URL" ]]; then
178+
echo "| Pull request | $PR_URL |" >> $GITHUB_STEP_SUMMARY
179+
fi
167180
echo "" >> $GITHUB_STEP_SUMMARY
168181
169182
if [[ "$CHANGES" == "true" ]]; then
170183
echo "### Generated Files" >> $GITHUB_STEP_SUMMARY
171184
echo '```' >> $GITHUB_STEP_SUMMARY
172-
echo "Total MDX files: $(find docs/sdk-reference -type f -name '*.mdx' | wc -l)" >> $GITHUB_STEP_SUMMARY
185+
echo "Total MDX files: $TOTAL_MDX_FILES" >> $GITHUB_STEP_SUMMARY
173186
echo '```' >> $GITHUB_STEP_SUMMARY
187+
else
188+
echo "No SDK reference changes were detected, so no pull request was created." >> $GITHUB_STEP_SUMMARY
174189
fi

‎scripts/create-sdk-reference-sync-pr.sh‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
#!/bin/bash
2+
3+
set -euo pipefail
4+
5+
if [[ -z "${GITHUB_OUTPUT:-}" ]]; then
6+
echo "GITHUB_OUTPUT is required" >&2
7+
exit 1
8+
fi
9+
10+
if [[ -z "${GH_TOKEN:-}" ]]; then
11+
echo "GH_TOKEN is required" >&2
12+
exit 1
13+
fi
14+
15+
base_branch="${BASE_BRANCH:?BASE_BRANCH is required}"
16+
branch_name="${BRANCH_NAME:-automation/sdk-reference-sync}"
17+
sdk_name="${SDK_NAME:-all}"
18+
sdk_version="${SDK_VERSION:-latest}"
19+
trigger="${TRIGGER:-unknown}"
20+
limit_display="${LIMIT_DISPLAY:-5}"
21+
force="${FORCE:-false}"
22+
changed_files="${CHANGED_FILES:-0}"
23+
total_mdx_files="${TOTAL_MDX_FILES:-0}"
24+
workflow_name="${WORKFLOW_NAME:-}"
25+
repository="${REPOSITORY:-}"
26+
run_id="${RUN_ID:-}"
27+
28+
if [[ "$base_branch" == "$branch_name" ]]; then
29+
echo "Base branch and PR branch cannot be the same" >&2
30+
exit 1
31+
fi
32+
33+
git config user.name "github-actions[bot]"
34+
git config user.email "github-actions[bot]@users.noreply.github.com"
35+
36+
git switch -C "$branch_name"
37+
git add docs/sdk-reference docs.json
38+
39+
if git diff --staged --quiet; then
40+
{
41+
echo "operation=none"
42+
echo "url="
43+
} >> "$GITHUB_OUTPUT"
44+
exit 0
45+
fi
46+
47+
title="docs: sync SDK reference for ${sdk_name} ${sdk_version}"
48+
49+
git commit -m "$title"
50+
git push --force-with-lease origin "HEAD:${branch_name}"
51+
52+
body_file="$(mktemp)"
53+
trap 'rm -f "$body_file"' EXIT
54+
55+
cat <<EOF > "$body_file"
56+
## Summary
57+
This automated PR syncs generated SDK reference documentation.
58+
59+
## Trigger
60+
- Source: \`${trigger}\`
61+
- SDK: \`${sdk_name}\`
62+
- Version: \`${sdk_version}\`
63+
- Limit: \`${limit_display}\`
64+
- Force: \`${force}\`
65+
66+
## Changes
67+
- Updates generated reference files under \`docs/sdk-reference/**\`
68+
- Updates \`docs.json\` navigation when generation changes the docs tree
69+
- Changed files detected in this run: \`${changed_files}\`
70+
- Total tracked MDX reference files after generation: \`${total_mdx_files}\`
71+
72+
## Run Details
73+
- Workflow: \`${workflow_name}\`
74+
- Run: https://github.com/${repository}/actions/runs/${run_id}
75+
EOF
76+
77+
pr_info="$(gh pr list \
78+
--repo "$repository" \
79+
--base "$base_branch" \
80+
--head "$branch_name" \
81+
--state open \
82+
--json number,url \
83+
--jq '.[0]? | select(.) | [.number, .url] | @tsv')"
84+
85+
if [[ -n "$pr_info" ]]; then
86+
pr_number="${pr_info%%$'\t'*}"
87+
pr_url="${pr_info#*$'\t'}"
88+
gh pr edit "$pr_number" --repo "$repository" --title "$title" --body-file "$body_file" >/dev/null
89+
operation="updated"
90+
else
91+
pr_url="$(gh pr create \
92+
--repo "$repository" \
93+
--base "$base_branch" \
94+
--head "$branch_name" \
95+
--title "$title" \
96+
--body-file "$body_file")"
97+
operation="created"
98+
fi
99+
100+
{
101+
echo "operation=$operation"
102+
echo "url=$pr_url"
103+
} >> "$GITHUB_OUTPUT"

‎scripts/resolve-sdk-reference-sync-params.sh‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
#!/bin/bash
2+
3+
set -euo pipefail
4+
5+
if [[ -z "${GITHUB_OUTPUT:-}" ]]; then
6+
echo "GITHUB_OUTPUT is required" >&2
7+
exit 1
8+
fi
9+
10+
event_name="${EVENT_NAME:-}"
11+
input_sdk="${INPUT_SDK:-}"
12+
input_version="${INPUT_VERSION:-}"
13+
input_limit="${INPUT_LIMIT:-}"
14+
input_force="${INPUT_FORCE:-}"
15+
payload_sdk="${PAYLOAD_SDK:-}"
16+
payload_version="${PAYLOAD_VERSION:-}"
17+
payload_limit="${PAYLOAD_LIMIT:-}"
18+
19+
case "$event_name" in
20+
"workflow_dispatch")
21+
trigger="workflow_dispatch"
22+
sdk="${input_sdk:-all}"
23+
version="${input_version:-latest}"
24+
limit="${input_limit:-5}"
25+
force="${input_force:-false}"
26+
;;
27+
"repository_dispatch")
28+
trigger="repository_dispatch (sdk-release)"
29+
sdk="${payload_sdk:-all}"
30+
version="${payload_version:-latest}"
31+
limit="${payload_limit:-5}"
32+
force="false"
33+
;;
34+
"schedule")
35+
trigger="schedule (*/15 * * * *)"
36+
sdk="all"
37+
version="all"
38+
limit="3"
39+
force="false"
40+
;;
41+
*)
42+
trigger="${event_name:-unknown}"
43+
sdk="all"
44+
version="latest"
45+
limit="5"
46+
force="false"
47+
;;
48+
esac
49+
50+
if [[ -z "$limit" || "$limit" == "0" ]]; then
51+
limit_display="No limit"
52+
else
53+
limit_display="$limit"
54+
fi
55+
56+
{
57+
echo "trigger=$trigger"
58+
echo "sdk=$sdk"
59+
echo "version=$version"
60+
echo "limit=$limit"
61+
echo "limit_display=$limit_display"
62+
echo "force=$force"
63+
} >> "$GITHUB_OUTPUT"

‎sdk-reference-generator/README.md‎

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,7 @@ Tests cover:
138138
The generator runs in GitHub Actions on:
139139
- Manual workflow dispatch
140140
- Automatic repository dispatch from SDK repos on release
141+
- Scheduled sync every 15 minutes
141142

142143
### Manual Trigger (GitHub UI)
143144

@@ -172,10 +173,35 @@ curl -X POST \
172173
-d '{"event_type": "sdk-release", "client_payload": {"sdk": "js-sdk", "version": "v2.9.0"}}'
173174
```
174175

176+
### Scheduled Sync
177+
178+
The sync workflow also runs on a 15-minute cron interval:
179+
180+
```text
181+
*/15 * * * *
182+
```
183+
184+
Scheduled runs default to:
185+
- **SDK**: `all`
186+
- **Version**: `all`
187+
- **Limit**: `3`
188+
- **Force**: `false`
189+
190+
This acts as a polling safety net if an SDK release event is missed, while keeping the scheduled scan bounded to the latest three versions per SDK.
191+
192+
### Output Behavior
193+
194+
The sync workflow no longer pushes directly to `main`.
195+
196+
When generated docs change, the workflow now:
197+
- Creates or updates an automation branch
198+
- Opens a structured pull request with trigger metadata, generation parameters, and a link to the workflow run
199+
- Limits committed paths to `docs/sdk-reference/**` and `docs.json`
200+
175201
### Safety Features
176202

177203
- Validates all generated files before committing
178-
- Only commits if changes detected
204+
- Only creates a pull request if changes are detected
179205
- Full logging visible in workflow runs
180206
- User inputs passed via environment variables (prevents script injection)
181207

@@ -197,4 +223,3 @@ pnpm run generate --sdk js-sdk --limit 1
197223
# run tests
198224
pnpm test
199225
```
200-

0 commit comments

Comments
 (0)