From 5ca672fe8b7c36527bd65273aad40cbac82bf1ea Mon Sep 17 00:00:00 2001 From: Noel Miller Date: Tue, 8 Oct 2024 16:19:56 -0500 Subject: [PATCH 1/6] create build.yml --- .github/workflows/build.yml | 88 +++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 .github/workflows/build.yml diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 000000000..d80d090ba --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,88 @@ +name: Build Pelican Site +on: + workflow_call: + inputs: + settings: + required: true + description: "The path to your Pelican settings file (`pelican`'s `--settings` option), for example: 'publishconf.py'" + type: string + requirements: + required: false + default: "pelican" + description: "The Python requirements to install, for example to enable markdown and typogrify use: 'pelican[markdown] typogrify' or if you have a requirements file use: '-r requirements.txt'" + type: string + output-path: + required: false + default: "output/" + description: "Where to output the generated files (`pelican`'s `--output` option)" + type: string + theme: + required: false + default: "" + description: "The GitHub repo URL of a custom theme to use, for example: 'https://github.com/seanh/sidecar.git'" + type: string + python: + required: false + default: "3.12" + description: "The version of Python to use, for example: '3.12' (to use the most recent version of Python 3.12, this is faster) or '3.12.1' (to use an exact version, slower)" + type: string + siteurl: + required: false + default: "" + description: "The base URL of your web site (Pelican's SITEURL setting). If not passed this will default to the URL of your GitHub Pages site, which is correct in most cases." + type: string + feed_domain: + required: false + default: "" + description: "The domain to be prepended to feed URLs (Pelican's FEED_DOMAIN setting). If not passed this will default to the URL of your GitHub Pages site, which is correct in most cases." + type: string +permissions: + contents: read + pages: write + id-token: write +concurrency: + group: "build" + cancel-in-progress: false +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: ${{ inputs.python }} + - name: Checkout theme + if: ${{ inputs.theme }} + run: git clone '${{ inputs.theme }}' .theme + - name: Configure GitHub Pages + id: pages + uses: actions/configure-pages@v5 + - name: Install requirements + run: pip install ${{ inputs.requirements }} + - name: Build Pelican site + shell: python + run: | + import subprocess + + cmd = "pelican" + cmd += " --settings ${{ inputs.settings }}" + cmd += " --extra-settings" + cmd += """ SITEURL='"${{ inputs.siteurl || steps.pages.outputs.base_url }}"'""" + cmd += """ FEED_DOMAIN='"${{ inputs.feed_domain || steps.pages.outputs.base_url }}"'""" + cmd += " --output ${{ inputs.output-path }}" + + if "${{ inputs.theme }}": + cmd += " --theme-path .theme" + + subprocess.run(cmd, shell=True, check=True) + - name: Fix permissions + run: | + chmod -c -R +rX "${{ inputs.output-path }}" | while read line; do + echo "::warning title=Invalid file permissions automatically fixed::$line" + done + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ${{ inputs.output-path }} From 403d50790bc6d1b7250094d268f4a616fa711c1b Mon Sep 17 00:00:00 2001 From: Noel Miller Date: Tue, 8 Oct 2024 16:20:38 -0500 Subject: [PATCH 2/6] update github_pages.yml --- .github/workflows/github_pages.yml | 50 ++++++------------------------ 1 file changed, 9 insertions(+), 41 deletions(-) diff --git a/.github/workflows/github_pages.yml b/.github/workflows/github_pages.yml index 48ebb2d0e..8bc87dd71 100644 --- a/.github/workflows/github_pages.yml +++ b/.github/workflows/github_pages.yml @@ -46,47 +46,15 @@ concurrency: cancel-in-progress: false jobs: build: - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - name: Set up Python - uses: actions/setup-python@v5 - with: - python-version: ${{ inputs.python }} - - name: Checkout theme - if: ${{ inputs.theme }} - run: git clone '${{ inputs.theme }}' .theme - - name: Configure GitHub Pages - id: pages - uses: actions/configure-pages@v5 - - name: Install requirements - run: pip install ${{ inputs.requirements }} - - name: Build Pelican site - shell: python - run: | - import subprocess - - cmd = "pelican" - cmd += " --settings ${{ inputs.settings }}" - cmd += " --extra-settings" - cmd += """ SITEURL='"${{ inputs.siteurl || steps.pages.outputs.base_url }}"'""" - cmd += """ FEED_DOMAIN='"${{ inputs.feed_domain || steps.pages.outputs.base_url }}"'""" - cmd += " --output ${{ inputs.output-path }}" - - if "${{ inputs.theme }}": - cmd += " --theme-path .theme" - - subprocess.run(cmd, shell=True, check=True) - - name: Fix permissions - run: | - chmod -c -R +rX "${{ inputs.output-path }}" | while read line; do - echo "::warning title=Invalid file permissions automatically fixed::$line" - done - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - with: - path: ${{ inputs.output-path }} + uses: "noelmiller/pelican/.github/workflows/build.yml@decouple_build_workflow" + with: + settings: ${{ inputs.settings }} + requirements: ${{ inputs.requirements }} + output-path: ${{ inputs.output-path }} + theme: ${{ inputs.theme }} + python: ${{ inputs.python }} + siteurl: ${{ inputs.siteurl }} + feed_domain: ${{ inputs.feed_domain }} deploy: environment: name: github-pages From 84e31ba2b11083f8e1c913ae381baae8ff52b032 Mon Sep 17 00:00:00 2001 From: Noel Miller Date: Tue, 8 Oct 2024 16:28:15 -0500 Subject: [PATCH 3/6] prepped for getpelican org --- .github/workflows/github_pages.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/github_pages.yml b/.github/workflows/github_pages.yml index 8bc87dd71..f403b9f54 100644 --- a/.github/workflows/github_pages.yml +++ b/.github/workflows/github_pages.yml @@ -46,7 +46,7 @@ concurrency: cancel-in-progress: false jobs: build: - uses: "noelmiller/pelican/.github/workflows/build.yml@decouple_build_workflow" + uses: "getpelican/pelican/.github/workflows/build.yml@main" with: settings: ${{ inputs.settings }} requirements: ${{ inputs.requirements }} From f9a0d9e56bedb8d42f312e01f2d73efaa8f160c5 Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Mon, 14 Oct 2024 17:20:25 +0100 Subject: [PATCH 4/6] Combine `build.yml` and `github_pages.yml` Combine `build.yml` and `github_pages.yml` into a single workflow file. Having `build.yml` be a separate workflow file that `github_pages.yml` calls has two problems: 1. All the inputs (and their types, descriptions, defaults) have to be duplicated in the two workflow files. 2. The reference to `@main` in `uses: "getpelican/pelican/.github/workflows/build.yml@main"` in the `github_pages.yml` workflow makes development and testing awkward. For example let's say you want to send a pull request that contains changes to `build.yml` and that also requires changes to `github_pages.yml` at the same time. The problem is that the `github_pages.yml` on your PR branch will still contain the reference to `build.yml` `@main` so if you try to test the branch's version of `github_pages.yml` it'll call the version of `build.yml` from `main` not from the PR branch and will fail. This commit move the build job from `build.yml` into `github_pages.yml` but makes the deploy job optional: it adds a `deploy` input and will only run the deploy job if `deploy = true` is passed. Previously a user could test their build without deploying it by calling the separate `build.yml` workflow. Now they can do it by calling the `github_pages.yml` workflow and passing `deploy=false`. This commit also moves the `concurrency` stuff from the workflow level to the deploy level: it's okay to have multiple build jobs running concurrently, just not multiple deploy jobs. --- .github/workflows/build.yml | 88 ------------------------------ .github/workflows/github_pages.yml | 64 +++++++++++++++++----- 2 files changed, 51 insertions(+), 101 deletions(-) delete mode 100644 .github/workflows/build.yml diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml deleted file mode 100644 index d80d090ba..000000000 --- a/.github/workflows/build.yml +++ /dev/null @@ -1,88 +0,0 @@ -name: Build Pelican Site -on: - workflow_call: - inputs: - settings: - required: true - description: "The path to your Pelican settings file (`pelican`'s `--settings` option), for example: 'publishconf.py'" - type: string - requirements: - required: false - default: "pelican" - description: "The Python requirements to install, for example to enable markdown and typogrify use: 'pelican[markdown] typogrify' or if you have a requirements file use: '-r requirements.txt'" - type: string - output-path: - required: false - default: "output/" - description: "Where to output the generated files (`pelican`'s `--output` option)" - type: string - theme: - required: false - default: "" - description: "The GitHub repo URL of a custom theme to use, for example: 'https://github.com/seanh/sidecar.git'" - type: string - python: - required: false - default: "3.12" - description: "The version of Python to use, for example: '3.12' (to use the most recent version of Python 3.12, this is faster) or '3.12.1' (to use an exact version, slower)" - type: string - siteurl: - required: false - default: "" - description: "The base URL of your web site (Pelican's SITEURL setting). If not passed this will default to the URL of your GitHub Pages site, which is correct in most cases." - type: string - feed_domain: - required: false - default: "" - description: "The domain to be prepended to feed URLs (Pelican's FEED_DOMAIN setting). If not passed this will default to the URL of your GitHub Pages site, which is correct in most cases." - type: string -permissions: - contents: read - pages: write - id-token: write -concurrency: - group: "build" - cancel-in-progress: false -jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - name: Set up Python - uses: actions/setup-python@v5 - with: - python-version: ${{ inputs.python }} - - name: Checkout theme - if: ${{ inputs.theme }} - run: git clone '${{ inputs.theme }}' .theme - - name: Configure GitHub Pages - id: pages - uses: actions/configure-pages@v5 - - name: Install requirements - run: pip install ${{ inputs.requirements }} - - name: Build Pelican site - shell: python - run: | - import subprocess - - cmd = "pelican" - cmd += " --settings ${{ inputs.settings }}" - cmd += " --extra-settings" - cmd += """ SITEURL='"${{ inputs.siteurl || steps.pages.outputs.base_url }}"'""" - cmd += """ FEED_DOMAIN='"${{ inputs.feed_domain || steps.pages.outputs.base_url }}"'""" - cmd += " --output ${{ inputs.output-path }}" - - if "${{ inputs.theme }}": - cmd += " --theme-path .theme" - - subprocess.run(cmd, shell=True, check=True) - - name: Fix permissions - run: | - chmod -c -R +rX "${{ inputs.output-path }}" | while read line; do - echo "::warning title=Invalid file permissions automatically fixed::$line" - done - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - with: - path: ${{ inputs.output-path }} diff --git a/.github/workflows/github_pages.yml b/.github/workflows/github_pages.yml index f403b9f54..9c279ab14 100644 --- a/.github/workflows/github_pages.yml +++ b/.github/workflows/github_pages.yml @@ -1,4 +1,4 @@ -# Workflow for publishing to GitHub Pages. +# Workflow for building the site and (optionally) publishing it to GitHub Pages. name: Deploy to GitHub Pages on: workflow_call: @@ -37,25 +37,63 @@ on: default: "" description: "The domain to be prepended to feed URLs (Pelican's FEED_DOMAIN setting). If not passed this will default to the URL of your GitHub Pages site, which is correct in most cases." type: string + deploy: + required: false + default: true + description: "Whether to deploy the site. If true then build the site and deploy it. If false then just test that the site builds successfully but don't deploy anything." + type: boolean permissions: contents: read pages: write id-token: write -concurrency: - group: "pages" - cancel-in-progress: false jobs: build: - uses: "getpelican/pelican/.github/workflows/build.yml@main" - with: - settings: ${{ inputs.settings }} - requirements: ${{ inputs.requirements }} - output-path: ${{ inputs.output-path }} - theme: ${{ inputs.theme }} - python: ${{ inputs.python }} - siteurl: ${{ inputs.siteurl }} - feed_domain: ${{ inputs.feed_domain }} + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: ${{ inputs.python }} + - name: Checkout theme + if: ${{ inputs.theme }} + run: git clone '${{ inputs.theme }}' .theme + - name: Configure GitHub Pages + id: pages + uses: actions/configure-pages@v5 + - name: Install requirements + run: pip install ${{ inputs.requirements }} + - name: Build Pelican site + shell: python + run: | + import subprocess + + cmd = "pelican" + cmd += " --settings ${{ inputs.settings }}" + cmd += " --extra-settings" + cmd += """ SITEURL='"${{ inputs.siteurl || steps.pages.outputs.base_url }}"'""" + cmd += """ FEED_DOMAIN='"${{ inputs.feed_domain || steps.pages.outputs.base_url }}"'""" + cmd += " --output ${{ inputs.output-path }}" + + if "${{ inputs.theme }}": + cmd += " --theme-path .theme" + + subprocess.run(cmd, shell=True, check=True) + - name: Fix permissions + run: | + chmod -c -R +rX "${{ inputs.output-path }}" | while read line; do + echo "::warning title=Invalid file permissions automatically fixed::$line" + done + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ${{ inputs.output-path }} deploy: + concurrency: + group: "pages" + cancel-in-progress: false + if: ${{ inputs.deploy }} environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} From fdbf97a3c0d9b63c9f2472f9808b8cbbe25fc139 Mon Sep 17 00:00:00 2001 From: Noel Miller Date: Fri, 18 Oct 2024 16:28:30 -0500 Subject: [PATCH 5/6] update tips to include deploy input --- docs/tips.rst | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/docs/tips.rst b/docs/tips.rst index e5574c7ca..7a700b65b 100644 --- a/docs/tips.rst +++ b/docs/tips.rst @@ -246,7 +246,52 @@ Here's the complete list of workflow inputs: | | | your GitHub Pages site, which is correct | | | | | | in most cases. | | | +------------------+----------+--------------------------------------------+--------+---------------+ +| ``deploy`` | No | This is used to determine whether you will | bool | ``true`` | +| | | deploy the site or not to GitHub Pages. | | | +| | | This is most useful if you want to test a | | | +| | | change to your website in a pull request | | | +| | | before deploying those change. | | | ++------------------+----------+--------------------------------------------+--------+---------------+ + +Testing your build in a GitHub Pull Request +""""""""""""""""""""""""""""""""""""""""""" + +If you want to test your build in a pull request before deploying to GitHub, your workflow might look something like this: + +.. code-block:: yaml + name: Build and Deploy Site + on: + push: + branches: ["main"] + pull_request: + branches: ["main"] + workflow_dispatch: + inputs: + deploy: + required: false + default: true + description: "Whether to deploy the site. If checked then build the site and deploy it. If not checked then just test that the site builds successfully but don't deploy anything." + type: boolean + jobs: + deploy: + uses: "getpelican/pelican/.github/workflows/github_pages.yml@main" + permissions: + id-token: write + contents: read + pages: write + with: + settings: "publishconf.py" + requirements: "-r requirements.txt" + deploy: ${{ (github.event_name == 'workflow_dispatch' && inputs.deploy == true) || (github.event_name == 'push' && github.ref_type == 'branch' && github.ref_name == github.event.repository.default_branch) }} + +The ``on`` section of the workflow defines the events that will trigger the workflow. In this example, the workflow will run on pushes to the main branch, pull requests to the main branch, and manual runs of the workflow. + +``workflow_dispatch`` defines the deploy boolean to be true by default. This means that if you run the workflow manually, it will deploy the site. + +The ``deploy`` input for the job is using a set of standard github workflow variables to control when deploy will either be true or false (you can customize this to your needs). + +In this example, the deploy will be true if the event is a push to the main branch (or merging into main from a PR) or a manual run of the workflow. If the event is a pull request, the deploy will be false and it will only build an artifact for the site. "Insecure content" warnings from browsers """"""""""""""""""""""""""""""""""""""""" From f033bacfb1b7a1cb9412be9039e1ec3b03aefa32 Mon Sep 17 00:00:00 2001 From: Noel Miller Date: Fri, 18 Oct 2024 18:46:51 -0500 Subject: [PATCH 6/6] minor edits with requested changes --- docs/tips.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/tips.rst b/docs/tips.rst index 7a700b65b..4df20ae3b 100644 --- a/docs/tips.rst +++ b/docs/tips.rst @@ -253,7 +253,7 @@ Here's the complete list of workflow inputs: | | | before deploying those change. | | | +------------------+----------+--------------------------------------------+--------+---------------+ -Testing your build in a GitHub Pull Request +Testing Your Build in a GitHub Pull Request """"""""""""""""""""""""""""""""""""""""""" If you want to test your build in a pull request before deploying to GitHub, your workflow might look something like this: @@ -271,7 +271,7 @@ If you want to test your build in a pull request before deploying to GitHub, you deploy: required: false default: true - description: "Whether to deploy the site. If checked then build the site and deploy it. If not checked then just test that the site builds successfully but don't deploy anything." + description: "Whether to deploy the site. If checked, then build the site and deploy it. If not checked, then just test that the site builds successfully but don't deploy anything." type: boolean jobs: deploy: @@ -289,9 +289,9 @@ The ``on`` section of the workflow defines the events that will trigger the work ``workflow_dispatch`` defines the deploy boolean to be true by default. This means that if you run the workflow manually, it will deploy the site. -The ``deploy`` input for the job is using a set of standard github workflow variables to control when deploy will either be true or false (you can customize this to your needs). +The ``deploy`` input for the job is using a set of standard GitHub workflow variables to control when ``deploy`` will either be true or false (you can customize this to your needs). -In this example, the deploy will be true if the event is a push to the main branch (or merging into main from a PR) or a manual run of the workflow. If the event is a pull request, the deploy will be false and it will only build an artifact for the site. +In this example, the ``deploy`` will be true if the event is a push to the main branch (or merging into main from a PR) or a manual run of the workflow. If the event is a pull request, the ``deploy`` will be false and it will only build an artifact for the site. "Insecure content" warnings from browsers """""""""""""""""""""""""""""""""""""""""