publish / solution
For toolkit maintainers

Bring the guardrails
to your organization.

Run a governance repository you control. The initial allowlist is empty on purpose: no cross-repository request is processed until you explicitly authorize its target.

1. Prepare the governance repository

Copy or fork the toolkit into an organization-controlled repository. Prefer private visibility for confidential intakes. Use Node.js 22 or newer. Read SETUP.md for complete permission tables and troubleshooting.

npm ci --ignore-scripts
npm test
npm run check

Enable Actions, create the publication-request, approved-for-production, reassessment-request, control-exception, and decommission-request labels, and protect the default branch. Give the workflow token issues-write permission; it is used only in the governance repository. Assign human triage for the three manual lifecycle forms; their labels do not trigger automated processing.

2. Choose a cross-repository credential

GitHub App · Recommended

Install on selected solution repositories. Configure repository Issues write; Contents, Administration, Code scanning alerts, and Dependabot alerts read. Metadata read is implicit.

Set variables SOLUTION_APP_ID, SOLUTION_APP_OWNER, and SOLUTION_APP_REPOSITORIES (repository names, comma-separated). Store the key as secret SOLUTION_APP_PRIVATE_KEY.

Fine-grained PAT

Select only the solution repositories and use the same repository permissions. Store it as SOLUTION_REPO_TOKEN. Do not set SOLUTION_APP_ID when selecting PAT mode.

Respect organization approval, SSO, expiry, and rotation policies. A developer's personal broad-scope token is not a long-term governance solution.

3. Adapt your policy and guides

Add exact owner/repository entries in config/policy.yml, change guide_url, and review the tier rules in config/tiers.yml. The installation/token must actually cover each target. One App token in the bundled workflows addresses one installation owner.

Edit YAML controls and their rendered guide anchors together. Update repository-specific links in these pages and the issue template. Read CUSTOMIZING.md for schema and reusable Action guidance.

4. Publish the rendered guide

In repository Settings → Pages, set the source to GitHub Actions. Run Publish guide, or push a docs change to main. No external fonts, JavaScript, CDN, analytics, or site generator are needed. GitHub Pages visibility and private publishing depend on your plan; do not assume a private repository's site is private.

5. Try a safe pilot

  1. Allowlist a disposable solution repository that you own. Install/configure the chosen credential there.
  2. Create a publication issue with synthetic, non-sensitive answers. As a maintainer, comment /publish if intake did not run automatically.
  3. Rerun /publish without changes and verify there is still one parent and one issue per applicable control.
  4. Comment /validate. Expect gaps until controls and repository settings are complete.
  5. Check partial-run recovery, a tier-changing intake edit, and native sub-issue or checklist linking before inviting more developers.