From b300512e89130cf253e206c574d54a081baec8df Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 25 Jun 2026 15:14:01 -0600 Subject: [PATCH] Reduce code dupe in workflows; improve workflows. --- .github/workflows/docs-build-and-deploy.yml | 68 ++++++------------- ...ocs-build_to_publish-optionally-deploy.yml | 49 +++++++++++++ .github/workflows/docs-to-publish.yml | 65 ++++++------------ .github/workflows/docs.yml | 12 ++-- 4 files changed, 97 insertions(+), 97 deletions(-) create mode 100644 .github/workflows/docs-build_to_publish-optionally-deploy.yml diff --git a/.github/workflows/docs-build-and-deploy.yml b/.github/workflows/docs-build-and-deploy.yml index aa3161c..1888359 100644 --- a/.github/workflows/docs-build-and-deploy.yml +++ b/.github/workflows/docs-build-and-deploy.yml @@ -1,25 +1,25 @@ -name: Deploy static content to Pages +name: Build and deploy docs on: push: # Run when a change to these files is pushed to any of these branches. - # When you copy this into your repo, you should update this list to include all the "ref"s you - # put in your version_list.py. + # When you copy this into your repo, you should: + # - Replace 'master' with the name of your repo's primary branch, if it's not master (e.g., + # main) + # - Delete 'add-github-workflows-with-tmp-docs' + # - Add any branches you refer to with DocsVersion(..., ref=*) in version_list.py branches: ['master', 'add-github-workflows-with-tmp-docs'] - # When you copy this into your repo, you should uncomment the following 2 lines: # paths: + # - '.github/workflows/docs-build-and-deploy.yml' + # - '.github/workflows/docs-build_to_publish-optionally-deploy.yml' # - 'doc/**' - # And also make sure to add any files that you "include" in your docs that live outside doc/ + # When you copy this into your repo: + # - Uncomment the "paths" block above + # - Make sure to add any files that you "include" in your docs that live outside doc/. # Allows you to run this workflow manually from the Actions tab workflow_dispatch: -# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages -permissions: - contents: read - pages: write - id-token: write - # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. concurrency: @@ -29,46 +29,18 @@ concurrency: jobs: build-and-deploy: + name: Call reusable workflow with deploy true # Only run on upstream repository. # When you copy this into your repo, replace this with yours. Case-sensitive! if: ${{ github.repository == 'ESMCI/doc-builder' }} - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - - runs-on: ubuntu-latest - steps: - - name: Checkout repository - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - with: - # Get all history, ensuring all branches are available for checkout - fetch-depth: 0 - submodules: true - - - name: Setup Pages - uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5 - - # Check out all submodules because we might :literalinclude: something from one - - name: Checkout all submodules - if: ${{ hashFiles('bin/git-fleximod') != '' }} - run: bin/git-fleximod update -o - - # When you copy this into your repo, update the --site-root URL. - - name: Build docs using container - id: build-docs - run: | - [[ -e doc ]] && cd doc - ./build_docs_to_publish -d --site-root https://esmci.github.io/doc-builder --verbose - - - name: Upload artifact - uses: actions/upload-pages-artifact@0252fc4ba7626f0298f0cf00902a25c6afc77fa8 # v3 - with: - # Upload publish dir - # When you copy this into your repo, change this to 'doc/_publish' - path: '_publish' + # Grant the GITHUB_TOKEN the write scopes needed to deploy to GitHub Pages. + permissions: + contents: read + pages: write + id-token: write - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@f33f41b675f0ab2dc5a6863c9a170fe83af3571e # v4 + uses: ./.github/workflows/docs-build_to_publish-optionally-deploy.yml + with: + deploy: true diff --git a/.github/workflows/docs-build_to_publish-optionally-deploy.yml b/.github/workflows/docs-build_to_publish-optionally-deploy.yml new file mode 100644 index 0000000..bb900ad --- /dev/null +++ b/.github/workflows/docs-build_to_publish-optionally-deploy.yml @@ -0,0 +1,49 @@ +name: Test building docs "to publish" when they're updated + +on: + workflow_call: + inputs: + deploy: + required: false + type: boolean + default: false + +jobs: + + build_to_publish-optionally-deploy: + name: Run build_to_publish and optionally deploy docs + runs-on: ubuntu-latest + + # Only associate this job with the github-pages environment when deploying. + environment: + name: ${{ inputs.deploy && 'github-pages' || '' }} + url: ${{ inputs.deploy && steps.deployment.outputs.page_url || '' }} + + steps: + + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + submodules: true + + - name: Build docs + id: build-docs + run: | + [[ -e doc ]] && cd doc + git fetch + site_root="https://${GITHUB_REPOSITORY%/*}.github.io/${GITHUB_REPOSITORY#*/}" + PYTHONUNBUFFERED=1 ./build_docs_to_publish -r ${PWD}/_build -d --verbose --site-root "${site_root}" + + # Subsequent steps should only happen if this workflow was called with deploy true + + - name: Upload artifact + if: ${{ inputs.deploy }} + uses: actions/upload-pages-artifact@0252fc4ba7626f0298f0cf00902a25c6afc77fa8 # v3 + with: + # Upload publish dir + path: 'doc/_publish' + + - name: Deploy to GitHub Pages + if: ${{ inputs.deploy }} + id: deployment + uses: actions/deploy-pages@f33f41b675f0ab2dc5a6863c9a170fe83af3571e # v4 diff --git a/.github/workflows/docs-to-publish.yml b/.github/workflows/docs-to-publish.yml index d8fbaf3..cd87560 100644 --- a/.github/workflows/docs-to-publish.yml +++ b/.github/workflows/docs-to-publish.yml @@ -1,61 +1,36 @@ -name: Test building docs "to publish" when they're updated +name: Test building docs "to publish" on: push: # Run when a change to these files is pushed to any branch. Without the "branches:" line, for some reason this will be run whenever a tag is pushed, even if the listed files aren't changed. branches: ['*'] - # When you copy this into your repo, you should uncomment the following 3 lines: + # But only when these files are updated: # paths: - # - 'doc/doc-builder' - # - 'doc/build_docs_to_publish' + # - '.github/workflows/docs-build-and-deploy.yml' + # - '.github/workflows/docs-build_to_publish-optionally-deploy.yml' + # - 'doc/**' + # When you copy this into your repo: + # - Uncomment the "paths" block above + # - Make sure to add any files that you "include" in your docs that live outside doc/. pull_request: # Run on pull requests that change the listed files - # When you copy this into your repo, you should uncomment the following 3 lines: # paths: - # - 'doc/doc-builder' - # - 'doc/build_docs_to_publish' - - workflow_dispatch: + # - '.github/workflows/docs-build-and-deploy.yml' + # - '.github/workflows/docs-build_to_publish-optionally-deploy.yml' + # - 'doc/**' + # When you copy this into your repo: + # - Uncomment the "paths" block above + # - Make sure to add any files that you "include" in your docs that live outside doc/. permissions: contents: read -jobs: - - test-build-docs-to-publish-container: - if: ${{ always() }} - name: With container from registry - runs-on: ubuntu-latest - steps: - - name: Checkout repository - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - with: - submodules: true - - - name: Build docs using Docker (Podman has trouble on GitHub runners) - id: build-docs - run: | - set -o pipefail - mkdir -p build-logs - [[ -e doc ]] && cd doc - git fetch - PYTHONUNBUFFERED=1 ./build_docs_to_publish -r ${PWD}/_build -d --verbose --site-root "$PWD/_publish" 2>&1 | tee >(sed -E $'s/\x1b\\[[0-9;]*[a-zA-Z]//g' > "${GITHUB_WORKSPACE}/build-logs/build.log") - # The tee writes build.log for the PR comment (posted by docs-pr-failure-post-comment.yml); the inner sed strips ANSI color codes that would otherwise render as garbage in the comment. - # PYTHONUNBUFFERED=1 because otherwise the teed log will be out of order - - # The rest of the steps only trigger on failure of above build-docs step. - # They upload logs that will be used by the docs-pr-failure-post-comment.yml workflow. +jobs: - - name: Record PR number on failure - if: failure() && steps.build-docs.outcome == 'failure' && github.event_name == 'pull_request' - run: | - mkdir -p build-logs - echo "${{ github.event.pull_request.number }}" > build-logs/pr_number.txt + build-to-publish-dont-deploy: + name: Call reusable workflow with deploy false - - name: Upload logs on failure - if: failure() && steps.build-docs.outcome == 'failure' - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 - with: - name: test-build-docs-to-publish-container_failed - path: build-logs/ + uses: ./.github/workflows/docs-build_to_publish-optionally-deploy.yml + with: + deploy: false diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 66aaa72..9828c8a 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -4,17 +4,21 @@ on: push: # Run when a change to these files is pushed to any branch. Without the "branches:" line, for some reason this will be run whenever a tag is pushed, even if the listed files aren't changed. branches: ['*'] - # When you copy this into your repo, you should uncomment the following 2 lines: # paths: + # - '.github/workflows/docs.yml' # - 'doc/**' - # And also make sure to add any files that you "include" in your docs that live outside doc/ + # When you copy this into your repo: + # - Uncomment the "paths" block above. + # - Make sure to add any files that you "include" in your docs that live outside doc/. pull_request: # Run on pull requests that change the listed files - # When you copy this into your repo, you should uncomment the following 2 lines: # paths: + # - '.github/workflows/docs.yml' # - 'doc/**' - # And also make sure to add any files that you "include" in your docs that live outside doc/ + # When you copy this into your repo: + # - Uncomment the "paths" block above. + # - Make sure to add any files that you "include" in your docs that live outside doc/. workflow_dispatch: