Fix gh-pages deploy race condition #101
Workflow file for this run
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Build Python Sphinx Docs and push to gh-pages | |
| on: | |
| push: | |
| branches: | |
| - '**' | |
| # Use pull_request (not pull_request_target) to build-test docs on PRs targeting master. | |
| # When a PR is merged, only the 'push' event triggers deployment to gh-pages. | |
| # Using pull_request_target here previously caused a race condition: merging a PR fired | |
| # both 'push' and 'pull_request_target' simultaneously, producing two concurrent runs | |
| # that both tried to force-push to gh-pages. The loser would fail with: | |
| # "cannot lock ref 'refs/heads/gh-pages': is at <new-sha> but expected <old-sha>" | |
| # See: https://github.com/OPM/opm-python-documentation/actions/runs/21938360885 | |
| pull_request: | |
| branches: [master] | |
| repository_dispatch: | |
| types: [docstrings_common_updated, docstrings_simulators_updated] | |
| permissions: | |
| contents: write | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout source code | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 # Fetch all history for all tags and branches | |
| - name: Create tmp directories for master | |
| run: | | |
| mkdir python/master-tmp | |
| # Download master JSON files to master-tmp/ directory | |
| # This supports sphinx-versioned multi-version documentation builds: | |
| # - sphinx-versioned builds docs for multiple branches (master, release-*, current branch) | |
| # - Each branch version looks for JSON files in different locations (see conf.py) | |
| # - master-tmp/ provides a shared location for current master JSON files that doesn't | |
| # interfere with committed release snapshots in python/ directory | |
| - name: Get docstrings_common.json from master branch of opm-common | |
| run: | | |
| curl -L -o python/master-tmp/docstrings_common.json https://raw.githubusercontent.com/OPM/opm-common/master/python/docstrings_common.json | |
| - name: Get docstrings_common.json from master branch of opm-simulators | |
| run: | | |
| curl -L -o python/master-tmp/docstrings_simulators.json https://raw.githubusercontent.com/OPM/opm-simulators/master/python/docstrings_simulators.json | |
| - name: Get dune.module from master branch of opm-simulators, this is needed for the call to extract_opm_simulators_release in python/sphinx_docs/docs/conf.py. | |
| run: | | |
| curl -L -o python/master-tmp/dune.module https://raw.githubusercontent.com/OPM/opm-simulators/master/dune.module | |
| - name: Set up Python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: "3.11" | |
| - name: Install poetry | |
| uses: OPM/actions-poetry@master | |
| - name: Install python dependencies | |
| run: | | |
| cd python/sphinx_docs | |
| poetry install | |
| - name: Build documentation | |
| run: | | |
| cd python | |
| mkdir gh-pages | |
| touch gh-pages/.nojekyll | |
| cd sphinx_docs | |
| # To add a new release to this build system: | |
| # - add the respective branch <your-new-release> on this repository, replace the slashes "/" by dashes "-" | |
| # (slashes mess with the navigation html created by sphinx-versioned) | |
| # - take a snapshot of https://raw.githubusercontent.com/OPM/opm-common/<your-new-release>/python/docstrings_common.json, | |
| # https://raw.githubusercontent.com/OPM/opm-simulators/<your-new-release>/python/docstrings_simulators.json and | |
| # https://raw.githubusercontent.com/OPM/opm-simulators/<your-new-release>/dune.module and put them | |
| # in the python folder on that branch | |
| # Once created, the script below will automatically detect and include the new release branch | |
| # Dynamically determine which branches to build documentation for | |
| # This allows the workflow to work on forks that may not have all release branches | |
| BRANCHES=$(../scripts/get_doc_branches.sh "${{ github.ref_name }}") | |
| echo "Building documentation for branches: $BRANCHES" | |
| poetry run sphinx-versioned -m master -b "$BRANCHES" --force --git-root ../../ | |
| - name: Copy documentation to gh-pages | |
| run: | | |
| cp -r python/sphinx_docs/docs/_build/* python/gh-pages | |
| - name: Deploy documentation for PR merge to master or push to master | |
| if: github.ref == 'refs/heads/master' | |
| uses: OPM/github-pages-deploy-action@releases/v4 | |
| with: | |
| branch: gh-pages | |
| folder: python/gh-pages | |
| - name: Deploy documentation for other branches (on forks) | |
| if: github.event_name == 'push' && github.ref != 'refs/heads/master' && !startsWith(github.ref, 'refs/heads/release') | |
| uses: OPM/github-pages-deploy-action@releases/v4 | |
| with: | |
| branch: gh-pages-${{ github.ref_name }} | |
| folder: python/gh-pages |