Add Centralised InnerSource Repository Governance pattern

Update centralised-repository-governance.md

Author: amburi

patterns/1-initial/centralised-repository-governance.md

@@ -0,0 +1,214 @@
+## Title
+
+Centralised InnerSource Repository Governance
+
+## Patlet
+
+InnerSource repositories become difficult to discover, understand, and contribute to when project hygiene drifts across teams. A central governance repository can define InnerSource readiness checks as policy-as-code and run automated audits that help project owners keep their repositories contributor-friendly without removing local ownership.
+
+## Problem
+
+As InnerSource adoption grows, teams publish repositories with different levels of documentation, ownership clarity, contribution guidance, communication channels, and discoverability metadata. Some repositories have a strong `README.md` and `CONTRIBUTING.md`; others have no maintainer contact, no issue templates, unclear CODEOWNERS, stale labels, or no signal that outside contributions are welcome.
+
+These gaps make contributors hesitate. They cannot tell whether a repository is active, who owns it, how to ask questions, what kind of contribution is welcome, or whether the project follows the organisation's InnerSource standards. Manual checks by an InnerSource Program Office, platform team, or community group do not scale once many teams publish projects.
+
+## Story
+
+An InnerSource Program Office noticed that contributors often gave up before opening a pull request. The source code was visible, but the contribution path was unclear. Some repositories had no `CONTRIBUTING.md`; others had outdated contact information or no issue labels that helped newcomers find suitable work.
+
+Instead of asking every team to remember a checklist, the program office created a governance repository. It stored the organisation's InnerSource readiness expectations as versioned policies and ran scheduled audits across participating repositories.
+
+Project owners received a simple report: which InnerSource readiness checks passed, which ones needed attention, who owned the repository, and where to find remediation guidance. The audit did not block teams. It helped them make their projects easier to discover, understand, and contribute to.
+
+## Context
+
+* InnerSource is practiced across multiple teams, business units, or repositories.
+* Teams retain ownership of their repositories and contribution process.
+* Contributors need clear signals for how to use, discuss, and contribute to projects.
+* The organisation has shared expectations for InnerSource project hygiene.
+* An InnerSource Portal, source code inventory, or repository catalogue may already exist.
+* GitHub Actions, GitHub APIs, or similar automation tooling is available.
+
+## Forces
+
+* **Autonomy vs consistency:** Teams need local ownership, but contributors need predictable project signals.
+* **Contributor confidence:** Missing documentation, stale ownership, or unclear communication channels discourage contributions.
+* **Scale:** Manual InnerSource readiness reviews fail once repository count grows.
+* **Signal quality:** Noisy or overly generic findings will be ignored.
+* **Valid variation:** Different governance levels or project maturity stages may require different readiness expectations.
+* **Infrastructure strain:** Large audits can consume API rate limits, runner capacity, logs, and team attention.
+* **Control-plane security:** The governance repository becomes important infrastructure because tampering with policies, exceptions, inventory, or workflows can hide readiness gaps across many repositories.
+
+## Solution
+
+Create a **central InnerSource governance repository** that defines contributor-readiness expectations as policy-as-code and runs scheduled audits against repositories in scope. Treat it as an internal product with owners, review rules, actionable reports, and a practical exception process.
+
+The governance repository should contain:
+
+```text
+innersource-governance/
+  policies/
+    default/
+      base-documentation.yml
+      contribution-process.yml
+      communication.yml
+      discoverability.yml
+    shared-ownership/
+      codeowners.yml
+      maintainer-model.yml
+  repository-inventory.yml
+  exceptions.yml
+  audit/
+    audit.py
+  .github/
+    workflows/
+      readiness-audit.yml
+```
+
+### InnerSource Policies
+
+Store InnerSource readiness expectations in `policies/`. Use a small number of profiles that match your organisation's InnerSource operating models, such as `default`, `contributions-welcome`, or `shared-ownership`.
+
+Checks can include:
+
+* `README.md` with project purpose, usage, and getting-started guidance,
+* `CONTRIBUTING.md` with contribution process and review expectations,
+* `CODEOWNERS` or documented maintainer ownership,
+* issue and pull request templates,
+* documented communication channels,
+* support or maintainer contact information,
+* license or internal sharing guidance,
+* repository description, topics, and discoverability metadata,
+* contribution labels such as `good first issue` or `help wanted`, and
+* InnerSource Portal badge or registration metadata.
+
+Security and repository configuration checks, such as branch protection or workflow permissions, can be included when they directly support trusted collaboration. Keep the focus on making repositories safer and easier to contribute to.
+
+### Repository Inventory
+
+Maintain an inventory of repositories covered by the audit. This can live in the governance repository or be imported from an InnerSource Portal or source code inventory.
+
+```yaml
+repositories:
+  - name: payments-api
+    owner: payments-platform-team
+    profile: contributions-welcome
+    lifecycle: active
+    portal_slug: payments-api
+```
+
+Each repository should have an owner, lifecycle state, and assigned InnerSource profile. This gives every finding a clear owner and prevents one generic checklist from being applied to every project.
+
+### Exception Registry
+
+Record approved deviations from the readiness baseline in `exceptions.yml`. Each exception should have an owner, reason, and expiry or review date.
+
+```yaml
+exceptions:
+  - repository: payments-api
+    policy: issue_templates_required
+    reason: Team is migrating from an external tracker this quarter.
+    owner: payments-platform-team
+    expires: 2026-12-31
+```
+
+Exceptions keep governance practical, but they should be visible in reports. Avoid broad or non-expiring exceptions because they hide contributor experience problems.
+
+### Readiness Audit
+
+Use an audit script to inspect each repository and compare it with the assigned InnerSource policy profile. Findings should include the repository, owner, policy, severity, expected state, actual state, exception status, and suggested remediation.
+
+Prioritise checks that immediately affect contributor success:
+
+* missing or incomplete base documentation,
+* missing contribution process,
+* unclear ownership or maintainer contact,
+* undocumented communication channel,
+* missing issue or pull request templates,
+* stale portal metadata or missing discoverability tags,
+* missing labels for newcomer-friendly work, and
+* repository settings that make contribution review unsafe or unclear.
+
+Design the audit to be incremental and rate-aware. Store the last known state and re-check only repositories that changed where possible. Use conditional requests such as `ETag` / `If-None-Match`, cache expensive checks like repository metadata, branch names, workflow files, and CODEOWNERS, and use GraphQL batching carefully for bulk metadata. Stagger scan frequency by project importance: active InnerSource projects nightly, candidate projects every few days, and archived or sandbox repositories weekly or monthly.
+
+### Reporting and Remediation
+
+Run the audit on a schedule and publish a digest report. Start with visibility-only reporting before introducing automated remediation.
+
+```yaml
+on:
+  schedule:
+    - cron: "0 2 * * *"
+```
+
+Reports should help project owners improve contributor experience, not rank or shame teams. For each finding, include clear remediation guidance or links to templates. If automated remediation is later added, use reviewable pull requests for straightforward fixes such as adding a missing template file.
+
+Track metrics that show whether InnerSource participation is becoming easier:
+
+* percentage of repositories covered,
+* percentage of repositories passing readiness checks,
+* open findings by severity,
+* mean time to remediate contributor-blocking gaps,
+* active and expired exceptions,
+* false positives and repeated findings,
+* audit runtime, API usage, and runner minutes.
+
+### Govern the Governance Repository
+
+The governance repository should itself follow strong InnerSource practices. Policy changes should happen through pull requests, with visible discussion and review by the InnerSource Program Office, platform team, security partners, and affected project owners where appropriate.
+
+Protect the repository more strictly than ordinary project repositories. Require branch protection, mandatory reviews, CODEOWNERS approval for `policies/`, `exceptions.yml`, inventory, audit code, and workflows, and signed or verified changes for sensitive files.
+
+Use least-privilege credentials. Separate read-only audit credentials from any remediation credentials. Log and alert on changes to policies, exceptions, inventory, workflows, and credentials. Periodically audit the governance repository through an independent check.
+
+## Resulting Context
+
+* Contributors can quickly tell whether a repository is ready for InnerSource participation.
+* Project owners receive actionable guidance for improving documentation, ownership, communication, and discoverability.
+* InnerSource expectations are transparent, version-controlled, and open to contribution.
+* Exceptions are explicit, time-bound, and visible.
+* InnerSource Portal and inventory data become more reliable.
+* Audit cost and infrastructure load are managed through incremental, staggered scans.
+* Leadership gains visibility into InnerSource health without micromanaging repository owners.
+
+## Use This Pattern When
+
+* You have many InnerSource repositories owned by different teams.
+* Contributors struggle to identify how to use or contribute to projects.
+* InnerSource Portal quality depends on repository metadata and project hygiene.
+* Manual readiness checks are too slow or incomplete.
+* You want transparent policy-as-code instead of undocumented central checks.
+* The cost of poor contributor experience is higher than the cost of maintaining the governance process.
+
+## Don’t Use This Pattern When
+
+* Only a few InnerSource repositories exist and manual support is enough.
+* You need hard enforcement at merge time rather than periodic guidance.
+* You cannot maintain repository ownership or lifecycle metadata.
+* You cannot protect the governance repository and its credentials appropriately.
+* Most projects require unique contribution models that do not fit a small set of profiles.
+
+## Known Instances
+
+TBD
+
+## Status
+
+* Initial
+
+## Authors
+
+* [Amburi Roy](https://www.linkedin.com/in/amburi/)
+
+## Related Patterns
+
+* [Standard Base Documentation](../2-structured/base-documentation.md) — defines the contributor-facing files that an InnerSource readiness linter can check.
+* [Assisted Compliance](assisted_compliance.md) — complements audit findings by helping repository owners add missing contribution guidance.
+* [Communication Tooling](../2-structured/communication-tooling.md) — describes the communication channels that readiness checks can require repositories to document.
+* [Issue Tracker Use Cases](../2-structured/issue-tracker.md) — supports checking that issue templates and public planning practices are in place.
+* [Unified Source Code Inventory](source-code-inventory.md) — can provide the repository inventory used as audit scope.
+* [Explicit Governance Levels](../2-structured/governance-levels.md) — can provide policy profiles for different InnerSource operating models.
+* [InnerSource Portal - Hygiene](innersource-portal-hygiene.md) — overlaps with readiness checks for portal badges, metadata, and active projects.
+* [Include Product Owners](include-product-owners.md) — helps with stewardship of the governance repository.
+* [Trusted Committer](../2-structured/trusted-committer.md) — supports safe and consistent policy changes.
+* [InnerSource Portal](../2-structured/innersource-portal.md) — complements central access to shared organisational knowledge.