Skip to content

feat(doc): surface the docs preview artifact in the PR job summary - #314

Merged
Minipada merged 2 commits into
jazzyfrom
feature/135-publish-a-documentation-preview-from-pr
Aug 10, 2026
Merged

feat(doc): surface the docs preview artifact in the PR job summary#314
Minipada merged 2 commits into
jazzyfrom
feature/135-publish-a-documentation-preview-from-pr

Conversation

@Minipada

Copy link
Copy Markdown
Owner

Summary

doc.yaml (#252) already uploaded the built mdbook site as a workflow artifact (doc-site) on every run, including PRs — nothing restricted that step to push. What #135 actually needed was discoverability: the artifact was buried in the run's Artifacts section, several clicks past where a reviewer lands from the PR's Checks tab.

  • Give the Upload the built site step an id and, on pull_request runs, read its artifact-url output (available immediately post-upload since upload-artifact v4) into an env var and write a Markdown download link to $GITHUB_STEP_SUMMARY — the same page "Details" on a PR check opens.
  • Stayed artifact-only rather than a hosted deploy: this repo has no preview host configured (Preview documentation in each PR (netlify?) #184 closed without one), and reaching fork PRs with a hosted preview would need pull_request_target plus a deploy token — secrets exposed to untrusted PR code. pull_request keeps this safe; its default GITHUB_TOKEN is read-only, which is all an artifact upload needs, so fork PRs get the same preview link as same-repo PRs.
  • Updated the workflow's header comment to document the new behavior and the reasoning for staying artifact-only.

Acceptance criteria (from #135)

  • Preview (artifact download at minimum) reachable from the PR checks — one-click link in the job summary
  • Works for fork PRs, or degrades gracefully with the limitation documented — pull_request trigger, no secrets, documented in the workflow header
  • No secrets exposed to untrusted PR code — no secrets used at all

Test plan

  • pre-commit run --files .github/workflows/doc.yamlcheck-yaml passes; the build-doc hook (real strictdoc export + mdbook build) passes unaffected
  • Not verified end-to-end against a live Actions run (would need this PR's own CI to actually execute the new step) — artifact-url output and $GITHUB_STEP_SUMMARY are documented, stable GitHub Actions features

Closes #135

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com

https://claude.ai/code/session_01BxvjR5XyyaEPBBpwGfUK9W

@codecov

codecov Bot commented Aug 10, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 40.50%. Comparing base (1fd33b6) to head (81c41ce).

Additional details and impacted files
@@           Coverage Diff           @@
##            jazzy     #314   +/-   ##
=======================================
  Coverage   40.50%   40.50%           
=======================================
  Files          82       82           
  Lines        5094     5094           
=======================================
  Hits         2063     2063           
  Misses       3031     3031           
Flag Coverage Δ
cpp-jazzy 40.50% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Minipada and others added 2 commits August 10, 2026 11:35
doc.yaml already uploaded the built book as a workflow artifact on
every run, including PRs, but finding it meant digging into the run's
Artifacts section. Capture the upload step's artifact-url output and
write a direct download link to $GITHUB_STEP_SUMMARY on PR runs, so
the preview is one click from the PR's Checks tab.

Stays artifact-only rather than a hosted deploy: this repo has no
preview host configured (#184), and reaching one from a fork PR would
need pull_request_target plus a deploy token exposed to untrusted PR
code. pull_request keeps this safe for fork PRs since the default
GITHUB_TOKEN there is read-only, which is all an artifact upload
needs.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BxvjR5XyyaEPBBpwGfUK9W
Signed-off-by: David Bensoussan <d.bensoussan@proton.me>
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BxvjR5XyyaEPBBpwGfUK9W
Signed-off-by: David Bensoussan <d.bensoussan@proton.me>
@Minipada
Minipada force-pushed the feature/135-publish-a-documentation-preview-from-pr branch from 09f9a4f to 81c41ce Compare August 10, 2026 09:36
@Minipada
Minipada merged commit 2b7cc67 into jazzy Aug 10, 2026
10 of 11 checks passed
@Minipada
Minipada deleted the feature/135-publish-a-documentation-preview-from-pr branch August 16, 2026 14:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant