update documentation

Author: bertiethorpe

.github/workflows/upgrade-check.yml.sample

@@ -2,10 +2,26 @@
 # stackhpc/ansible-slurm-appliance 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 ansible-slurm-appliance repository simply copy it into .github/workflows
 # and give it an appropriate name, e.g.
 # cp .github/workflows/upgrade-check.yml.sample .github/workflows/upgrade-check.yml
+#
+# Workflow uses https://github.com/peter-evans/create-pull-request to handle the pull request action. 
+# See the docs for action inputs.
+#
+# In order for GitHub actions to create pull requests that make changes to workflows in `.github/workflows`, 
+# a token for each deployment must be provided. Both user PAT and fine-grained tokens should work, but it was tested
+# with a PAT. Fine-grained repo-scoped token is preferred if possible but requires organisation admin privileges.
+#
+# See https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
+# for security considerations around tokens. TREAT YOUR ACCESS TOKENS LIKE PASSWORDS.
+#
+# The following repository permissions must be set for the PAT:
+#  - `Workflows: Read and write`
+#  - `Actions: Read and write`
+#  - `Pull requests: Read and write`
+# The PAT should then be copied into an Actions repository secret in the downstream repo with the title `WORKFLOW_TOKEN`.
 
 name: Check for upstream updates
 on:
@@ -15,10 +31,6 @@ on:
 jobs:
   check_for_update:
     runs-on: ubuntu-22.04
-    # permissions:
-    #   contents: write
-    #   pull-requests: write
-    #   actions: write
 
     steps:
       - name: Checkout the config repo
@@ -27,7 +39,7 @@ jobs:
           fetch-depth: 0
           fetch-tags: true
 
-      # Based on equivalent GitLab CI job
+      # Based on equivalent azimuth-config job
       - name: Check for new release
         shell: bash
         run: |

README.md

@@ -147,19 +147,6 @@ Please see the [monitoring-and-logging.README.md](docs/monitoring-and-logging.RE
 
 ## CI/CD automation
 
-A GitHub Actions workflow which checks for new upstream version release tags and creates a PR to update the downstream repo, can be found at:
+The `.github` directory contains a set of sample workflows which can be used by downstream site-specific configuration repositories to simplify ongoing maintainence tasks. These include:
 
-        .github/workflows/upgrade-check.yml.sample
-
-If activated, the workflow is scheduled by default to run every day at 9 AM UTC and can be triggered manually via the `workflow_dispatch` event. How to activate the workflow is detailed at the top of the file.
-
-Workflow uses [create-pull-request](https://github.com/peter-evans/create-pull-request) to handle the pull request action. See for action inputs.
-
-In order for GitHub actions to fetch workflow changes in `.github/workflows`, a PAT for each deployment must be provided.
-
-The following repository permissions must be set for the PAT:
- - `Workflows: Read and write`
- - `Actions: Read and write`
- - `Pull requests: Read and write`
-
-The PAT should then be copied into an Actions repository secret in the downstream repo with the title `WORKFLOW_TOKEN`.
+- An [upgrade check](.github/workflows/upgrade-check.yml.sample) workflow which automatically checks this upstream stackhpc/ansible-slurm-appliance repo for new releases and proposes a pull request to the downstream site-specific repo when a new release is published.