From df234723bec7964f77df914a9d7a40efa4d4dbe3 Mon Sep 17 00:00:00 2001 From: James Bruten Date: Wed, 22 Oct 2025 15:19:49 +0100 Subject: [PATCH 1/7] pat instructions --- source/Development/testing.rst | 3 ++ source/WorkingPractices/gh_authorisation.rst | 51 ++++++++++++++++++-- 2 files changed, 51 insertions(+), 3 deletions(-) diff --git a/source/Development/testing.rst b/source/Development/testing.rst index 791fd963..a3f887dc 100644 --- a/source/Development/testing.rst +++ b/source/Development/testing.rst @@ -51,6 +51,9 @@ 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. * ``-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..59b46820 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 `_. @@ -108,8 +110,8 @@ signing. sign each commit. -gh command line ---------------- +gh Command Line Interface +------------------------- .. tip:: @@ -123,3 +125,46 @@ 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 generally optional, as the test suites will by default +attempt to verify using ssh. However Monsoon users will need to use github +tokens as access to github from Monsoon is not available via ssh. + +To use PAT's, requires storing them in a git credentials file, conventionally +named ``~/.git-credentials``. It is important to limit access to this file, so +change the accessibility now and update the git configuration to use this file. + +.. code-block:: shell + + touch ~/.git-credentials + chmod 0600 ~/.git-credentials + git config --global credential.helper 'store --file ~/.git-credentials' + +Now `create a Classic Token +`_. +In order to read and write from a repository, you will need to select at minimum +the ``Repo`` scope. For security it is good practice to not use tokens with no +expiry date. You will also need to authorise the token for use with the +MetOffice organisation `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. From 5226526cb620c733a0e6c0eaa7b94480baea5f5e Mon Sep 17 00:00:00 2001 From: James Bruten <109733895+james-bruten-mo@users.noreply.github.com> Date: Thu, 23 Oct 2025 08:05:27 +0100 Subject: [PATCH 2/7] Update source/WorkingPractices/gh_authorisation.rst Co-authored-by: Yaswant Pradhan <2984440+yaswant@users.noreply.github.com> --- source/WorkingPractices/gh_authorisation.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/WorkingPractices/gh_authorisation.rst b/source/WorkingPractices/gh_authorisation.rst index 59b46820..f4395889 100644 --- a/source/WorkingPractices/gh_authorisation.rst +++ b/source/WorkingPractices/gh_authorisation.rst @@ -135,9 +135,9 @@ Using github tokens is generally optional, as the test suites will by default attempt to verify using ssh. However Monsoon users will need to use github tokens as access to github from Monsoon is not available via ssh. -To use PAT's, requires storing them in a git credentials file, conventionally -named ``~/.git-credentials``. It is important to limit access to this file, so -change the accessibility now and update the git configuration to use this file. +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 From dad346f1d164685c88ba569beaf7fd3e3ed11ed7 Mon Sep 17 00:00:00 2001 From: James Bruten <109733895+james-bruten-mo@users.noreply.github.com> Date: Thu, 23 Oct 2025 08:07:04 +0100 Subject: [PATCH 3/7] Update source/WorkingPractices/gh_authorisation.rst Co-authored-by: Yaswant Pradhan <2984440+yaswant@users.noreply.github.com> --- source/WorkingPractices/gh_authorisation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/WorkingPractices/gh_authorisation.rst b/source/WorkingPractices/gh_authorisation.rst index f4395889..278f6660 100644 --- a/source/WorkingPractices/gh_authorisation.rst +++ b/source/WorkingPractices/gh_authorisation.rst @@ -145,7 +145,7 @@ git to use it: chmod 0600 ~/.git-credentials git config --global credential.helper 'store --file ~/.git-credentials' -Now `create a Classic Token +Next, `create a Classic Token `_. In order to read and write from a repository, you will need to select at minimum the ``Repo`` scope. For security it is good practice to not use tokens with no From e8fce9ebffb1175d94208e87e934bf67f50692db Mon Sep 17 00:00:00 2001 From: James Bruten <109733895+james-bruten-mo@users.noreply.github.com> Date: Thu, 23 Oct 2025 08:07:36 +0100 Subject: [PATCH 4/7] Update source/WorkingPractices/gh_authorisation.rst Co-authored-by: Yaswant Pradhan <2984440+yaswant@users.noreply.github.com> --- source/WorkingPractices/gh_authorisation.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/WorkingPractices/gh_authorisation.rst b/source/WorkingPractices/gh_authorisation.rst index 278f6660..2dead9ea 100644 --- a/source/WorkingPractices/gh_authorisation.rst +++ b/source/WorkingPractices/gh_authorisation.rst @@ -147,11 +147,11 @@ git to use it: Next, `create a Classic Token `_. -In order to read and write from a repository, you will need to select at minimum -the ``Repo`` scope. For security it is good practice to not use tokens with no -expiry date. You will also need to authorise the token for use with the -MetOffice organisation `Single Sign On -`_. +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. Additionally, authorise your token for use with the MetOffice +organisation via Single Sign On. See the GitHub documentation for details: +`Authorizing a personal access token for use with Single Sign-On `_. .. important:: From 69af6b6bab4519ac5e9aebaa9bab6fe5f8b89c4c Mon Sep 17 00:00:00 2001 From: James Bruten <109733895+james-bruten-mo@users.noreply.github.com> Date: Thu, 23 Oct 2025 08:29:38 +0100 Subject: [PATCH 5/7] Update source/WorkingPractices/gh_authorisation.rst Co-authored-by: Yaswant Pradhan <2984440+yaswant@users.noreply.github.com> --- source/WorkingPractices/gh_authorisation.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/WorkingPractices/gh_authorisation.rst b/source/WorkingPractices/gh_authorisation.rst index 2dead9ea..f89c24a1 100644 --- a/source/WorkingPractices/gh_authorisation.rst +++ b/source/WorkingPractices/gh_authorisation.rst @@ -131,9 +131,9 @@ for details of authenticating. Github Personal Access Tokens ----------------------------- -Using github tokens is generally optional, as the test suites will by default -attempt to verify using ssh. However Monsoon users will need to use github -tokens as access to github from Monsoon is not available via ssh. +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, for now. To use Personal Access Tokens (PATs), store them in a git credentials file, typically ``~/.git-credentials``. Restrict access to this file and configure From 69af6b37c46112fa12c96978bb4681631a07bac4 Mon Sep 17 00:00:00 2001 From: James Bruten Date: Thu, 23 Oct 2025 08:32:46 +0100 Subject: [PATCH 6/7] tweak sso wording --- source/WorkingPractices/gh_authorisation.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/source/WorkingPractices/gh_authorisation.rst b/source/WorkingPractices/gh_authorisation.rst index f89c24a1..5ba92524 100644 --- a/source/WorkingPractices/gh_authorisation.rst +++ b/source/WorkingPractices/gh_authorisation.rst @@ -79,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 `_. @@ -133,7 +134,7 @@ 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, for now. +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 @@ -149,9 +150,10 @@ 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. Additionally, authorise your token for use with the MetOffice -organisation via Single Sign On. See the GitHub documentation for details: -`Authorizing a personal access token for use with Single Sign-On `_. +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:: From b8ef9d64c37ba05c6179c398f7bf44397746570c Mon Sep 17 00:00:00 2001 From: James Bruten Date: Thu, 23 Oct 2025 08:46:38 +0100 Subject: [PATCH 7/7] monsoon note --- source/Development/testing.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/Development/testing.rst b/source/Development/testing.rst index a3f887dc..2367a786 100644 --- a/source/Development/testing.rst +++ b/source/Development/testing.rst @@ -53,7 +53,8 @@ mirrors and naming it ``my_rose_stem_suite``. * ``-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. + 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