From 44963951d140a21d02a5ea41227a12176ce26ee6 Mon Sep 17 00:00:00 2001 From: Ethan Hutchins Date: Tue, 22 Sep 2026 16:05:36 +0100 Subject: [PATCH] Update GitHub documentation for clarity and compliance with visibility policies --- using-github/coding-in-the-open.md | 148 +++++++++++----------- using-github/creating-a-readme-file.md | 3 + using-github/migrating-to-github.md | 20 +-- using-github/readme.md | 75 ++--------- using-github/software-licensing-policy.md | 4 +- 5 files changed, 94 insertions(+), 156 deletions(-) diff --git a/using-github/coding-in-the-open.md b/using-github/coding-in-the-open.md index 4a01aac36..4a6494c33 100644 --- a/using-github/coding-in-the-open.md +++ b/using-github/coding-in-the-open.md @@ -1,111 +1,113 @@ -# How to Meet Section 12: Make New Source Code Open (MOD / GOV.UK Standards) +# GitHub Repository Visibility Policy -This guidance explains how teams can meet [**Section 12 – Make New Source Code Open**](https://www.digital.mod.uk/policy-rules-standards-and-guidance/service-manual/meet-the-standard), following both the GOV.UK Service Standard and Defence‑specific considerations from the MOD Service Manual. +This policy sets out when UKHO source code may be published on GitHub. It applies to new repositories and changes to existing repository visibility. -## 1. Why this matters +## Policy position -- **Public value** - New source code created with public funds should be open by default—this maximises reuse, reduces duplication, and supports transparency and cost-efficiency across government. +UKHO repositories are **private by default**. A repository may be public only where there is a clear, current business or engineering justification and the content is suitable for external visibility. -- **Defence-specific constraints** - Defence teams should open code when appropriate, but withhold publishing code relating to SECRET or TOP SECRET systems or content that hasn't been publicly announced. +Public repositories are not inherently inappropriate. They can support transparency, reuse, and coding in the open. Public visibility must be intentional, approved, documented, and reviewed regularly. -## 2. What "make source code open" means +Private repositories must still follow UKHO requirements for access control, secret management, vulnerability scanning, and secure handling of personal and sensitive information. -### GOV.UK expectations +This policy supports [GOV.UK Service Standard point 12](https://www.gov.uk/service-manual/service-standard/point-12-make-new-source-code-open), the [GDS guidance on when code should be open or closed](https://www.gov.uk/government/publications/open-source-guidance/when-code-should-be-open-or-closed), and the [MOD Defence Service Manual](https://www.digital.mod.uk/policy-rules-standards-and-guidance/service-manual/meet-the-standard). These standards inform the decision, but do not override UKHO's private-by-default position. -- Write code in the open from the start, using a public repository—but never include secrets like API keys or credentials. -- Always retain IP ownership of your service’s new code and license it openly (e.g., MIT or another Open Source Initiative–compatible license). -- If code must remain closed (e.g., unreleased policy or sensitive security mechanisms), provide a strong rationale—but open it as soon as permissible. +## Code ownership and commercial boundaries -### Additional GOV.UK technical guidance +UKHO should retain ownership of code created for its services and must use an appropriate open-source licence before publication. -- Host code publicly (e.g., GitHub), ensuring departmental control and compliance with cybersecurity standards. -- Avoid embedding secrets—manage them using secure secret-management systems. -- Open configuration code, database schemas, and even security‑enforcing code (cryptographic or authentication logic) unless there's a specific reason—noting that openness often strengthens security. -- Use a clear open-source license, handle versioning (e.g. Semantic Versioning), provide contributing guidelines, manage issues, and encourage community contributions. -- Track changes via version control and prepare to manage security vulnerabilities in public code responsibly. +Using commercial software does not automatically require UKHO-developed code to remain private. However: -#### Closed code +- vendor-owned code must not be published without permission +- proprietary SDKs, APIs, libraries, and data must be checked against their licence terms +- UKHO configuration, infrastructure code, and integration code may be published only after the same security, information, and licensing review as other source code +- open-core products must be assessed so that only components permitted for redistribution are published -Only a small number of well-defined situations justify keeping code closed. Per the [GDS guidance on when code should be open or closed](https://www.gov.uk/government/publications/open-source-guidance/when-code-should-be-open-or-closed) and the [MOD Defence Service Manual (Section 12)](https://www.digital.mod.uk/policy-rules-standards-and-guidance/service-manual/meet-the-standard), these are: +Where a restriction is temporary, such as unreleased policy, record the date or condition for reconsideration. Keep only the necessary content private and review the decision when the restriction expires. -- **Keys and credentials** – must always be kept separate and closed; use a secret management system -- **Fraud detection algorithms** – keep the algorithm closed but separate from the code that uses it -- **Unreleased policy** – keep closed only until the policy is announced; open as soon as possible thereafter -- **SECRET or TOP SECRET content (MOD-specific)** – code that directly relates to classified systems or content at these markings must not be published -- **Third-party intellectual property not licensed for open publication** – code, algorithms, or data owned by a vendor or third party where the licence does not permit open redistribution +## Opening a repository -> **Note on "commercially sensitive" code:** Commercial sensitivity alone is **not** a valid reason under GDS or MOD guidance to keep code closed. If a team believes code is commercially sensitive, this must be assessed case-by-case with the product owner, security champion, and legal adviser. A clear and documented rationale must be provided — see [Providing a rationale for closed code](#providing-a-rationale-for-closed-code) below. +Before making a repository public, the team must: -These items will usually be identified early in the product lifecycle with support from your product owner and cyber security team. If you are unsure if your code should be open or closed then it is important to organise a session to work through this. +1. Record the purpose, benefits, owner, owning team, and next review date. +2. Confirm that the proposed content is suitable for external visibility. +3. Complete the [Repository Visibility Change Governance Checklist](/software-engineering-policies/OpenSourceContribution/OpenSourceGovernanceChecklist.md). +4. Complete code, dependency, secret, personal-data, classification, and licensing reviews. +5. Add or update the README, `SECURITY.md`, licence, `CODEOWNERS`, contribution guidance, and issue process as appropriate. +6. Obtain the required approval through the development portal. -#### Open code +Public repositories must not contain: -You should open all other code. This includes: +- keys, credentials, tokens, or other secrets +- SECRET or TOP SECRET content +- unreleased policy or information not approved for publication +- unnecessary personal data or internal information +- third-party content not licensed for public redistribution +- algorithms or other material specifically assessed as requiring confidentiality -- configuration code -- database schema -- security-enforcing code +Where a repository contains both publishable and restricted content, separate the content rather than publishing the whole repository. -More details can be found in the [GDS Guidance – When code should be open or closed](https://www.gov.uk/government/publications/open-source-guidance/when-code-should-be-open-or-closed) +## Minimum standard for public repositories -#### Providing a rationale for closed code +A public repository must have: -Where code cannot be made open, teams **must** provide a convincing written explanation of why. This rationale should: +- a clear README describing its purpose and ownership +- a `CONTRIBUTING.md` describing contribution expectations and processes +- an appropriate open-source licence, unless an approved exception applies +- a current `SECURITY.md` +- `CODEOWNERS` where appropriate +- suitable branch protection and access controls +- an active pipeline with vulnerability and secret scanning +- pipeline checks for SAST, software composition analysis, code quality, and dependency or vulnerability updates +- container scanning and infrastructure-as-code scanning where applicable +- a process for vulnerabilities, issues, and external contributions -- identify the specific subset of code that must remain closed (do not close entire repositories unnecessarily) -- name the applicable reason from the list above -- state the expected date or condition under which the code can be opened -- be recorded in the repository's README or a linked document, and reviewed at regular intervals +The publication review must include configuration, infrastructure code, database schemas, and security-enforcing code. These must not be treated as safe simply because they are not application code. -This is a requirement of both [GOV.UK Service Standard point 12](https://www.gov.uk/service-manual/service-standard/point-12-make-new-source-code-open) and the MOD Defence Service Manual. +## Ongoing review -#### Commercial software and open/closed boundaries +Repository owners must review each public repository at least every six months and whenever its owner, purpose, or content changes materially. The review should cover: -When your service includes or is built on commercial software: +- purpose, owner, activity, and maintenance status +- repository content, history, issues, pull requests, and metadata +- required files, branch protection, pipeline activity, and scan evidence +- secrets, credentials, personal data, and organisational intelligence -- **Our own code remains open by default** even when it integrates with commercial products — the commercial product licence does not automatically make your code closed -- **Vendor-supplied or vendor-owned code** must not be published without explicit permission from the vendor; check your contract and engage the legal adviser if in doubt -- **Proprietary SDKs, APIs, or libraries** incorporated into your codebase may restrict redistribution; ensure the vendor licence is reviewed against our [Software Licensing Policy](./software-licensing-policy.md) before publishing -- **Configuration code for commercial tools** (e.g. Terraform modules targeting a commercial product, Helm charts, CI/CD pipeline definitions) should be open unless they contain credentials or commercially confidential configuration values -- Where a commercial product contains **open-core** components, ensure you are publishing only the OSI-licensed portions and not conflating them with the proprietary modules +Make a repository private or archive it when public visibility is no longer justified or its content is unsuitable for publication. Public visibility must not continue simply because it was previously approved. -If you are uncertain about any commercial software boundary, consult your Security Champion, Lead Engineer, and Legal Adviser before publishing. +## Governance and reporting -## 3. Defence (MOD)‑specific enhancements +The designated owner of the public repository review process must maintain an inventory of public repositories, their owners, justifications, review dates, and outstanding actions. They must report overdue reviews and material exceptions through the agreed governance route. -- **Do open code where possible**—unless the code deals with SECRET or TOP SECRET elements. -- **Ensure classification awareness**: assess which parts of the codebase are sensitive and only withhold those as necessary, with intent to open once safe. +Repository owners must promptly report suspected secret exposure, unsuitable public content, failed security scans, or loss of the justification for public visibility. The repository must be made private or access restricted while the issue is assessed where necessary. -## 4. Summary: Step‑by‑Step Guidance +## Contributor account hygiene -| Phase | Actions | -| ------------- | ----------------------------------------------------------------------- | -| **Planning** | - Define IP and open licensing (e.g., MIT)
- Choose open repo tool within Defence and compliant with cyber policy | -| **Development** | - Code openly from day one
- Exclude secrets and credentials (use secret management)
- Write clear documentation and commit history | -| **Security Review** | - Conduct security checks before publishing
- Remove sensitive content and confirm what may remain closed (e.g., unreleased policy or SECRET parts) | -| **Publishing** | - Release code publicly under an open licence
- Include versioning rules, contributing guidelines, issue tracking | -| **Ongoing Management** | - Continue development openly
- Maintain version control and handle issues transparently
- Monitor and promptly patch security vulnerabilities | +Contributor accounts are part of repository governance. Public activity can link code, reviews, issues, usernames, profile details, and working patterns. -## 5. Tips & Best Practices +Contributors should: -- **Open by default, closed only for strong reasons** – and open as soon as those reasons no longer apply. -- **Plan for openness from the start** – reducing the burden of retrospectively sanitizing code. -- **Favour openness even in security‑critical modules** – properly designed open cryptographic code can be more robust. -- **Use secure development workflows** – store code in trusted repositories, manage secrets separately, and structure your release process to accommodate open-source norms. -- **Provide clear governance** – licenses, versioning, contribution policies, and response channels for external collaborators. +- use an account suitable for UKHO work and a UKHO email address where required +- keep email addresses private or use GitHub proxy-email features +- minimise public profile information, including location, employer details, photographs, and personal links +- avoid linking personal services to a work-associated GitHub profile +- understand the effects on links and attribution before renaming an account +- enable the authentication controls required by UKHO -## 6. Opening a closed repository +This guidance must be included in contributor onboarding and periodic repository access reviews. It reduces unnecessary personal exposure without removing accountability or contribution history. -In the case where a repository is available to be made open, it is required that a team lead fills in the [checklist](/software-engineering-policies/OpenSourceContribution/OpenSourceGovernanceChecklist.md) with the necessary details. This request can then be processed in the development portal. +## Secret detection and history management -## 7. Repositories that do not require a licence +Secret prevention and detection must be layered. TruffleHog should be assessed periodically and supplemented where appropriate with GitHub secret scanning and push protection, GitLeaks or equivalent scanning, pre-commit controls, pipeline checks, and repository monitoring. Secrets must be kept outside source control using approved secret-management systems. -Most repositories should carry an open-source licence. However, there are limited circumstances where publishing a licence is not appropriate: +Container images must continue to be scanned for vulnerabilities and embedded secrets when they are built, imported, or refreshed, using the existing Snyk controls and container-ingestion checks where applicable. Suspected exposed secrets must be revoked or rotated promptly and handled through the appropriate incident process. -- **Classified or restricted repositories** that are not and will not be publicly accessible do not require an OSI licence, but must still carry appropriate classification markings -- **Purely internal tooling** that is explicitly scoped as never-to-be-published — though teams should challenge this assumption and default to openness -- **Third-party code** repositories where UKHO does not hold the IP and cannot grant a licence +Squash and merge is encouraged for new projects where appropriate. It improves maintainability but does not remove all contributor information. -In all these cases, the absence of a licence must be documented and approved. See the [Software Licensing Policy](./software-licensing-policy.md) for further detail on when a licence may not be required. +History rewriting is not routine remediation. `git filter-repo`, mailmap files, and rebasing can break signatures and references and require contributors to re-clone. Use them only for a specific, material risk that cannot be addressed less disruptively, with approval, communication, and testing beforehand. + +## Exceptions and licensing + +Where code cannot be made public, document the specific restricted content, the reason, and the date or condition for reconsideration. Commercial sensitivity alone is not sufficient; consult the product owner, Security Champion, Lead Engineer, and Legal Adviser where relevant. + +Most public repositories must carry an open-source licence. An exception may apply to classified or restricted repositories, approved internal-only tooling, or third-party code where UKHO cannot grant a licence. The absence of a licence must be documented and approved. See the [Software Licensing Policy](./software-licensing-policy.md). diff --git a/using-github/creating-a-readme-file.md b/using-github/creating-a-readme-file.md index 41733b037..28ac9e38c 100644 --- a/using-github/creating-a-readme-file.md +++ b/using-github/creating-a-readme-file.md @@ -32,6 +32,9 @@ It is not the place for detailed documentation, keep that elsewhere and include * Link to documentation * Background context, why have you written this * Team members/contributors. +* Code of Conduct +* Development scripts, such as `script/bootstrap`, `script/dev`, and `script/test`, where applicable +* Technical decision logs or architecture decision records, where applicable * Anything else that seems relevant ### Resources diff --git a/using-github/migrating-to-github.md b/using-github/migrating-to-github.md index 379698adc..d1b14dc94 100644 --- a/using-github/migrating-to-github.md +++ b/using-github/migrating-to-github.md @@ -2,22 +2,8 @@ ## Remove sensitive data -As part of [the Open Source Governance Checklist](../software-engineering-policies/OpenSourceContribution/OpenSourceGovernanceChecklist.md), it is a requirement that sensitive data has been removed from the repository history. This can be acheived with Git's `filter-branch` command to walk over the history of a branch and apply changes throughout. +As part of [the Repository Visibility Change Governance Checklist](../software-engineering-policies/OpenSourceContribution/OpenSourceGovernanceChecklist.md), sensitive data must be removed before a repository is made public. -## Remove lines from commit messages +History rewriting is disruptive and must not be used as routine remediation. First remove the sensitive data from the current working tree, rotate or revoke exposed secrets, and assess whether the repository should remain private. Where history rewriting is necessary, use `git filter-repo` rather than the deprecated `git filter-branch` command. Obtain approval, communicate the change to contributors, and test the process on a representative copy before rewriting the repository. -Gerrit leaves a `Commit-Id` line in every commit message made. To remove these, the `--msg-filter` can be used as follows: - -```bash -git filter-branch -f --msg-filter 'sed "/Change-Id/ d"' -- --all -``` - -Substitute `Change-Id` for any string to match an entire line and delete from all commit message in the branch. - -## Remove directories/files from branch trees - -To remove directories from the entire history of a branch, use the `--tree-filter` as follows: - -```bash -git filter-branch --tree-filter "rm -rf dev" --prune-empty HEAD -``` +Specific history-rewriting commands are intentionally not included here because the correct filters depend on the repository and the data being removed. Use the [git-filter-repo documentation](https://github.com/newren/git-filter-repo) and obtain a review from the repository owner and Security Champion before applying any rewrite. diff --git a/using-github/readme.md b/using-github/readme.md index 53d6b7bc0..1d9b63efb 100644 --- a/using-github/readme.md +++ b/using-github/readme.md @@ -1,69 +1,16 @@ -# Our guidance for using GitHub +# Using GitHub -We should be adhering to the MoD digital service manual and [point 12](https://www.digital.mod.uk/policy-rules-standards-and-guidance/service-manual/meet-the-standard) states that we should be making new source code open. This is an extension of the [GDS guidelines](https://www.gov.uk/service-manual/service-standard/point-12-make-new-source-code-open) in which they talk about [what should be open and what should be closed](https://www.gov.uk/government/publications/open-source-guidance/when-code-should-be-open-or-closed). There is the additional care to be taken with [security classifications](https://www.digital.mod.uk/service-manual/security-classifications) and commercial protections however we should opt for a Public repo on creation unless agreed upon in threat modelling that a closed repo is required. +This directory contains guidance for using GitHub at UKHO. -## Background +UKHO repositories are private by default. The [GitHub Repository Visibility Policy](coding-in-the-open.md) defines when a repository may be made public and the controls required before and after publication. -This repository is to provide guidance on what must exist in open repos as a minimum with the aim of enabling people to feel familiar when browsing, find information and to become productive if contributing back. +## Guidance -## Overview +- [GitHub Repository Visibility Policy](coding-in-the-open.md): repository visibility, public repository approval, ongoing review, contributor account hygiene, security scanning, and licensing boundaries. +- [Creating a README](creating-a-readme-file.md): what a project README should contain. +- [Creating a CONTRIBUTING.md](creating-a-contributing-file.md): how to document contribution expectations and processes. +- [Pull request guidance](pull-request-details.md): a suggested pull request workflow for contributors and maintainers. +- [Migrating a project to GitHub](migrating-to-github.md): removing sensitive data and adapting project history during migration. +- [Software licensing policy](software-licensing-policy.md): selecting and documenting licences, Crown Copyright, and third-party licensing considerations. -All open repos must contain the following: - -* **A CONTRIBUTING.md within the root folder.** The file is a marker to people that this repo will accept changes from outside of the team. It must contain the processes that the owner of the repository needs people to follow when contributing to the project. [Guidance on how to write a CONTRIBUTING.md](creating-a-contributing-file.md). - -* **A LICENSE within the root folder.** This will be MIT in most cases. Having a license is critical as it states what others are allowed to do with the code. - -* **A README.md within the root folder.** This must contain some basic useful information for the user allowing them to quickly understand the project and get started using it. It isn't the place for extensive documentation. [Guidance on how to write a README.md](creating-a-readme-file.md). - -> [!IMPORTANT] -> An empty readme does not provide any useful information to ourselves, the reader or future maintainers. Please do not create the file just to tick a box. - -* **A continuous integration build process.** Each time a pull request is submitted a build is triggered which will run all the tests to ensure the change does not break any features. This will also give the contributor feedback and confidence that their code will work! This also supports in keeping your services up to date with dependency and vulnerability updates. - -Above is the minimum for what an open repo must contain, other useful things a repo may contain: - -* Code of Conduct - * [Code of Conduct from contributor covenant](https://www.contributor-covenant.org/). - -* Changelog - * [Keep a changelog](http://keepachangelog.com/en/0.3.0/). - -* TDL (Technical decision log) - * [Documenting Architecture Decisions](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). - * [Architecture Decision Records In action presentation](https://resources.sei.cmu.edu/asset_files/Presentation/2017_017_001_497746.pdf). - -* Scripts - * ```script/bootstrap``` - Configure the machine ready to develop for this repo (pull down and configure dependencies etc.) - * ```script/dev``` - Start any background processes/servers needed during development - * ```script/test``` - Run all the tests for this repo. - -## Code Contribution Process - -All open repos must be using git and code contributions should be made using the standard Fork and Pull Request approach (or equivalent). [Guidance on how to make a pull request](pull-request-details.md). - -## Tooling - -All public repos will need to have the following tooling run against them to ensure that we are protecting ourselves: - -* SAST Tooling -* SCA Scanning -* Container Scanning (where applicable) -* Infrastructure as Code scanning (where applicable) -* Code quality scanning -* Dependency/Vulnerability update checks (Dependabot or similar) -* Pre-commit secret checks (GitHub advanced security) - -## Terminology - -```Contributing``` - This is more than just adding code, this also includes creating issues/bug reports, asking questions, improving documentation. - -```Contributor``` - This refers to anyone who has added to this project, including filing issues. - -```Repo``` - A git repository and the associated Github/lab with it. - -```Pull Request``` - How a contributor asks the owner of a repository to accept their contribution. The owner "pulls" the contribution into the main repository. - -## Inspiration - -[Alpha Gov - Open Standards](https://github.com/alphagov/open-standards) +The linked documents provide detailed guidance for their subject areas. Where guidance overlaps, the GitHub Repository Visibility Policy takes precedence for repository visibility and public release decisions. diff --git a/using-github/software-licensing-policy.md b/using-github/software-licensing-policy.md index f15f0d0fc..5360ee365 100644 --- a/using-github/software-licensing-policy.md +++ b/using-github/software-licensing-policy.md @@ -4,7 +4,7 @@ When developing software for government use, it is important to choose appropriate open-source licences that align with the [GOV.UK Service Standard point 12](https://www.gov.uk/service-manual/service-standard/point-12-make-new-source-code-open), the [MOD Defence Service Manual (Section 12)](https://www.digital.mod.uk/policy-rules-standards-and-guidance/service-manual/meet-the-standard), and the UK Government's Open Source Licensing framework. -**All code produced by civil servants or contractors working on behalf of the Crown is automatically covered by [Crown Copyright](https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/).** Regardless of repository visibility you should select and publish a licence so that the terms of use are clear, and so that GitHub can correctly identify the licence. +**All code produced by civil servants or contractors working on behalf of the Crown is automatically covered by [Crown Copyright](https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/).** Public repositories must include an appropriate licence so that the terms of use are clear and GitHub can correctly identify the licence. Private repositories should follow the licensing requirements agreed for the project. You must include a `LICENSE` file in the repository root. It is also recommended to add a licence section to the `README.md`. @@ -12,7 +12,7 @@ You must include a `LICENSE` file in the repository root. It is also recommended There are limited circumstances where publishing a licence is not appropriate or required: -- **Never-public repositories** — internal-only tooling that is explicitly scoped as never publicly accessible (though teams should challenge this and default to openness) +- **Never-public repositories** — internal-only tooling that is explicitly scoped as never publicly accessible - **Classified or restricted repositories** — repositories that carry security classifications and are not accessible outside the department; apply classification markings instead - **Third-party owned code** — where UKHO does not hold the IP and therefore cannot grant a licence to others