14 APM GitHub Private Distribution

Status

Accepted

Context

GitHub organisations can expose org-level Copilot agents and shared workflow files through a private .github repository (.github-private). This surface needs to stay in sync with the set of endorsed org-level Copilot agents published from apm-registry.

Two approaches were considered:

1. Direct authoring in .github-private — maintainers hand-edit agent files directly in .github-private.
2. Generated distribution — apm-registry CI generates the org-level Copilot agent files as a package artifact and syncs them into .github-private via a validated PR workflow.

Direct authoring makes .github-private a second source of truth for agent content, which diverges from the APM single-source model and loses the provenance, hash verification, and CI validation guarantees.

Generated distribution makes .github-private a read-only rendering surface. All source content lives in apm-registry; .github-private only ever holds the generated output from a specific registry release.

The handbook marketplace is also generated from apm-registry, but it is a separate distribution path. The calab-sync-agent-primitives-bot GitHub App syncs release catalog artifacts into calab-ai/calab-handbook under content/03 Products/Agent Primitives/marketplace/** by opening PRs to main; it does not directly push to protected branches.

Decision

calab-ai/.github-private is a generated distribution surface, not a primitive source repository and not a general tooling repository.

On each GA release of the calab-org-agents package from apm-registry, a distribution workflow:

1. Reads the generated package output from the release artifacts.
2. Opens or updates a sync PR in .github-private.
3. Writes generated agent files and a .generated-from-apm.json provenance file.
4. Runs validation to confirm file hashes, source refs, and no unexpected drift.
5. Auto-merges the PR if validation passes.

Files in .github-private outside the managed paths must not be overwritten by the distribution workflow. The .generated-from-apm.json provenance file records the source registry release and resolved commit for auditability.

Consequences

• Org-level Copilot agents are always consistent with the latest released calab-org-agents package from apm-registry.
• Direct hand-edits to generated files in .github-private are rejected by CI validation on the next sync.
• The distribution workflow must have write access to .github-private via a scoped GitHub App or PAT.
• .github-private must not be repurposed as a source for primitives, tooling, or other APM content.
• Provenance is auditable at the file level through .generated-from-apm.json without inspecting raw git history.
• Handbook marketplace updates from the same registry release catalog remain subject to calab-handbook PR review and CI gates, in parallel with .github-private distribution.