Add deploy.mode: branch to publish the site to a Pages branch by avillar · Pull Request #106 · opengeospatial/bblocks-postprocess

avillar · 2026-10-28T21:17:51Z

Closes #46, closes #52. Relates to #102.

Adds an alternative to the current deployment: instead of committing build/ to the source branch and deploying a Pages artifact, validate-and-process.yml can publish the built site to a branch (gh-pages by default). Source branches then stay free of build output, while the artifacts remain browsable and versioned in git.

Configuration

In bblocks-config.yaml (bblocks-config-override.yml applies as for other keys):

deploy:
  mode: branch      # "artifact" (default, current behavior) or "branch"
  branch: gh-pages  # only used in "branch" mode; default gh-pages

Nothing changes for repos that don't set deploy.

What `mode: branch` does

Skips the build/ commit to the source branch and the Pages artifact steps (configure-pages, upload-pages-artifact, deploy-pages).
Mirrors the site (same content that the artifact mode uploads) into the target branch with rsync --delete: created as an orphan branch if it doesn't exist, .nojekyll added (branch deployments would otherwise run Jekyll and drop underscore-prefixed paths), committed and pushed only if something changed. Each commit records the source commit in its message.
Leaves out hidden files, the _repos_* clones and the scripts/URL mappings generated for them (a bblocks-config-local.yml shipped by the repo itself is kept).
Fails early if GitHub Pages is not set to "Deploy from a branch" serving that branch from / (root), instead of silently publishing to a branch nobody serves.
Waits for Pages to serve the new register.json (checksum comparison) before upload-to-triplestore runs, only when a SPARQL endpoint is configured, since a branch push deploys asynchronously.

The deploy section is also added to bblocks-config.schema.yaml (with tests); the postprocessor itself ignores it.

Trying it on a register

