add new FAQs

source/WorkingPractices/gh_authorisation.rst

@@ -62,6 +62,8 @@ and `commit email address
       ``[email protected]``.
     * 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
 <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
-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>`_.
+One way to do this is via ssh keys.
+
+1. `Generate a new ssh key and add it to the ssh-agent.
+   <https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent>`_.
+2. `Add the public key to your GitHub Account.
+   <https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account>`_
+3. `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>`_.
+
+   * 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/<ssh-key-paired-with-GitHub>
+    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 <github_path>` can act as an
+    with ssh, then :ref:`Personal Access Tokens <github_pat>` can act as an
     alternative.
 
 Verified Commits

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 <branch_migration>` 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 <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 <testing>`.
-
-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 <TAG>``. 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 <branch_migration>` 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 <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 <testing>`.
+
+.. rubric:: Rose-stem is giving the following error while trying to fetch code
+  from other repositories: `[email protected]: 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<ssh>`.
+
+.. 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 <TAG>``. 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.