Skip to content

[CI] Rework docs deployment #77

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Nov 7, 2025
+15 −6
Merged

[CI] Rework docs deployment #77

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
639a797
[CI] Rework docs deployment
giordano Nov 6, 2025
71ed6c0
[CI] Upload documentation build as an artifact
giordano Nov 6, 2025
83532ed
[docs] Push documentation to BreezeDocumentation
giordano Nov 6, 2025
42e881c
[CI] Use BreezeDocumentation Documenter key
giordano Nov 6, 2025
19132f8
[CI] Don't create token for PRs from forks
giordano Nov 7, 2025
907b6fa
[docs] Only push previews when all env vars are non-empty
giordano Nov 7, 2025
5f7621c
[CI] Don't use app to generate github token
giordano Nov 7, 2025
43a2ce4
Update link to documentation in README.md
giordano Nov 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 13 additions & 2 deletions .github/workflows/Documentation.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,10 +48,16 @@ jobs:
version: "min"
- uses: julia-actions/cache@v2
id: julia-cache
- uses: actions/create-github-app-token@v2
id: generate_token
if: ${{ ! github.event.pull_request.head.repo.fork }}
with:
app-id: "${{ secrets.NUMTERRA_BOT_ID }}"
private-key: "${{ secrets.NUMTERRA_BOT_PRIVATE_KEY }}"
- uses: julia-actions/julia-docdeploy@v1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
Copy link
Collaborator Author

@giordano giordano Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On a second thought, I'm not entirely sure an app is needed for this, pushing to the other repo happens via DOCUMENTER_KEY. Let me try that.

Copy link
Collaborator Author

@giordano giordano Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed that the app was unnecessary for this task after all. Oh well, we have it set up anyway, we can use it for something else cool!

DOCUMENTER_KEY: ${{ secrets.BREEZEDOCUMENTATION_DOCUMENTER_KEY }}
- name: Save Julia depot cache on cancel or failure
id: julia-cache-save
if: cancelled() || failure()
Expand All @@ -60,3 +66,8 @@ jobs:
path: |
${{ steps.julia-cache.outputs.cache-paths }}
key: ${{ steps.julia-cache.outputs.cache-key }}
- uses: actions/upload-artifact@v4
with:
name: documentation-build
path: docs/build
retention-days: 7
10 changes: 7 additions & 3 deletions docs/make.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,13 @@ makedocs(sitename="Breeze",
]
)

deploydocs(;
deploydocs(
;
repo = "github.com/NumericalEarth/Breeze.jl",
deploy_repo = "github.com/NumericalEarth/BreezeDocumentation",
devbranch = "main",
push_preview = true,
forcepush = true
# Only push previews if all the relevant environment variables are non-empty. This is an
# attempt to work around https://github.com/JuliaDocs/Documenter.jl/issues/2048.
push_preview = all(!isempty, (get(ENV, "GITHUB_TOKEN", ""), get(ENV, "DOCUMENTER_KEY", ""))),
Comment on lines +37 to +39
Copy link
Collaborator Author

@giordano giordano Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd need to wait for a PR by dependabot to be sure this is working correctly, but looking at https://github.com/NumericalEarth/Breeze.jl/actions/runs/19032077021/job/54348250773?pr=61#step:5:5 GITHUB_TOKEN isn't empty, but DOCUMENTER_KEY is, so making sure they're both non-empty should be a decent approach.

Copy link
Collaborator Author

@giordano giordano Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just learned about dependabot secrets, in principle we can set DOCUMENTER_KEY for dependabot too, but I think the solution I proposed should be robust in all cases, regardless of whether we decide to set DOCUMENTER_KEY for dependabot or not.

forcepush = true,
)
Loading