diff --git a/source/WorkingPractices/gh_authorisation.rst b/source/WorkingPractices/gh_authorisation.rst index 075d5a15..f40732d6 100644 --- a/source/WorkingPractices/gh_authorisation.rst +++ b/source/WorkingPractices/gh_authorisation.rst @@ -62,6 +62,8 @@ and `commit email address ``ID+username@users.noreply.github.com``. * Use this email address instead in the command above. +.. _ssh: + SSH Key Setup ------------- @@ -78,21 +80,35 @@ SSH Key Setup 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 -`_. +One way to do this is via ssh keys. + +1. `Generate a new ssh key and add it to the ssh-agent. + `_. +2. `Add the public key to your GitHub Account. + `_ +3. `Configure the SSH key for SSO + `_. + + * In order to use this ssh key with MetOffice organisations, it must be authorised. + First ensure you are a member of the MetOffice GitHub organisation and then + authorise the key for single sign on access. + +4. Add a GitHub entry in your ~/.ssh/config: + +.. code-block:: + + Host github github.com + User git + IdentityFile %d/.ssh/ + IdentitiesOnly yes + ForwardX11 no .. tip:: In order to work non-interactively with the test suite, your ssh key will need to be setup without a passphrase. If you prefer to use a passphrase - with ssh, then :ref:`Personal Access Tokens ` can act as an + with ssh, then :ref:`Personal Access Tokens ` can act as an alternative. Verified Commits diff --git a/source/git_faq.rst b/source/git_faq.rst index d5f2ab2a..54fca72a 100644 --- a/source/git_faq.rst +++ b/source/git_faq.rst @@ -3,37 +3,74 @@ Git Migration FAQ's =================== -How do I access the repositories? - All of the migrated Simulation Systems repositories are found in the Met - Office organisation. Certain repositories, where licencing allows, have been - made public, so can be viewed by anyone. Other repositories (eg. UM) are - internal to the Met Office organisation. These can be seen if you have access - to the organisation. - -Where are my branches and tickets? - Migration of individual branches and tickets is being left to each developer - to be done on a case by case basis. Please see the :ref:`branch migration - guide ` for advice on migrating an fcm branch to git. - -Why can't I push or create a branch in the repository? - We are managing our repositories using a :ref:`forking ` model, - therefore creating of branches in the central repository is tightly - controlled. Please create your own fork and develop your changes on branches - in there. - -Why won't the rose-stem command work? - The syntax to launch the test suite has changed with the move to git. Please - see our :ref:`testing pages `. - -How do I run with an older version? - The entire history of each trunk branch from the MOSRS repository has been - migrated (for the UM this is from vn9.2). If you need a specific release, then - you can checkout the tag of that release, eg. ``git checkout ``. If you - require a specific commit, you will need to find the relevant hash from the - history of the main branch. - -Why can't I see the full history of Jules and MONC? - Due to licencing issues we were unable to make the history of these - repositories public. We have a copy of the repository with all the previous - releases internal to the MetOffice. Please ask if you need help accessing - that. +.. rubric:: How do I access the repositories? + +All of the migrated Simulation Systems repositories are found in the Met +Office organisation. Certain repositories, where licencing allows, have been +made public, so can be viewed by anyone. Other repositories (eg. UM) are +internal to the Met Office organisation. These can be seen if you have access +to the organisation. + +.. rubric:: Where are my branches and tickets? + +Migration of individual branches and tickets is being left to each developer +to be done on a case by case basis. Please see the :ref:`branch migration +guide ` for advice on migrating an fcm branch to git. + +.. rubric:: Why can't I push or create a branch in the repository? + +We are managing our repositories using a :ref:`forking ` model, +therefore creating of branches in the central repository is tightly +controlled. Please create your own fork and develop your changes on branches +in there. + +.. rubric:: Why won't the rose-stem command work? + +The syntax to launch the test suite has changed with the move to git. Please +see our :ref:`testing pages `. + +.. rubric:: Rose-stem is giving the following error while trying to fetch code + from other repositories: `git@github.com: Permission denied (publickey).` + +This is a sign of SSH setup issues. Please make sure you've followed all the +steps on the :ref:`GitHub Authorisations page`. + +.. rubric:: How do I run with an older version? + +The entire history of each trunk branch from the MOSRS repository has been +migrated (for the UM this is from vn9.2). If you need a specific release, then +you can checkout the tag of that release, eg. ``git checkout ``. If you +require a specific commit, you will need to find the relevant hash from the +history of the main branch. + +.. rubric:: Why can't I see the full history of Jules and MONC? + +Due to licencing issues we were unable to make the history of these +repositories public. We have a copy of the repository with all the previous +releases internal to the MetOffice. Please ask if you need help accessing +that. + +.. rubric:: My forked repository got detached from upstream repository following + visibility change (private to public) upstream. + +The "detached" state is a security feature to isolate private forks when the +upstream parent becomes public. Only GitHub staff have the administrative +privileges required to manually re-link the repository network while +preserving existing PR data and history. + +One option is to make sure any work you wish to preserve is in a clone of your +fork. Then recreate the fork from upstream using the same name as before. +Pushing from your clone will connect to the new fork. However this will delete +any pull requests you had open from the previous fork. + +If you already have a lots of develop branches/PRs, its probably best to +contact GitHub Support and Submit a ticket to reattach your fork with +upstream with the following message: + + My upstream private repo became public, which detached my fork. I have open + PRs I need to preserve. Please reattach my fork to the original network. + + Upstream URL: https://github.com/MetOffice/{repo-name} + Fork URL: https://github.com/{user}/{repo-name} + +This process should usually get resolved within a day.