Add GitHub management runbooks (#20)

spikeheap · web-flow · commit 3c2c7be82105 · 2024-11-05T12:11:39.000Z
* Explicitly order ways of working pages

We do this so we can add the GitHub management docs (and lots of other things) without them taking the top spots in the sidebar

* Add GitHub management docs

These docs detail how to add a new user, remove that user, and some extra information about how we use groups and who owns an account.
diff --git a/docs/ways-of-working/GitHub/_category.yml b/docs/ways-of-working/GitHub/_category.yml
@@ -0,0 +1 @@
+position: 10
diff --git a/docs/ways-of-working/GitHub/add_a_user_to_github.md b/docs/ways-of-working/GitHub/add_a_user_to_github.md
@@ -0,0 +1,53 @@
+---
+sidebar_position: 1
+---
+# Add a user to GitHub
+
+This runbook describes how to add internal and outside collaborators to the  [LBHackney-IT GitHub organisation](https://github.com/LBHackney-IT).
+
+> ⚠️ Access to `LBHackney-IT` GitHub organisation is controlled by Google Group membership, so adding users directly within GitHub will not work.
+
+There are two workflows: one for users with Hackney accounts and one for those that don't ([outside collaborators](#outside-collaborators)). Always prefer the Hackney Google account route where possible.
+
+## Staff and users with Hackney Google account
+
+### Prerequisites
+
+1. The `Manager` role in [SAML-Github-Users](https://groups.google.com/a/hackney.gov.uk/g/saml-github-users/members), which includes the Head of Engineering and Lead Engineers.
+
+### Steps
+
+1. In the [`SAML-Github-Users` Google Group](https://groups.google.com/a/hackney.gov.uk/g/saml-github-users/members) add the user as a "Group member" with the following welcome message:
+
+    > Hi, you've been added to this group so you can access our GitHub organisation.
+    >
+    > There are some steps you need to take now (if you've already done a couple of these, even better):
+    >
+    > 1. Create or login to your GitHub account. Its fine to use an existing/personal account if you have one.
+    > 2. Visit https://github.com/settings/emails and add your Hackney email address.
+    > 3. Visit https://github.com/settings/security and setup 2 factor authentication.
+    > 4. Click https://github.com/orgs/LBHackney-IT/sso and follow the steps to login to your Hackney Google account and associate it with your GitHub account.
+    >
+    > Once you've done that, tell the person who's getting you set up your GitHub username and they'll add you to the appropriate groups so you can get started.
+
+2. Once the user has completed those steps grant them access to repositories by adding them to one or more teams, following [Manage GitHub teams](./manage_github_teams.md).
+
+## Outside collaborators
+
+Where someone doesn't (and shouldn't) have a Hackney Google account, we can add them as "Outside collaborators"
+
+> ⚠️ This method is more restrictive and cumbersome than the one above. Only use it where a contributor should not have a Hackney Google account, e.g. a short-term agency engagement accessing a single repository.
+
+### Prerequisites
+
+1. You must have the `Admin` role on the repository/repositories you're adding the person to.
+2. The user's GitHub account must have 2 factor authentication enabled.
+
+### Steps
+
+> ℹ️ Outside collaborators are added per-repository, so you may need to complete these steps multiple times for the same person.
+
+1. In the repository the user needs access to, visit `Settings` ->  `Collaborators and teams`, then in `Manage access` click `Add people`.
+2. Find the user by their GitHub username.
+    - GitHub will highlight that the user is an external collaborator.
+3. Pick the lowest-privilege role which enables the user to perform their tasks. Typically this will be `Write` or `Maintain`, but must _not_ be `Admin`.
diff --git a/docs/ways-of-working/GitHub/github_account_ownership.md b/docs/ways-of-working/GitHub/github_account_ownership.md
@@ -0,0 +1,22 @@
+---
+sidebar_position: 10
+---
+# GitHub account ownership
+
+Unlike most enterprise systems, GitHub's user model separates ownership of accounts and organisations. Within Hackney we follow this model.
+
+## The `LBHackney-IT` organisation
+
+Hackney owns and manages the [LBHackney-IT organisation](https://github.com/LBHackney-IT). Any repositories, Actions, etc. within the organisation are owned and controlled by us, and we have various security controls in place. Therefore all Hackney-owned repositories _must_ reside within the `LBHackney-IT` organisation.
+
+## User accounts
+
+User accounts are personally owned, and may be used for other activities on GitHub outside of Hackney.
+
+### Do I need to create a new account when I join Hackney?
+
+You have two options when you join Hackney that are equally valid:
+
+1. Use your existing GitHub account. This is the most common choice, and enables you to keep all your contribution history in one place, and contribute to work and personal projects without needing to switch accounts.
+
+2. Create a new account, separate from your existing account. You may prefer to have strong separation between work and personal projects, in which case a fresh account dedicated to Hackney makes sense. Typically this involves adding `LBH` as a prefix of suffix to the username. You'll still own this account if you leave, and may choose to delete it.
diff --git a/docs/ways-of-working/GitHub/manage_github_teams.md b/docs/ways-of-working/GitHub/manage_github_teams.md
@@ -0,0 +1,67 @@
+---
+sidebar_position: 2
+---
+# Manage GitHub teams
+
+This page describes how to create and manage teams, as well as deciding and managing team membership.
+
+## Why and how we use teams
+
+Managing individuals' access to specific repositories doesn't scale well. Instead, we group people into teams and manage those teams' access to repositories. This makes it much easier to get new starters set up correctly and manage people moving between teams.
+
+Teams are managed in the [LBHackney-IT Teams list](https://github.com/orgs/LBHackney-IT/teams).
+
+> ℹ️ Teams should reflect our organisation structure, so may require occasional refactoring to align them.
+
+There are currently two main types of team in use:
+
+1. Profession teams, e.g. [`Development Team`](https://github.com/orgs/LBHackney-IT/teams/development-team). Every member of the profession belongs in these groups, and they're used for things that are owned by the professional as a whole, for example this documentation site.
+
+2. Project teams, e.g.  [`Targeted Services`](https://github.com/orgs/LBHackney-IT/teams/targeted-services). These project teams have a sub-team for leads, which provides elevated privileges to do more sensitive repository management.
+
+## Adding a new user
+
+Typically a new joiner will need to be added to at least two teams:
+
+- The profession they belong to (e.g. [Development Team](https://github.com/orgs/LBHackney-IT/teams/development-team)), and
+- One or more product teams they belong to (or the `leads` sub-team of that product).
+
+### Adding a regular contributor
+
+Any lead can add people to one or more of their teams.
+
+1. In the [Teams list](https://github.com/orgs/LBHackney-IT/teams) click on the team you want to add them to, e.g. `Housing Products`.
+2. Click `Add a member`
+3. Search for the user's GitHub username.
+4. Click `Invite`.
+
+### Adding a lead
+
+Leads are added in a subtly different way, in order to grant them the `Admin` role to repositories the team is responsible for. We add the lead to both the main product _and_ the leads teams, and set them as team maintainers so they can add and remove team members.
+
+> ℹ️ A "lead" in this context is someone trusted to manage the project, and doesn't reflect a specific job title.
+
+Any lead can add another lead, or this can be carried out by a GitHub admin, e.g. the Head of Engineering.
+
+1. In the [Teams list](https://github.com/orgs/LBHackney-IT/teams) find the team you want to add them to, e.g. `Housing Products`.
+2. Click the disclosure arrow on the right hand side (next to `X teams`, and click the relevant "... leads" team).
+    ![Screenshot showing the above steps to select the leads team.](../img/github_add_to_leads_team.png), and add the user:
+    1. Click `Add a member`.
+    2. Search for the user's GitHub username.
+    3. Click `Invite`.
+3. Change their role to 'Maintainer' for the team:
+    1. Click the check box to the left of the user.
+    2. Click the `1 member selected` drop-down.
+    3. Click `Change role`.
+    4. Select `Maintainer`.
+    5. Click  `Change role`.
+4. Go to the parent team (e.g. `Housing Products`), and add the user:
+    1. Click `Add a member`
+    2. Search for the user's GitHub username.
+    3. Click `Invite`.
+5. Change their role to 'Maintainer' for the team:
+    1. Click the check box to the left of the user.
+    2. Click the `1 member selected` drop-down.
+    3. Click `Change role`.
+    4. Select `Maintainer`.
+    5. Click  `Change role`.
diff --git a/docs/ways-of-working/GitHub/remove_a_user_from_github.md b/docs/ways-of-working/GitHub/remove_a_user_from_github.md
@@ -0,0 +1,44 @@
+---
+sidebar_position: 3
+---
+# Remove a user from GitHub
+
+There are a couple of scenarioes where we will remove someone from the `LBHackney-IT` GitHub organisation:
+
+- They leave Hackney
+- They no longer contribute to engineering projects or don't need access to GitHub anymore.
+
+There are two workflows: one for users with Hackney accounts and one for those that don't ([outside collaborators](#outside-collaborators)). Always prefer the Hackney Google account route where possible.
+
+## Staff and users with Hackney Google account
+
+### Prerequisites
+
+1. The `Manager` role in [SAML-Github-Users](https://groups.google.com/a/hackney.gov.uk/g/saml-github-users/members), which includes the Head of Engineering and Lead Engineers.
+2. The `Owner` role on the `LBHackney-IT` organisation (as of 2024 that's the Head of Engineering and some Lead Engineers).
+
+### Steps
+
+1. Remove the person from the [`SAML-Github-Users` Google Group](https://groups.google.com/a/hackney.gov.uk/g/saml-github-users/members).
+
+2. Find the user in the [People list](https://github.com/orgs/LBHackney-IT/people), click  the `...` dropdown, then select `Remove from organization`:
+![Screenshot showing the steps described above in the GitHub interface](../img/github_remove_user.png)
+
+> ℹ️ It's necessary to remove the user from both Google _and_ GitHub to ensure all access is revoked in a timely fashion and they cannot re-join the GitHub organisation.
+
+## Outside collaborators
+
+It is possible to remove people from individual repositories, however the process described here requires fewer steps.
+
+### Prerequisites
+
+1. You must have the `Owner` role on the `LBHackney-IT` organisation (as of 2024 that's the Head of Engineering and some Lead Engineers).
+
+### Steps
+
+> ℹ️ These steps are also described in the [official GitHub documentation](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/removing-an-outside-collaborator-from-an-organization-repository), which includes alternative instructions to remove people from individual repositories.
+
+1. Visit [`People` -> `Outside collaborators`](https://github.com/orgs/LBHackney-IT/outside-collaborators).
+2. Select the people you'd like to remove from the organisation.
+3. Above the list of outside collaborators, select the `X collaborators selected...` dropdown menu, and click `Remove from all repositories`.
+4. Review the confirmation notice and confirm by clicking `Remove outside collaborators`.
diff --git a/docs/ways-of-working/README.md b/docs/ways-of-working/README.md
@@ -1,3 +1,6 @@
+---
+sidebar_position: 0
+---
 # Our Ways of Working
 
 ## Planning/Prioritisation
diff --git a/docs/ways-of-working/development_standards.md b/docs/ways-of-working/development_standards.md
@@ -1,6 +1,9 @@
+---
+sidebar_position: 1
+---
 # Hackney Development Standards
 
-## 12 Factors App 
+## 12 Factors App
 
 <b> The Twelve-Factor App Methodology is suggested by developers for smoothly working and delivering Software as a Service (SaaS) Applications or Web Apps with a focus on Microservices. </b>
 
diff --git a/docs/ways-of-working/img/github_add_to_leads_team.png b/docs/ways-of-working/img/github_add_to_leads_team.png
diff --git a/docs/ways-of-working/img/github_remove_user.png b/docs/ways-of-working/img/github_remove_user.png
diff --git a/docs/ways-of-working/pull_request _process.md b/docs/ways-of-working/pull_request _process.md
@@ -1,3 +1,6 @@
+---
+sidebar_position: 2
+---
 # Pull Request process
 
 ## Context
