Add example GitHub workflow for automated update PRs (#167)

* Add GitHub workflow for automated update PRs

* Add docs

* Revert auto-formatting of block titles

.github-upgrade-check.yml.sample

@@ -0,0 +1,68 @@
+# This workflow compares a downstream azimuth-config repository for a specific site with the upstream
+# stackhpc/azimuth-config repository to check whether there is a new upstream version available. If a
+# newer tag is found in the upstream repository then a pull request is created to the downstream repo
+# in order to merge in the changes from the new upstream release.
+
+# To use this workflow in a downstream azimuth-config repository simply copy it into .github/workflows
+# and give it an appropriate name, e.g.
+# cp .github-upgrade-check.yml.sample .github/workflows/upgrade-check.yml
+
+name: Check for upstream updates
+on:
+  schedule:
+    - cron: "0 9 * * *"
+  workflow_dispatch:
+jobs:
+  check_for_update:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+
+      - name: Checkout the config repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      # Based on equivalent GitLab CI job
+      - name: Check for new release
+        shell: bash
+        run: |
+          set -xe
+
+          # Install dependency
+          apt update && apt install -y git-crypt
+
+          # Tell git who we are for commits
+          git config user.email "${{ github.actor }}-ci@azimuth.ci"
+          git config user.name "${{ github.actor }} CI"
+
+          # Create the merge branch and write vars to .mergeenv file
+          ./bin/create-merge-branch
+
+      - name: Set release tag output
+        id: release_tag
+        if: ${{ hashFiles('.mergeenv') }}
+        run: source .mergeenv && echo value=$RELEASE_TAG >> $GITHUB_OUTPUT
+
+      - name: Set branch name output
+        id: branch_name
+        if: ${{ hashFiles('.mergeenv') }}
+        run: source .mergeenv && echo value=$BRANCH_NAME >> $GITHUB_OUTPUT
+
+      - name: Remove tmp file
+        run: rm .mergeenv
+        if: ${{ hashFiles('.mergeenv') }}
+
+      - name: Create Pull Request
+        if: ${{ steps.release_tag.outputs.value }}
+        uses: peter-evans/create-pull-request@v6
+        with:
+          base: main
+          branch: ${{ steps.branch_name.outputs.value }}
+          title: "Upgrade Azimuth to ${{ steps.release_tag.outputs.value }}"
+          body: This PR was automatically generated by GitHub Actions.
+          commit-message: "Upgrade Azimuth to ${{ steps.release_tag.outputs.value }}"
+          delete-branch: true

bin/create-merge-branch

@@ -51,21 +51,26 @@ if [ -n "$(git status --short)" ]; then
   echo "[INFO] Merge resulted in the following changes"
   git status
 
-  echo "[INFO] Checking out temporary branch '$BRANCH_NAME'..."
-  git checkout -b "$BRANCH_NAME"
-
-  echo "[INFO] Committing changes"
-  git commit -m "Upgrade Azimuth to $RELEASE_TAG"
-
-  echo "[INFO] Pushing changes to origin"
-  git push --set-upstream origin "$BRANCH_NAME"
-
-  # Go back to the main branch at the end
-  echo "[INFO] Reverting back to main"
-  git checkout main
-
-  echo "[INFO] Removing temporary branch"
-  git branch -d "$BRANCH_NAME"
+  # NOTE(scott): The GitHub create-pull-request action does
+  # the commiting for us, so we only need to make branches
+  # and commits if running outside of GitHub actions.
+  if [ ! $GITHUB_ACTIONS ]; then
+    echo "[INFO] Checking out temporary branch '$BRANCH_NAME'..."
+    git checkout -b "$BRANCH_NAME"
+
+    echo "[INFO] Committing changes"
+    git commit -m "Upgrade Azimuth to $RELEASE_TAG"
+
+    echo "[INFO] Pushing changes to origin"
+    git push --set-upstream origin "$BRANCH_NAME"
+
+    # Go back to the main branch at the end
+    echo "[INFO] Reverting back to main"
+    git checkout main
+
+    echo "[INFO] Removing temporary branch"
+    git branch -d "$BRANCH_NAME"
+  fi
 
   # Write a file containing the branch name and tag
   # for automatic PR or MR creation that follows

docs/deployment/automation.md

@@ -60,23 +60,23 @@ environment in your repository. This is a one-to-one relationship except for
 [per-branch dynamic review environments](#per-branch-dynamic-review-environments),
 where multiple GitLab environments will use a single configuration environment.
 
-If you are using GitLab-managed Terraform state, each *GitLab environment* (not
+If you are using GitLab-managed Terraform state, each _GitLab environment_ (not
 configuration environment) will get it's own independent state.
 
 The sample configuration defines the following deployment jobs:
 
-  1. Each commit to a branch other than `main` (e.g. a feature branch), triggers an
-     automated deployment to a **branch-specific**
-     [dynamic GitLab environment](https://docs.gitlab.com/ee/ci/environments/#create-a-dynamic-environment),
-     using a single [concrete configuration environment](../environments.md). These
-     environments are automatically destroyed when the associated merge request is
-     closed.
-  2. Each commit to `main` triggers an automated deployment to staging using a
-     [static GitLab environment](https://docs.gitlab.com/ee/ci/environments/#create-a-static-environment).
-  3. Each commit to `main` also creates a job for an automated deployment to
-     production, also using a static environment. However this job requires a
-     [manual trigger](https://docs.gitlab.com/ee/ci/environments/#configure-manual-deployments)
-     before it will start.
+1. Each commit to a branch other than `main` (e.g. a feature branch), triggers an
+   automated deployment to a **branch-specific**
+   [dynamic GitLab environment](https://docs.gitlab.com/ee/ci/environments/#create-a-dynamic-environment),
+   using a single [concrete configuration environment](../environments.md). These
+   environments are automatically destroyed when the associated merge request is
+   closed.
+2. Each commit to `main` triggers an automated deployment to staging using a
+   [static GitLab environment](https://docs.gitlab.com/ee/ci/environments/#create-a-static-environment).
+3. Each commit to `main` also creates a job for an automated deployment to
+   production, also using a static environment. However this job requires a
+   [manual trigger](https://docs.gitlab.com/ee/ci/environments/#configure-manual-deployments)
+   before it will start.
 
 To get started, just copy `.gitlab-ci.yml.sample` to `.gitlab-ci.yml` and amend
 the environment names and paths to match the environments in your configuration.
@@ -212,7 +212,6 @@ Unfortunately, this is a paid feature and the only real alternative is to use a
     separate service account that only belongs to your configuration project and
     issue a personal access token from that account instead.
 
-
 ## GitHub CI/CD
 
 For site-specific configuration repositories hosted on GitHub, `azimuth-config` provides two sample workflows
@@ -222,4 +221,9 @@ and manually-triggered deployment to a production environment
 ([example workflow](https://github.com/azimuth-cloud/azimuth-config/blob/stable/.github-deploy-prod.yml.sample)).
 These can be used with [GitHub Actions](https://docs.github.com/en/actions) to mimic some of the GitLab
 functionality described above. Each sample file contains a top-level comment describing how to tailor these
-workflows to a site-specific configuration repository.
+workflows to a site-specific configuration repository.
+
+An additional [upgrade-check](https://github.com/stackhpc/azimuth-config/blob/stable/.github-upgrade-check.yml.sample)
+workflow is included which will regularly check for new upstream azimuth-config releases and automatically create a
+pull request in the downstream azimuth-config repository when a new upstream version is available. See the comment
+at the top of the sample workflow file for more details.