Skip to content

Commit 67ad130

Browse files
ekohlekohl
committed
Implement previews for GitHub pull requests
When a contributor submits a PR, we always perform a build. This takes it a step further and uploads that a custom surge.sh domain. It adds a sticky comment to link to that preview while also generating some diffs. This means reviews easier. In the implementation an additional preview step is added. This first builds the base (target of the PR) as the current. Then it downloads the generated preview that was added as an artifact in the original build step. Creating a reasonably sized diff was tricky, because there's a long Javascript line that includes the mtime, making it indeterministic. That line isn't relevant anyway, so it's removed. The diff command also ignores the search index. All of that is placed in the preview, making it readable. A sticky comment is added with a summary, making it easy to use. The sticky comment is updated for every push, rather than added a comment for every push. This keeps the PR conversation usable.
1 parent 439dda4 commit 67ad130

File tree

3 files changed

+144
-0
lines changed

3 files changed

+144
-0
lines changed

‎.github/download_workflow_run_artifact.js

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
module.exports = async ({github, context, core, fs, artifact_name}) => {
2+
let allArtifacts = await github.rest.actions.listWorkflowRunArtifacts({
3+
owner: context.repo.owner,
4+
repo: context.repo.repo,
5+
run_id: context.payload.workflow_run.id,
6+
});
7+
let matchArtifact = allArtifacts.data.artifacts.filter((artifact) => {
8+
return artifact.name == artifact_name
9+
})[0];
10+
let download = await github.rest.actions.downloadArtifact({
11+
owner: context.repo.owner,
12+
repo: context.repo.repo,
13+
artifact_id: matchArtifact.id,
14+
archive_format: 'zip',
15+
});
16+
fs.writeFileSync(`${process.env.GITHUB_WORKSPACE}/${artifact_name}.zip`, Buffer.from(download.data));
17+
};

‎.github/workflows/preview.yml

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
name: Preview
2+
3+
on:
4+
workflow_run:
5+
workflows:
6+
- deploy
7+
types:
8+
- completed
9+
10+
jobs:
11+
preview-failed:
12+
if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion != 'success'
13+
runs-on: ubuntu-latest
14+
steps:
15+
- name: Download metadata artifact
16+
uses: actions/github-script@v7
17+
with:
18+
script: |
19+
const script = require('./.github/download_workflow_run_artifact.js');
20+
let fs = require('fs');
21+
await script({github, context, core, fs, artifact_name: 'pr'});
22+
23+
- name: Unzip artifact
24+
run: unzip pr.zip
25+
26+
- name: Read PR data
27+
run: echo "PR_DATA=$(cat ./pr.json)" >> $GITHUB_ENV
28+
29+
- name: Comment on PR
30+
uses: marocchino/sticky-pull-request-comment@v2
31+
with:
32+
number: ${{ fromJSON(env.PR_DATA).pr_number }}
33+
message: "The PR preview for ${{ fromJSON(env.PR_DATA).head_sha }} could not be generated"
34+
35+
preview:
36+
runs-on: ubuntu-latest
37+
steps:
38+
# TODO: can this download from the existing pages or a cache?
39+
- name: Checkout
40+
uses: actions/checkout@v4
41+
with:
42+
persist-credentials: false
43+
44+
- name: Build current pages
45+
run: |
46+
npm install
47+
npx honkit build
48+
mv _book current
49+
50+
- name: Download metadata artifact
51+
uses: actions/github-script@v7
52+
with:
53+
script: |
54+
const script = require('./.github/download_workflow_run_artifact.js');
55+
let fs = require('fs');
56+
await script({github, context, core, fs, artifact_name: 'github-pages'});
57+
58+
- name: Unpack preview
59+
run: unzip github-pages.zip -d preview
60+
61+
- name: Remove indeterminism
62+
run: |
63+
find current/ preview/ -type f -exec sed -i '/gitbook.page.hasChanged/d' {} +
64+
65+
- name: Create diff to current
66+
run: |
67+
diff -Nrwu --exclude search_index.json current/ preview/ | cat > preview/diff.patch
68+
if [[ -s preview/diff.patch ]] ; then
69+
sudo apt-get update
70+
sudo apt-get install -y diffstat python3-pygments
71+
72+
pygmentize -o preview/diff.html -l diff -f html -O full preview/diff.patch
73+
diffstat -l -p2 preview/diff.patch > diff.txt
74+
fi
75+
76+
- name: Set preview domain
77+
run: echo "PREVIEW_DOMAIN=$(echo ${{ github.repository }} | tr / - )-${{ github.job }}-pr-${{ fromJSON(env.PR_DATA).pr_number }}.surge.sh" >> $GITHUB_ENV
78+
79+
- name: Install surge
80+
run: npm install surge
81+
82+
- name: Deploy to surge.sh
83+
run: npx surge ./preview $PREVIEW_DOMAIN --token ${{ secrets.SURGE_TOKEN }}
84+
85+
- name: Generate summary
86+
run: |
87+
echo "The PR preview for ${{ fromJSON(env.PR_DATA).head_sha }} is available at [${{ env.PREVIEW_DOMAIN }}](https://${{ env.PREVIEW_DOMAIN }})" >> pr.md
88+
echo "" >> pr.md
89+
90+
if [[ -f preview/diff.txt ]] ; then
91+
echo "The following output files are affected by this PR:" >> pr.md
92+
sed -E "s#(.*)#- [\1](https://${{ env.PREVIEW_DOMAIN }}/\1)#" preview/diff.txt >> pr.md
93+
else
94+
echo "No diff compared to the current website" >> pr.md
95+
fi
96+
97+
if [[ -s preview/diff.patch ]] ; then
98+
echo "" >> pr.md
99+
echo "[show diff](https://${{ env.PREVIEW_DOMAIN }}/diff.patch)" >> pr.md
100+
fi
101+
102+
if [[ -f preview/diff.html ]] ; then
103+
echo "" >> pr.md
104+
echo "[show diff as HTML](https://${{ env.PREVIEW_DOMAIN }}/diff.html)" >> pr.md
105+
fi
106+
107+
- name: Comment on PR
108+
uses: marocchino/sticky-pull-request-comment@v2
109+
with:
110+
number: ${{ fromJSON(env.PR_DATA).pr_number }}
111+
path: pr.md

‎.github/workflows/test.yml

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,19 @@ jobs:
1515
run: |
1616
npm install
1717
npx honkit build
18+
19+
- name: Upload artifact
20+
uses: actions/upload-artifact@v4
21+
with:
22+
name: github-pages
23+
path: _book/**
24+
25+
- name: Save PR metadata
26+
run: |
27+
mkdir -p ./pr
28+
echo '{"pr_number": ${{ github.event.number }}, "branch_name": "${{ env.BRANCH_NAME }}", "target_name": "${{ env.TARGET_NAME }}", "head_sha": "${{ github.event.pull_request.head.sha }}"}' > ./pr/pr.json
29+
30+
- uses: actions/upload-artifact@v4
31+
with:
32+
name: pr
33+
path: ./pr/

0 commit comments

Comments
 (0)