From 122063a30eab801ea471d9e2da8420737827b0b6 Mon Sep 17 00:00:00 2001 From: eecavanna Date: Wed, 29 Jan 2025 20:07:51 -0800 Subject: [PATCH] Refactor GHA workflows so build steps are decoupled from deployment step --- .github/workflows/assemble-website.yml | 63 +++++++++++++++++++ .github/workflows/compile-home-docs.yml | 3 + .github/workflows/deploy-to-gh-pages.yml | 63 ++++--------------- .../fetch-and-compile-runtime-docs.yml | 1 - .../fetch-and-compile-workflow-docs.yml | 1 - 5 files changed, 78 insertions(+), 53 deletions(-) create mode 100644 .github/workflows/assemble-website.yml diff --git a/.github/workflows/assemble-website.yml b/.github/workflows/assemble-website.yml new file mode 100644 index 0000000..eb19a54 --- /dev/null +++ b/.github/workflows/assemble-website.yml @@ -0,0 +1,63 @@ +# This GitHub Actions workflow creates a file tree consisting of several smaller file trees and a few additional files. +# Reference: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions +name: Assemble website + +on: + workflow_dispatch: { } + # Allow this workflow to be called by other workflows. + # Reference: https://docs.github.com/en/actions/using-workflows/reusing-workflows + workflow_call: { } + +jobs: + # Use existing workflows to compile the home, Runtime, and workflow documentation. + # Reference: https://docs.github.com/en/actions/using-workflows/reusing-workflows#calling-a-reusable-workflow + compile-home-docs: + name: Compile home docs + uses: ./.github/workflows/compile-home-docs.yml + fetch-and-compile-runtime-docs: + name: Fetch and compile Runtime docs + uses: ./.github/workflows/fetch-and-compile-runtime-docs.yml + fetch-and-compile-workflow-docs: + name: Fetch and compile workflow docs + uses: ./.github/workflows/fetch-and-compile-workflow-docs.yml + + assemble: + name: Assemble website file tree + # This job depends upon other jobs succeeding. + # Reference: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds + needs: + - compile-home-docs + - fetch-and-compile-runtime-docs + - fetch-and-compile-workflow-docs + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - name: Check out commit # Docs: https://github.com/actions/checkout + uses: actions/checkout@v4 + - name: Download all artifacts + uses: actions/download-artifact@v4 # Docs: https://github.com/actions/download-artifact + with: { path: artifacts } + # Note: We use the `-T` option of the `cp` command so that the source directory name does not + # get appended to the destination directory name. It's short for `--no-target-directory`. + # Reference: https://www.gnu.org/software/coreutils/manual/html_node/Target-directory.html + - name: Assemble website file tree + run: | + mkdir -p \ + _build/html/runtime \ + _build/html/workflows + cp -R -T artifacts/home-docs-as-html _build/html + cp -R -T artifacts/runtime-docs-as-html _build/html/runtime + cp -R -T artifacts/workflow-docs-as-html _build/html/workflows + - name: Inject robots.txt file into assembled website file tree + run: | + cp content/robots.txt _build/html/robots.txt + ls -R _build/html + - name: Save the result for publishing to GitHub Pages # Docs: https://github.com/actions/upload-pages-artifact + uses: actions/upload-pages-artifact@v3 + with: + path: _build/html + # Note: The artifact name is "github-pages" by default; so, this specification is redundant. We include it + # anyway, here, as a reminder for people that will be implementing workflows that consume the same + # artifact; e.g., spell checkers and link checkers. + name: github-pages diff --git a/.github/workflows/compile-home-docs.yml b/.github/workflows/compile-home-docs.yml index 7e73878..65ed5f0 100644 --- a/.github/workflows/compile-home-docs.yml +++ b/.github/workflows/compile-home-docs.yml @@ -4,6 +4,9 @@ name: Compile home documentation into HTML on: push: { branches: [ main ] } + # Run this workflow whenever someone opens or adds commits to a PR whose base branch is `main`. + # Reference: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request + pull_request: { branches: [main] } workflow_dispatch: { } # Allow this workflow to be called by other workflows. # Reference: https://docs.github.com/en/actions/using-workflows/reusing-workflows diff --git a/.github/workflows/deploy-to-gh-pages.yml b/.github/workflows/deploy-to-gh-pages.yml index 318223e..841ccb3 100644 --- a/.github/workflows/deploy-to-gh-pages.yml +++ b/.github/workflows/deploy-to-gh-pages.yml @@ -1,6 +1,6 @@ -# This GitHub Actions workflow creates a production build of the website and deploys it to GitHub Pages. +# This GitHub Actions workflow deploys the website file tree to GitHub Pages. # Reference: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions -name: Build and deploy to GitHub Pages +name: Deploy to GitHub Pages on: push: { branches: [ main ] } @@ -12,60 +12,16 @@ concurrency: cancel-in-progress: true jobs: - # Use existing workflows to compile the home, Runtime, and workflow documentation. + # Use an existing workflow to assemble the website file tree that, in this workflow, we will deploy to GitHub Pages. # Reference: https://docs.github.com/en/actions/using-workflows/reusing-workflows#calling-a-reusable-workflow - compile-home-docs: - name: Compile home docs - uses: ./.github/workflows/compile-home-docs.yml - fetch-and-compile-runtime-docs: - name: Fetch and compile Runtime docs - uses: ./.github/workflows/fetch-and-compile-runtime-docs.yml - fetch-and-compile-workflow-docs: - name: Fetch and compile workflow docs - uses: ./.github/workflows/fetch-and-compile-workflow-docs.yml - - build: - name: Compile main website - # This job depends upon other jobs succeeding. - # Reference: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds - needs: - - compile-home-docs - - fetch-and-compile-runtime-docs - - fetch-and-compile-workflow-docs - runs-on: ubuntu-latest - permissions: - contents: read - steps: - - name: Check out commit # Docs: https://github.com/actions/checkout - uses: actions/checkout@v4 - - name: Download all artifacts - uses: actions/download-artifact@v4 # Docs: https://github.com/actions/download-artifact - with: - path: artifacts - # Note: We use the `-T` option of the `cp` command so that the source directory name does not - # get appended to the destination directory name. It's short for `--no-target-directory`. - # Reference: https://www.gnu.org/software/coreutils/manual/html_node/Target-directory.html - - name: Assemble website file tree - run: | - mkdir -p \ - _build/html/runtime \ - _build/html/workflows - cp -R -T artifacts/home-docs-as-html _build/html - cp -R -T artifacts/runtime-docs-as-html _build/html/runtime - cp -R -T artifacts/workflow-docs-as-html _build/html/workflows - - name: Inject robots.txt file into assembled website file tree - run: | - cp content/robots.txt _build/html/robots.txt - ls -R _build/html - - name: Save the result for publishing to GitHub Pages # Docs: https://github.com/actions/upload-pages-artifact - uses: actions/upload-pages-artifact@v3 - with: - path: _build/html + assemble-website: + name: Assemble website + uses: ./.github/workflows/assemble-website.yml deploy: name: Deploy website needs: - - build + - assemble-website runs-on: ubuntu-latest # Reference: https://github.com/actions/deploy-pages permissions: @@ -79,3 +35,8 @@ jobs: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 + with: + # Note: The artifact name is "github-pages" by default; so, this specification is redundant. We include it + # anyway, here, as a reminder for people that will be implementing workflows that consume the same + # artifact; e.g., spell checkers and link checkers. + artifact_name: github-pages diff --git a/.github/workflows/fetch-and-compile-runtime-docs.yml b/.github/workflows/fetch-and-compile-runtime-docs.yml index 8e8887b..a7f57a3 100644 --- a/.github/workflows/fetch-and-compile-runtime-docs.yml +++ b/.github/workflows/fetch-and-compile-runtime-docs.yml @@ -1,7 +1,6 @@ name: Fetch and compile Runtime docs on: - push: { branches: [ main ] } workflow_dispatch: { } # Allow this workflow to be called by other workflows. # Reference: https://docs.github.com/en/actions/using-workflows/reusing-workflows diff --git a/.github/workflows/fetch-and-compile-workflow-docs.yml b/.github/workflows/fetch-and-compile-workflow-docs.yml index aa87e1b..204b52a 100644 --- a/.github/workflows/fetch-and-compile-workflow-docs.yml +++ b/.github/workflows/fetch-and-compile-workflow-docs.yml @@ -1,7 +1,6 @@ name: Fetch and compile workflow docs on: - push: { branches: [ main ] } workflow_dispatch: { } # Allow this workflow to be called by other workflows. # Reference: https://docs.github.com/en/actions/using-workflows/reusing-workflows