diff --git a/source/Development/testing.rst b/source/Development/testing.rst index 791fd963..2367a786 100644 --- a/source/Development/testing.rst +++ b/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 ` 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 diff --git a/source/WorkingPractices/gh_authorisation.rst b/source/WorkingPractices/gh_authorisation.rst index 88907cd7..5ba92524 100644 --- a/source/WorkingPractices/gh_authorisation.rst +++ b/source/WorkingPractices/gh_authorisation.rst @@ -69,7 +69,9 @@ 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 `). Access + from Monsoon will require using a PAT. You will require a way of `authenticating with github from git `_. @@ -77,8 +79,9 @@ One way to do this is via ssh keys. For creating and adding a new ssh key to github, `see the github documentation `_. 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 `_. @@ -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 +`_. +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 +`_. + +.. 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://:@github.com" >> ~/.git-credentials + +To use you token to authenticate with github when running the `:ref:rose-stem +suite `, include the command line option ``-S USE_TOKENS=true``. +For Monsoon users, this option is automatically enabled.