{{ message }}
Repository navigation
272 lines (234 loc) · 10.7 KB
/
Copy pathsync-sdk-docs.yml
File metadata and controls
272 lines (234 loc) · 10.7 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
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
name: 'Sync Copilot SDK docs'
# Syncs Copilot SDK docs after copilot-sdk docs changes and opens an update PR.
# Supports manual dry runs and pull request validation without publishing.
on:
repository_dispatch:
types: [sync-sdk-docs]
workflow_dispatch:
inputs:
dry_run:
description: 'Dry run — run normalization but skip push and PR creation'
required: false
default: 'false'
type: boolean
source_ref:
description: 'copilot-sdk ref to sync from (branch, tag, or SHA). Defaults to main.'
required: false
default: 'main'
type: string
pull_request:
types: [opened, synchronize, reopened]
paths:
- '.github/workflows/sync-sdk-docs.yml'
- 'content/copilot/get-started/sdk-quickstart.md'
- 'src/workflows/sync-sdk-docs/**'
concurrency:
group: sync-sdk-docs-${{ github.event_name }}
cancel-in-progress: true
permissions:
contents: write
pull-requests: write
jobs:
sync-docs:
name: 'Sync SDK docs'
if: github.repository == 'github/docs-internal'
runs-on: ubuntu-latest
env:
SDK_DOCS_TARGET: content/copilot/how-tos/copilot-sdk
SYNC_BRANCH: sdk-docs/auto-sync
ASSETS_TARGET: assets/images/help/copilot/copilot-sdk
SOURCE_REF: ${{ inputs.source_ref || 'main' }}
steps:
- name: Checkout docs-internal
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
# Publishing runs must start from the default branch because preserve-redirects.ts reads
# live URLs from git HEAD. workflow_dispatch from another branch could write stale redirects.
- name: Verify publishing runs start from the default branch
if: github.event_name != 'pull_request' && inputs.dry_run != 'true'
run: |
if [ "$GITHUB_REF_NAME" != "$DEFAULT_BRANCH" ]; then
echo "::error::This run would push and open a PR, but it started from" \
"'$GITHUB_REF_NAME' rather than the default branch '$DEFAULT_BRANCH'." \
"HEAD is the baseline for redirect preservation, so syncing from another" \
"branch can drop or invent redirects. Re-run from '$DEFAULT_BRANCH', or" \
"use the dry_run input to test from a branch."
exit 1
fi
env:
DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
- name: Fetch SDK docs from copilot-sdk
env:
GH_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
run: |
set -e
tmp=$(mktemp -d)
echo "Cloning copilot-sdk@$SOURCE_REF (sparse: docs/ only)..."
git clone --depth 1 --branch "$SOURCE_REF" --filter=blob:none --sparse \
"https://x-access-token:${GH_TOKEN}@github.com/github/copilot-sdk.git" "$tmp" 2>&1 | tail -1
cd "$tmp" && git sparse-checkout set docs 2>/dev/null
SDK_SHA=$(git -C "$tmp" rev-parse HEAD)
echo "SDK_SHA=$SDK_SHA" >> "$GITHUB_ENV"
echo "SDK_TMP=$tmp" >> "$GITHUB_ENV"
echo "Fetched copilot-sdk@${SDK_SHA::7}"
- name: Set up Node and dependencies
uses: ./.github/actions/node-npm-setup
- name: Install mermaid-cli
run: npm install -g @mermaid-js/mermaid-cli@11
- name: Clean existing SDK docs
run: |
rm -rf "$SDK_DOCS_TARGET"
- name: Copy SDK docs
run: |
mkdir -p "$SDK_DOCS_TARGET"
# Keep relocated pages in the rsync input. RELOCATED_PAGES in
# src/workflows/sync-sdk-docs/normalize-sdk-docs.ts removes them and
# repoints inbound links.
rsync -av --exclude='.validation/' --exclude='developer-docs/' "$SDK_TMP/docs/" "$SDK_DOCS_TARGET/"
echo "Copied $(find "$SDK_DOCS_TARGET" -name '*.md' | wc -l | tr -d ' ') markdown files"
- name: Normalize content
run: |
npx tsx src/workflows/sync-sdk-docs/normalize-sdk-docs.ts \
--content-dir content \
--sdk-docs-dir "$SDK_DOCS_TARGET"
- name: Preserve redirects
run: |
# --git-ref HEAD points preserve-redirects.ts at the currently live URLs. Publishing runs
# have already verified HEAD is the default branch; pull_request runs stay dry-run only.
# Removed pages still produce a PR for redirect review. The script writes at-risk URLs and
# a copy-pasteable redirect_from block to the run summary either way.
npx tsx src/workflows/sync-sdk-docs/preserve-redirects.ts \
--sdk-docs-dir "$SDK_DOCS_TARGET" \
--git-ref HEAD
- name: Convert Mermaid diagrams to PNG
env:
PUPPETEER_CHROMIUM_REVISION: ''
run: |
# Puppeteer needs --no-sandbox on GitHub Actions runners.
echo '{ "args": ["--no-sandbox", "--disable-setuid-sandbox"] }' > /tmp/puppeteer-config.json
npx tsx src/workflows/sync-sdk-docs/convert-mermaid.ts \
--sdk-docs-dir "$SDK_DOCS_TARGET" \
--assets-dir "$ASSETS_TARGET" \
--repo-root . \
--puppeteer-config /tmp/puppeteer-config.json
- name: Remove stale SDK assets
run: |
if [ ! -d "$ASSETS_TARGET" ]; then
echo "No assets directory — nothing to clean."
exit 0
fi
REFERENCED=$(grep -roh '/assets/images/help/copilot/copilot-sdk/[^)]*' "$SDK_DOCS_TARGET" \
| sed 's|.*/||' | sort -u)
STALE=0
for file in "$ASSETS_TARGET"/*.png; do
[ -f "$file" ] || continue
BASENAME=$(basename "$file")
if ! echo "$REFERENCED" | grep -qxF "$BASENAME"; then
echo " STALE: $BASENAME"
rm "$file"
STALE=$((STALE + 1))
fi
done
echo "Removed $STALE stale asset(s)."
- name: Lint SDK content (non-blocking)
continue-on-error: true
run: |
SDK_FILES=$(find "$SDK_DOCS_TARGET" -name '*.md' | tr '\n' ' ')
if [ -z "$SDK_FILES" ]; then
echo "No SDK markdown files to lint."
exit 0
fi
echo "Linting $(echo "$SDK_FILES" | wc -w | tr -d ' ') SDK files..."
if npm run lint-content -- --paths $SDK_FILES; then
echo "✅ Content linter passed — no issues found."
else
echo ""
echo "⚠️ Content linter found issues (see above)."
echo "These will appear as CI failures on the generated PR."
echo "Fix them in the copilot-sdk source docs or update the normalize script."
fi
- name: Show diff summary
run: |
git add -A
if git diff --cached --quiet; then
echo "No changes detected."
echo "has_changes=false" >> "$GITHUB_ENV"
else
echo "has_changes=true" >> "$GITHUB_ENV"
echo "Changes detected:"
git diff --cached --stat
fi
- name: Upload normalized docs (PR validation)
if: github.event_name == 'pull_request'
uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
with:
name: normalized-sdk-docs
path: |
${{ env.SDK_DOCS_TARGET }}
${{ env.ASSETS_TARGET }}
retention-days: 7
- name: Commit and push
if: >-
env.has_changes == 'true'
&& github.event_name != 'pull_request'
&& inputs.dry_run != 'true'
env:
GH_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
# Fetch the sync branch if it exists so force-with-lease knows the remote state.
git fetch origin "$SYNC_BRANCH" 2>/dev/null || true
git checkout -B "$SYNC_BRANCH"
git commit -m "Sync Copilot SDK docs from copilot-sdk@${SDK_SHA::7}
Source commit: https://github.com/github/copilot-sdk/commit/$SDK_SHA
This commit was automatically generated by the sync-sdk-docs workflow."
git push --force-with-lease origin "$SYNC_BRANCH"
- name: Create or update pull request
if: >-
env.has_changes == 'true'
&& github.event_name != 'pull_request'
&& inputs.dry_run != 'true'
env:
GH_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
run: |
PR_TITLE="Sync Copilot SDK docs (auto-generated)"
PR_BODY="## Summary
This PR syncs documentation from [\`github/copilot-sdk/docs\`](https://github.com/github/copilot-sdk/tree/main/docs) to \`content/copilot/how-tos/copilot-sdk/\`.
**Source commit:** https://github.com/github/copilot-sdk/commit/$SDK_SHA
### What this PR does
- Copies SDK documentation from \`copilot-sdk\`
- Adds YAML frontmatter for docs.github.com publishing
- Converts internal links to AUTOTITLE format
- Converts Mermaid diagrams to PNG images
- Normalizes code fence languages and list formatting
> [!NOTE]
> This PR is auto-generated. Do not edit it directly — make changes in the [copilot-sdk docs](https://github.com/github/copilot-sdk/tree/main/docs) instead. Exception: \`redirect_from\` cannot come from upstream, so add redirects here.
---
_Generated by the [sync-sdk-docs workflow run]($GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID)._"
EXISTING_PR=$(gh pr list --head "$SYNC_BRANCH" --json number --jq '.[0].number' 2>/dev/null || true)
if [ -n "$EXISTING_PR" ]; then
echo "Updating existing PR #$EXISTING_PR"
gh pr edit "$EXISTING_PR" --title "$PR_TITLE" --body "$PR_BODY"
gh pr comment "$EXISTING_PR" --body "🔄 Updated with changes from [\`${SDK_SHA::7}\`](https://github.com/github/copilot-sdk/commit/$SDK_SHA)."
else
echo "Creating new PR"
gh pr create \
--title "$PR_TITLE" \
--body "$PR_BODY" \
--base main \
--head "$SYNC_BRANCH" \
--label "copilot-sdk-docs,workflow-generated"
fi
- name: Cleanup
if: always()
run: rm -rf "$SDK_TMP"
- uses: ./.github/actions/create-workflow-failure-issue
id: create-failure-issue
if: ${{ failure() && github.event_name != 'workflow_dispatch' && github.event_name != 'pull_request' }}
with:
token: ${{ secrets.DOCS_BOT_PAT_BASE }}
- uses: ./.github/actions/slack-alert
if: ${{ failure() && github.event_name != 'workflow_dispatch' && github.event_name != 'pull_request' }}
with:
slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
issue_url: ${{ steps.create-failure-issue.outputs.issue_url }}
You can’t perform that action at this time.