From e03023dbf85d3e09fc4f3ebf4c345883d5373101 Mon Sep 17 00:00:00 2001
From: Andrew Sazonov <andrew.sazonov@icloud.com>
Date: Wed, 29 Jan 2025 16:18:42 +0100
Subject: [PATCH] Update workflow for site build and deployment

---
 .github/workflows/build-page.yml | 107 +++++++++++++++++++++++++++----
 1 file changed, 93 insertions(+), 14 deletions(-)

diff --git a/.github/workflows/build-page.yml b/.github/workflows/build-page.yml
index bcef1f0..1cd16b8 100644
--- a/.github/workflows/build-page.yml
+++ b/.github/workflows/build-page.yml
@@ -1,9 +1,27 @@
-name: build site
+name: Build and deploy static site
 
-on: push
+on:
+  # Trigger the workflow on push
+  push:
+    # Every branch
+    branches:
+      - "**"
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+env:
+  # Set the environment variables to be used in all jobs defined in this workflow
+  # Set the CI_BRANCH environment variable to be the branch name
+  # NOTE: Use the same branch name as the one of EasyDiffractionLib. This is
+  # required to download the Jupyter notebooks from the EasyDiffractionLib repository
+  CI_BRANCH: ${{ github.head_ref || github.ref_name }}
+  REPOSITORY_NAME: diffraction
+  PROJECT_EMAIL: support@easydiffraction.org
 
 jobs:
-  build:
+
+  # Job 1: Build the static files for the documentation site
+  build-page:
     runs-on: ubuntu-24.04
 
     steps:
@@ -15,15 +33,7 @@ jobs:
       - name: Check-out repository
         uses: actions/checkout@v4
 
-      - name: Declare env variables on push only
-        if: github.event_name == 'push'
-        shell: bash
-        run: |
-          echo "BRANCH_NAME=${GITHUB_REF#refs/*/}" >> $GITHUB_ENV
-          echo "REPOSITORY_NAME=diffraction" >> $GITHUB_ENV
-          echo "PROJECT_EMAIL=support@easydiffraction.org" >> $GITHUB_ENV
-
-      - name: Download dependences
+      - name: Download dependencies
         working-directory: ..
         run: git clone ${GITHUB_SERVER_URL}/EasyScience/EasySite
 
@@ -50,10 +60,79 @@ jobs:
       - name: Copy built site to default working directory
         run: cp -R ../EasySite/public .
 
-      - name: Deploy built site to 'public_...' branch
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      # Upload the static files from the public/ directory to be used in the next job
+      # This artifact is named github-pages and is a single gzip archive containing a single tar file
+      # The artifact is then used in the next job by actions/deploy-pages to deploy the static files to GitHub Pages
+      # Unfortunately, the artifact is not available for download, so extra steps below are needed to do similar things
+      - name: Upload built site as artifact (for github-pages, all branches)
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: public/
+
+      # Upload the static files from the site/ directory to be used in the next job
+      # This extra step is needed to allow the download of the artifact in the next job
+      # for pushing its content to the branch named 'easydiffraction.org'
+      - name: Upload built site as artifact (for easydiffraction.org, master branch only)
+        if: ${{ env.CI_BRANCH == 'master' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: artifact # name of the artifact (without the extension zip)
+          path: public/
+          if-no-files-found: "error"
+          compression-level: 0
+
+  # Job 2: Deploy the static files
+  # To allow the deployment of the static files to GitHub Pages
+  # No restrictions on the branch name is set on https://github.com/EasyScience/diffraction/settings/environments
+  deploy-docs:
+    needs: build-page  # previous job 'build-page' need to be finished first
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      contents: read
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment, originates from an appropriate source
+
+    # 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:
+      group: "pages"
+      cancel-in-progress: false
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages # Artifact name
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+
+    steps:
+      # Deploy the static files created in the previous job to GitHub Pages
+      # All branches are deployed to GitHub Pages and available at
+      # https://easyscience.github.io/EasyDiffractionLibDocs
+      # This is needed for debugging purposes
+      - name: Deploy to easyscience.github.io/diffraction (all branches)
+        uses: actions/deploy-pages@v4
+
+      - name: Download built site as artifact from previous job (for easydiffraction.org, master branch only)
+        if: ${{ env.CI_BRANCH == 'master' }}
+        uses: actions/download-artifact@v4
+        with:  # name or path are taken from the upload step of the previous job
+          name: artifact
+          path: public/ # directory to extract downloaded zipped artifacts
+
+      # Push the site files created in the previous job to the 'easydiffraction.org' branch
+      # This branch is used to deploy the site to the custom domain https://easydiffraction.org
+      # Deploying is done with a webhook: https://github.com/EasyScience/EasyDiffractionLibDocs/settings/hooks
+      # This is done for the 'master' branch only, when the site is tested with a step above
+      - name: Deploy to easydiffraction.org (master branch)
+        if: ${{ env.CI_BRANCH == 'master' }}
         uses: s0/git-publish-subdir-action@develop
         env:
           GITHUB_TOKEN: ${{ secrets.API_TOKEN_GITHUB }}
           REPO: self
-          BRANCH: public_${{ env.BRANCH_NAME }}
+          BRANCH: easydiffraction.org
           FOLDER: public