In a throwaway register (or a fork), point the caller workflow (process-bblocks.yml) at this branch: uses: opengeospatial/bblocks-postprocess/.github/workflows/validate-and-process.yml@deploy-mode-branch. Only the workflow file changes in this PR; the nested full@v1 action and the Docker image are unchanged.
Add deploy: {mode: branch} to its bblocks-config.yaml.
Push. The first run creates the gh-pages branch (with a warning that Pages isn't serving it yet) and publishes the site to it. build/ is not committed to the source branch.
In the repository settings, set Pages to "Deploy from a branch", gh-pages, / (root). The branch can't be selected before the first run has created it.
Push again (or re-run the workflow): from now on the Pages source is checked at the start of each run, and the site is served from the branch.

To switch an existing register, also stop tracking build/ on the source branch (add it to .gitignore and git rm -r --cached build).

Testing

Unit tests for the schema section; full suite passes.
The config-reading and branch-publish shell steps were run locally against a bare remote: new orphan branch, no-op re-run (no commit), changed/removed files, invalid mode, branch equal to source branch, override file, generated vs. shipped bblocks-config-local.yml.
Not yet verified: an actual Actions run (Pages API check, Pages build, wait step). Needs a throwaway repo with Pages set to "Deploy from a branch" before release; it would be great if someone could try it on a real register.

Docs and template updates will follow once this is merged and released.

validate-and-process.yml can now publish the built site to a branch (gh-pages by default) instead of committing build/ to the source branch and deploying a Pages artifact. It is selected from bblocks-config.yaml (bblocks-config-override.yml applies), with two new keys: - deploy.mode: "artifact" (default, current behavior) or "branch" - deploy.branch: branch to publish to in "branch" mode (default "gh-pages") In branch mode the workflow skips the build/ commit and the Pages artifact steps, mirrors the site into the target branch (created as an orphan branch if missing, with .nojekyll), and commits and pushes only when something changed. Hidden files, the cloned repositories and the scripts and URL mappings generated for them are left out. It fails early if GitHub Pages is not set to serve that branch, and waits for Pages to serve the new register.json before the triplestore upload job runs.

… yet In branch mode, the Pages source guard failed the run when Pages was still set to "GitHub Actions". But GitHub only lets you select an existing branch as the Pages source, and the first run is what creates it, so a first-time switch could never get past the guard. If the branch doesn't exist, warn (with what to set afterwards) instead of failing.

rob-metalinkage

Is this intended to be default? Or recommended?

avillar · 2026-10-28T22:08:49Z

The default is artifact, i.e. how it works right now; branch is opt-in via deploy.mode.

…atial/bblocks-postprocess#106)

fmigneault · 2026-10-29T01:08:47Z

Let's see how it goes: fmigneault/bblocks-process-profiles-deploy-ghpages@693c45a

fmigneault · 2026-10-29T01:22:07Z

It "works": https://github.com/fmigneault/bblocks-process-profiles-deploy-ghpages/deployments/github-pages
I had to trigger twice to avoid the first-pull skip of the CI.

A bit odd that it shows "Deploying to github-pages" during the build/validate phase, before the actual "upload" phase.

https://github.com/fmigneault/bblocks-process-profiles-deploy-ghpages/actions/runs/40798904493

Build worked, but upload was skipped. Deploy reports it was done, but not the case.

Does the gh-pages need to be created beforehand? Or a specific setting configured ahead of it?
(CI config seems to hint it should create the missing branch for us, so not sure why it was skipped)

fmigneault · 2026-10-29T01:29:57Z

It seemed to have entered the usual "push commit build/" path:
fmigneault/bblocks-process-profiles-deploy-ghpages@ddff8a9

fmigneault · 2026-10-29T01:44:45Z

my bad, forgot to refer at the relevant branch providing the CI feature 🤦
fmigneault/bblocks-process-profiles-deploy-ghpages@4d78069

Now it worked as intended!
https://github.com/fmigneault/bblocks-process-profiles-deploy-ghpages/tree/gh-pages

However, the content is not where I would expect?
https://fmigneault.github.io/bblocks-process-profiles-deploy-ghpages/

Last step skipped?

fmigneault · 2026-10-29T01:52:45Z

Enabled GitHub Pages from config. Now it got picked up.
However, it does weird redirects.

https://fmigneault.github.io/bblocks-process-profiles-deploy-ghpages/
-> 
https://fmigneault.github.io/https://ogcincubator.github.io/bblocks-viewer/bblocks-process-profiles-deploy-ghpages/

…ranch mode The raw.githubusercontent.com fallback used context.ref_name, which does not exist in github-script's context, so the generated URL ended in /undefined. It now uses the ref being built. In deploy.mode: branch the site only exists on the deploy branch, so when the Pages API call fails (e.g. on the first run, before Pages is pointed at the branch) fall back to the default Pages URL instead.

avillar · 2026-10-29T07:45:10Z

@fmigneault thanks for testing! The .../undefined/config.js URL was a bug in the base URL fallback (used when the Pages API can't be read, which is the case on the first run in branch mode, before Pages is pointed at the branch). It's fixed in 88ed7ed: in branch mode the fallback is now the default Pages URL (https://<owner>.github.io/<repo>), and in artifact mode the raw URL no longer ends in undefined.

Could you re-run the workflow on your register (it picks up the fix from this branch) and let me know how it goes? If you use a custom domain, set base_url explicitly.

fmigneault · 2026-10-29T15:00:56Z

Rerunning it now creates this error:

Not sure why yet because 88ed7ed doesn't look like it tweaks anything about permissions.

~~I don't have any specific protection rules on that repository AFAIK.~~
Nevermind. GitHub enabled something behind the scene when activating the whole gh-pages publishing configuration.

I had to manually apply master on top of gh-pages to trigger it from the main branch.

Retesting it now.

fmigneault · 2026-10-29T15:14:19Z

Looks all good now: https://fmigneault.github.io/bblocks-process-profiles-deploy-ghpages/

…hub-pages environment The validate-and-process job declared the github-pages environment unconditionally. Once Pages is set to deploy from a branch, GitHub restricts that environment's deployment branches, so runs from the default branch were rejected before starting, even though branch mode never deploys through the Actions Pages API. actions/deploy-pages now runs in a separate deploy-pages job (artifact mode only) that holds the environment. upload-to-triplestore waits for it, using always() so that it still runs when deploy-pages is skipped in branch mode.

avillar · 2026-10-29T15:32:59Z

@fmigneault thanks, that error was a real bug on my side. The validate-and-process job always declared the github-pages environment, even in branch mode. Once Pages is set to deploy from a branch, GitHub restricts that environment's deployment branches to the Pages branch, so any run from master was rejected before it started. That also explains the "Deploying to github-pages" status you saw during the build phase.

It's fixed in 51aed2f: the Actions-based deployment now lives in a separate deploy-pages job that only runs in artifact mode, so branch mode never touches the environment.

I've tested it on a fresh repo created from bblocks-template, with Pages set to deploy from gh-pages and the environment restricted to custom branches, which is the same situation as yours. It works on the first run (it creates gh-pages) and on the second, once Pages is configured: https://avillar.github.io/test-pr-106/

Could you re-run the workflow on your register (it picks up the fix from the deploy-mode-branch branch)? You shouldn't need to change any environment settings.

fmigneault · 2026-10-29T19:08:57Z

It worked.

avillar requested a review from rob-metalinkage as a code owner October 28, 2026 21:17

avillar mentioned this pull request Oct 28, 2026

Improve build strategy #102

Open

rob-metalinkage reviewed Oct 28, 2026

View reviewed changes

fmigneault added a commit to fmigneault/bblocks-process-profiles-deploy-ghpages that referenced this pull request Oct 29, 2026

try deploy mode gh-pages of bblocks-postprocess (relates to opengeosp…

693c45a

…atial/bblocks-postprocess#106)

Navigation Menu

Repository navigation

Add deploy.mode: branch to publish the site to a Pages branch - #106

Add deploy.mode: branch to publish the site to a Pages branch#106
avillar wants to merge 4 commits into
masterfrom
deploy-mode-branch

avillar commented Oct 28, 2026 •

edited

Loading

Uh oh!

rob-metalinkage left a comment

Uh oh!

avillar commented Oct 28, 2026

Uh oh!

fmigneault commented Oct 29, 2026

Uh oh!

fmigneault commented Oct 29, 2026 •

edited

Loading

Uh oh!

fmigneault commented Oct 29, 2026

Uh oh!

fmigneault commented Oct 29, 2026 •

edited

Loading

Uh oh!

fmigneault commented Oct 29, 2026 •

edited

Loading

Uh oh!

avillar commented Oct 29, 2026

Uh oh!

fmigneault commented Oct 29, 2026 •

edited

Loading

Uh oh!

fmigneault commented Oct 29, 2026

Uh oh!

avillar commented Oct 29, 2026

Uh oh!

fmigneault commented Oct 29, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

avillar commented Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Configuration

What mode: branch does

Trying it on a register

Testing

Uh oh!

rob-metalinkage left a comment

Choose a reason for hiding this comment

Uh oh!

avillar commented Oct 28, 2026

Uh oh!

fmigneault commented Oct 29, 2026

Uh oh!

fmigneault commented Oct 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fmigneault commented Oct 29, 2026

Uh oh!

fmigneault commented Oct 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fmigneault commented Oct 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

avillar commented Oct 29, 2026

Uh oh!

fmigneault commented Oct 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fmigneault commented Oct 29, 2026

Uh oh!

avillar commented Oct 29, 2026

Uh oh!

fmigneault commented Oct 29, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

avillar commented Oct 28, 2026 •

edited

Loading

What `mode: branch` does

fmigneault commented Oct 29, 2026 •

edited

Loading

fmigneault commented Oct 29, 2026 •

edited

Loading

fmigneault commented Oct 29, 2026 •

edited

Loading

fmigneault commented Oct 29, 2026 •

edited

Loading