Improve documentation around Repository visibility (#343)

Co-authored-by: Dan Stefaniuk <[email protected]>
Co-authored-by: Alex Young <[email protected]>
Co-authored-by: Dan Stefaniuk <[email protected]>

Author: 3 people

practices/baseline-visibility.md

@@ -0,0 +1,23 @@
+# Baseline Visibility
+
+## Collaborating
+
+This repository is part of the [NHSDigital GitHub Organisation](https://github.com/NHSDigital), which forms part of a wider [Enterprise](https://docs.github.com/en/enterprise-cloud@latest/admin/overview/about-github-for-enterprises). To enable effective collaboration between members of the NHSDigital organisation the [base permissions](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/setting-base-permissions-for-an-organization) for repositories should be set to `No Permissions`, and visibility of Internal repositories is limited to members of the organisation. This will mean that individual members will not be able to view Private repository source code  unless granted specific permissions. All members should be invited to the `everyone` team. This grants access to Internal repositories while keeping Private repository access constrained.
+
+As the organisation is part of the Enterprise there are other Organisations. Members of these other Organisations have read access to [Internal](./baseline-visibility.md#internal-repositories) repositories.
+
+## Contributing
+
+With a baseline of `No Permissions` on a repository and as a member of the `everyone` team, members of the Organisation can view the source code of Public and Internal repositories and Private repositories that they have explicit read permissions for. They might then be able to identify improvements to this code. Each repository should contain a [CONTRIBUTING.md](../CONTRIBUTING.md) to describe how both team members and members from the wider organisation can contribute to the repository. Contributions to repositories are welcomed and should be encouraged.
+
+## Code Owners
+
+Each repository should include a [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) file in one of the [recommended locations](https://graphite.dev/guides/in-depth-guide-github-codeowners#creating-and-locating-your-codeowners-file). [Branch protections](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) must be in place to ensure that any Pull Requests are approved by users listed in the CODEOWNERS file. This ensures that any code changes are approved by appropriate members the teams that own and are responsible for the code and any downstream services that depend upon it.
+
+The presence of the CODEOWNERS file alows organisation members to identify who to contact should they have any questions about the code.
+
+Teams can be listed as CODEOWNERS, but secret teams should not be used.  Otherwise potential contributors wouldn't be able to identify who the codeowners are.
+
+## Internal Repositories
+
+Non-public repositories can be created of the `Internal` type. All members of the Enterprise can view these repositories. This will include users who do not have direct access to the individual Organisation but who are members of the Enterprise.

practices/securing-repositories.md

@@ -28,19 +28,19 @@ Contributors must take all necessary precautions to ensure that sensitive data d
 ### Organisation-level settings
 
 - All users must have MFA enabled.
-- Baseline visibility for private repositories must be `No Permission`.
+- [Baseline visibility](baseline-visibility.md) for private repositories must be `No Permission`.
 - Ability to change repository view from private to public must be reserved to admins only.
 
 ### Repository-specific settings
 
 - In line with the [Service Manual](https://service-manual.nhs.uk/service-standard/12-make-new-source-code-open), new repositories should be public by default, unless there is good reason not to - this avoids costly rework to secure private information further down the line.
 - Private repositories must disable forking.
-- There must be no outside collaborators in private repositories.
+- Outside collaborators in private repositories must be there for a specific purpose (e.g. security testers) and their need for access must be regularly reviewed.
 - Enable abuse reporting by <!-- markdown-link-check-disable -->[accepting content reports](https://docs.github.com/en/communities/moderating-comments-and-conversations/managing-how-contributors-report-abuse-in-your-organizations-repository)<!-- markdown-link-check-enable -->
 
 ### Teams setup
 
-Because of baseline visibility configurations, you must setup GitHub teams in order to provide team members access to repositories. The minimum recommended setup is as follows:
+Because of baseline visibility configurations, you must setup GitHub teams in order to provide team members appropriate access to repositories. The minimum recommended setup is as follows:
 
 - Create one team with the name of your product (e.g. `Engineering Quality Framework`). Add all required members to this team.
 - Create one child team within the team, for admins only (e.g. `Engineering Quality Framework Admins`). Add admins only to this team.
@@ -49,7 +49,7 @@ Because of baseline visibility configurations, you must setup GitHub teams in or
 
 Child teams inherit the parent's access permissions, simplifying permissions management for large groups. Members of child teams also receive notifications when the parent team is `@mentioned`, simplifying communication with multiple groups of people.
 
-Depending on your use case, you may want to create additional teams (e.g. a read-only access team, or different teams granting access to different projects). This is welcomed by the framework, as long as the teams provide clarity on the role they encompass, remain consistent and are applied consistently to your repositories.
+Depending on your use case, you may want to create additional teams (e.g. teams granting access to different projects). This is welcomed by the framework, as long as the teams provide clarity on the role they encompass, remain consistent and are applied consistently to your repositories.
 
 ## Code security