github tokens

source/Development/testing.rst

@@ -51,6 +51,10 @@ mirrors and naming it ``my_rose_stem_suite``.
 ``-S`` Options (non-exhaustive):
 
 * ``-S USE_MIRRORS=true`` - Use local github mirrors instead of ssh.
+* ``-S USE_TOKENS=true`` - Authenticate with github using a :ref:`personal
+  access token <github_pat>` instead of ssh. If both this and ``USE_MIRRORS``
+  are true, then the mirrors will be used instead. On Monsoon, this is
+  automatically set.
 * ``-S USE_HEADS=true`` - Use the head of the default branch for the github
   source, only intended for usage in nightly testing.
 * ``-S USE_EX[AB/CD/Z]=true`` - MetOffice only, specify the host machine for

source/WorkingPractices/gh_authorisation.rst

@@ -69,16 +69,19 @@ SSH Key Setup
 
     If ssh isn't available (eg. shared accounts), then it is possible to use the
     option ``-S USE_MIRRORS=true`` which will use local git mirrors if available
-    (see :ref:`testing` for more details).
+    (see :ref:`testing` for more details) or ``-S USE_TOKENS=true`` which will
+    use a github Personal Access Token (see :ref:`below <github_pat>`). Access
+    from Monsoon will require using a PAT.
 
 You will require a way of `authenticating with github from git
 <https://docs.github.com/en/get-started/git-basics/set-up-git#authenticating-with-github-from-git>`_.
 One way to do this is via ssh keys. For creating and adding a new ssh key to
 github, `see the github documentation
 <https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent>`_.
 In order to use this ssh key with MetOffice organisations, it must be authorised
-for single sign on access. First, ensure you are part of the MetOffice
-organisation, and then `configure the SSH key for SSO
+If you are a member of the MetOffice GitHub organisation you will need to
+authorise the key for single sign on access. First, ensure you are part of the
+MetOffice organisation, and then `configure the SSH key for SSO
 <https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-single-sign-on/authorizing-an-ssh-key-for-use-with-single-sign-on>`_.
 
 
@@ -108,8 +111,8 @@ signing.
     sign each commit.
 
 
-gh command line
----------------
+gh Command Line Interface
+-------------------------
 
 .. tip::
 
@@ -123,3 +126,47 @@ repositories. Where appropriate we have given options for performing tasks with
 To authenticate, run ``gh auth login`` and follow the instructions which will
 involve logging into github via a web browser. See the gh manual (linked above)
 for details of authenticating.
+
+.. _github_pat:
+
+Github Personal Access Tokens
+-----------------------------
+
+Using GitHub tokens is optional for most test suites, as SSH authentication is
+used by default. However, Monsoon users must use GitHub tokens because SSH
+access to GitHub is unavailable from Monsoon.
+
+To use Personal Access Tokens (PATs), store them in a git credentials file,
+typically ``~/.git-credentials``. Restrict access to this file and configure
+git to use it:
+
+.. code-block:: shell
+
+    touch ~/.git-credentials
+    chmod 0600 ~/.git-credentials
+    git config --global credential.helper 'store --file ~/.git-credentials'
+
+Next, `create a Classic Token
+<https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic>`_.
+To read from or write to a repository, ensure your token has at least the
+``repo`` scope. For security reasons, avoid using tokens without an expiry
+date. If you are a member of the MetOffice GitHub organisation, authorise your
+token for use with the MetOffice Single Sign On. See the GitHub documentation
+for details: `Authorizing a personal access token for use with Single Sign-On
+<https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-single-sign-on/authorizing-a-personal-access-token-for-use-with-single-sign-on>`_.
+
+.. important::
+
+    Make sure to create a Classic Token, rather than a Fine Grained token, as
+    these are required for authenticating with the single sign on.
+
+Once created, be sure to copy the generated token as this will not be available
+again. Add the token to the git credentials file in the following format,
+
+.. code-block:: shell
+
+    echo "https://<gh-username>:<PAT>@github.com" >> ~/.git-credentials
+
+To use you token to authenticate with github when running the `:ref:rose-stem
+suite <github_testing>`, include the command line option ``-S USE_TOKENS=true``.
+For Monsoon users, this option is automatically enabled.