fix: support concurrent documentation deploys to GitHub Pages

[jamesfredley]

What

Makes the deploy-github-pages action safe when multiple documentation deploys publish concurrently. Today, when several release/snapshot builds push to the documentation branch at the same time, their pushes race: a rejected push runs a plain git pull --rebase, which stops on a merge conflict in the shared folders and - under set -e - kills the whole job. Concurrent releases therefore fail (observed in apache/grails-core doc publishing).

Why it happens

Different releases never collide on their specific X.X.X folders, but they all write the shared paths: latest, the generic X.X.x, the root index.html, and the snapshot folder. A concurrent deploy that lands first advances the branch, our push is rejected, and the naive rebase conflicts on those shared paths and aborts.

The fix

In deploy-github-pages/entrypoint.sh, the push-retry loop is now concurrency-safe:

• Rebase with -X theirs + backoff. The deploy commit is replayed onto the remote so a concurrent deploy's independent version folders are preserved, and shared-folder file-content conflicts auto-resolve in favour of this deploy. Retries use bounded backoff with jitter.
• Reconcile owned paths. After the rebase, purge-owned folders (PURGE_EXISTING=true) are restored wholesale from this deploy's commit (clean last-writer-wins), so a shared folder never becomes a union of both deploys' files. Merge-mode folders (PURGE_EXISTING=false) are deliberately left to the -X theirs merge so a concurrent deploy's independent changes survive.
• latest is highest-version-wins. A lower release replayed after a concurrent higher release yields latest back to the remote instead of overwriting it with older docs.
• Modify/delete conflicts resolved.-X theirs cannot auto-resolve a modify/delete conflict (a file this deploy purges that a concurrent deploy modified). Instead of aborting and re-hitting the same conflict until attempts are exhausted, the rebase is now driven to completion deterministically.

Tests

Adds a Testcontainers regression test to DeployGithubPagesSpec that lands a concurrent deploy modifying a file this deploy purges (a real modify/delete conflict) and asserts the retry recovers cleanly - the deploy's own content wins and the stale file is removed. All existing deploy tests pass.

Note / follow-up

apache/grails-static-website exhibits the same class of race, but in a separate Gradle publish task (:publishMainSite pushing to apache/grails-websiteasf-site-production), which lives outside this repository. That will need a separate follow-up fix in that project - it is not addressed here.

[Copilot]

Pull request overview

This PR makes the deploy-github-pages GitHub Action resilient to concurrent documentation deployments by changing the push-retry strategy to rebase onto the remote with deterministic conflict handling, then reconciling “owned” paths to enforce intended last-writer-wins semantics. It also adds a regression test that simulates a real modify/delete conflict caused by a concurrent deploy.

Changes:

• Update the deploy action’s push-retry loop to use git pull --rebase -X theirs, add bounded backoff, and deterministically resolve modify/delete conflicts during rebase.
• Track and reconcile “owned” publish paths after rebase (including special handling so latest remains highest-version-wins).
• Add a Testcontainers-based regression test covering a concurrent deploy that modifies a file this deploy purges.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
deploy-github-pages/entrypoint.sh	Implements concurrency-safe push retries with rebase-based conflict resolution and owned-path reconciliation logic.
tests/src/test/groovy/org/apache/grails/github/DeployGithubPagesSpec.groovy	Updates existing retry-log expectation and adds a new regression test for modify/delete conflict recovery.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jdaugherty]

Wouldn't it be better to have a concurrency key or some other solution that blocks the run?

[jdaugherty]

 concurrency:
group: shared-exclusive-operation
cancel-in-progress: false
queue: max

This can be added per job, so we can have a unique concurrency key per job. I don't believe this change is warranted.

[jdaugherty]

apache/grails-core#15988 is an alternative and I think a better solution than complicating the action.

[jdaugherty]

I'm closing this for now since I've merged the other change. let's revisit if you disagree

[jdaugherty]

I'm still against this solution because we're relying on force repushing. We need to solve this outside of the action.

[jdaugherty]

apache/grails-core#15988 (comment) shows why the original solution didn't work. The reason I'm so against this change is we're effectively trying to solve a shared resource issue inside of a thread instead of outside of it.

[jamesfredley]

Replaced by #110 and apache/grails-core#16110