Guides

Connecting a portfolio

Install the GitHub app against the organisations you want understood. Start with every repository rather than a chosen few — the value of the scan is proportional to how much of the portfolio it can see, and read access cannot change anything.

• Install read-only against one or more organisations
• Let the scan finish before drawing conclusions from it
• Review the detected capabilities and correct the ones it got wrong
• Grant write scope only when you are ready for proposals

Reading the first scan

The scan will find duplication you already suspected and some you did not. Resist the urge to fix it immediately. The first useful move is naming the capabilities — once the graph has correct names and owners, everything downstream composes against something real.

Writing a first strategy

Write it the way you would brief a senior engineer: the outcome, the constraint, the thing it must not break. Avoid naming implementations. The analysis comes back with requirements, existing coverage and a reuse ratio, and every requirement is editable before anything is planned.

Raising the reuse ratio

A low ratio on the first strategy is normal and says more about the portfolio than about the strategy. It rises when near-miss capabilities are extended rather than forked, and it falls every time someone accepts a new capability that duplicates an existing one under a different name.

• Extend a near-miss capability instead of creating a sibling
• Give capabilities owners — unowned ones get forked
• Deprecate with a migration path rather than deleting
• Watch the ratio per product, not just per portfolio

Configuring policy

Start stricter than you think you need. Every rule states an action, an outcome and a reason in one line, so the cost of a rule being too tight is a visible refusal rather than a silent surprise. Loosen from evidence, not from impatience.

Configuring release gates

All eight gates are on by default. The useful configuration work is deciding which changes require a named approver and which can pass automatically — a low-risk interface label and a schema migration should not be governed identically.

Rolling out autonomy

Proposal-only first, for a few weeks, on one product. Read the pull requests as you would a new engineer's. Move to gated execution when the proposals stop surprising you, and widen by change class rather than all at once.