Setting Up Github Authorisations#

Initial Setup#

Note

The topics on this page are all more completely covered in other documentation, which should be used first when finding any issues. Common steps required to begin working with simulation systems repositories are described here however. We will endeavour to provide links to other documentation throughout.

All users looking to interact with the simulation system repositories, will need to create a GitHub account. Please visit signup to create an account.

Multi Factor Authentication should also be enabled. This will be a requirement to accesses certain repositories, but is encouraged for all users. When signed in, account security settings can be found at settings/security.

Important

Certain repositories with more restrictive licencing (eg. UM) will remain internal to the Met Office github organisation. To access these you will need to be a member of the organisation. Internal employees can request to be added via Service Now.

Before starting to use GitHub, you will also need to configure your user name and commit email address.

git config --global user.name "User Name"
git config --global user.email "User Email"

# Verify
git config --global user.name
git config --global user.email

Tip

Github has functionality that can keep your email address private.

  • Navigate to settings/emails

  • Enable the Keep my email addresses private setting. This should generate a unique noreply email address for you, which will look like ID+username@users.noreply.github.com.

  • Use this email address instead in the command above.

SSH Key Setup#

Important

Simulation Systems test suites will by default attempt to clone remote sources via ssh. Therefore setting up ssh keys is recommended.

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 Testing Your Change for more details) or -S USE_TOKENS=true which will use a GitHub Personal Access Token (see below). Access from Monsoon will require using a PAT.

You will require a way of 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. In order to use this ssh key with MetOffice organisations, it must be authorised 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.

Verified Commits#

Important

Ensure you have setup verified commits before beginning work on a branch that is targetting being merged to main.

Any branches with unverified commits will require rebasing before review.

Verified (or signed) commits are a way of ensuring the identity of the committer by signing the commit with a form of verification key, eg. ssh or gpg. Simulation Systems repositories will all be set up to enforce verified commits.

For instructions please see the GitHub documentation on setting up a verification key. If you have setup an ssh key for authenticating, then this can be reused for signing.

Tip

Run git config --global commit.gpgsign true in order to automatically sign each commit.

gh Command Line Interface#

Tip

The gh command line documentation is available at https://cli.github.com/manual/.

The gh command line is a useful tool for interacting with remote repositories. Where appropriate we have given options for performing tasks with gh as well as other methods.

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 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:

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,

echo "https://<gh-username>:<PAT>@github.com" >> ~/.git-credentials

To use your token to authenticate with GitHub when running the rose-stem suite, include the command line option -S USE_TOKENS=true. For Monsoon users, this option is automatically enabled.