Skip to content

feat(acq-kits): add github-enterprise-kit template - #597

Draft
mogul wants to merge 2 commits into
mainfrom
feat/github-enterprise-kit
Draft

mogul wants to merge 2 commits into
mainfrom
feat/github-enterprise-kit

Conversation

@mogul

@mogul mogul commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

New copy-and-rename template github-enterprise-kit (not in kits.yaml, per ADR 0005). It lets git and gh in an acq sandbox authenticate to a GitHub Enterprise Server host. acq's GitHub support covers github.com only (GSA-TTS/agentic-coding-quickstart#698), so a custom host gets no token prompt and push/pull fail. The kit supplies the pieces a kit can; the token stays on the host.

host:   acq secret set -g github-enterprise --host HOST --env GH_ENTERPRISE_TOKEN
                         (value in acq's store; guest only sees a placeholder)
kit:    caps.network.allow   HOST
        startup step         git@HOST: , ssh://git@HOST/  ->  https://HOST/
                             credential helper reads ${GH_ENTERPRISE_TOKEN} when git runs it
        environment          GH_HOST=HOST
proxy:  rewrites the placeholder in git's Authorization: Basic header for HOST
 integrations/isolation/
 ├── acq-kits/
+│   ├── README.md                         # Templates table row
 │   └── examples/
+│       └── github-enterprise-kit/
+│           ├── spec.yaml                 # example host ghe.example.org, REPLACE x3
+│           ├── README.md                 # what is / is not verified
+│           ├── TROUBLESHOOTING.md
+│           └── scripts/verify            # offline checks + opt-in live checks
 └── docs/
+    └── scope-layers.md                   # pointer from "Git over HTTPS"

Design notes:

  • The two SSH rewrites are two values of one insteadOf key (--replace-all, then --add). The ssh:// form ends in / so it cannot rewrite a look-alike host or a URL with a port.
  • Egress is the one hostname. GHES serves git, /api/v3, and /api/uploads there; subdomain-isolation hosts are only needed for features like release assets.
  • No ADR: ADR 0005 already covers where templates live.

Evidence

  • Before: no kit; a GHES remote has no egress, no HTTPS rewrite, no helper.
    After (scratch HOME, scripts/verify section 4; run twice, output after both):
git@ghe.example.org:own/repo.git          -> https://ghe.example.org/own/repo.git
ssh://git@ghe.example.org/own/repo.git    -> https://ghe.example.org/own/repo.git
git@github.com:own/repo.git               -> unchanged
GH_ENTERPRISE_TOKEN=PLACEHOLDER_abc git credential fill
  username=x-access-token
  password=PLACEHOLDER_abc        # read at run time; token value never in git config
  • scripts/verify offline: 15 passed, 0 failed, 1 skipped (live section). Mutated copies fail on a token-looking value, a host mismatch, and a missing --add line.
  • validate-kits.py --strict: 10 kits + 3 templates valid. acq kit validate: OK. markdownlint, make validate, pytest (884) pass.
  • Two rounds of adversarial sub-agent review; round 1 found 4 MAJOR issues (all fixed), round 2 found no blockers.

Not verified (needs a real GHES host, token, and sandbox)

  • Live git ls-remote / gh api user against GHES on either backend (scripts/verify runs them with GHE_VERIFY=1 GHE_HOST=...; it prints SKIP otherwise).
  • msb rewriting Basic auth for a GHES host: confirmed for github.com only (quickstart ADR 0011).
  • sbx: whether the custom-secret proxy rewrites Basic auth is unverified; the README says so.
  • GHES with an internal CA (TLS trust on guest and host proxy).

Merge Danger

Door: two-way. Additive docs and a template; revert the commit to undo.

Blast Radius: negligible. acq never applies the template, it is not in the registry, and no existing kit or script changes. Copiers who skip the REPLACE steps get a harmless reserved-domain egress entry.

Eligibility & Accountability

  • I am a federal employee or contractor (PRs merge with @GSA-TTS/agentic-coding-team code-owner approval; eligibility is attested here, not authenticated).
  • I understand this change and can explain it in my own words — I am the author of record and accountable for it.
  • By opening this PR, I attest I have the right to release this work under the repository's CC0-1.0 dedication.

AI Assistance Disclosure

  • AI tools were used in this contribution: OpenCode (Claude) drafted the template, docs, and scripts/verify; a second AI sub-agent reviewed the diff.
  • I verified all AI-generated content (no fabricated APIs, dependencies, or citations).
  • No third-party material is reused.

Type of Change

  • New tool/editor integration (integrations/)
  • Documentation update

Testing

  • Ran make validate locally (all checks pass)
  • Ran make test equivalent (pytest scripts/tests: 884 passed)
  • Tested with at least one real scenario (live GHES run pending, see "Not verified")
  • Examples are concrete and realistic
  • Commit message follows Conventional Commits

Safety Checklist

  • No secrets, API keys, tokens, or passwords included
  • No PII
  • No CUI
  • No internal URLs or hostnames (only reserved ghe.example.org / ghe.corp.example)
  • No customer data or proprietary information

Related Issues

Relates to GSA-TTS/agentic-coding-quickstart#698 (the kit is a workaround; fixing acq itself is separate work).

mogul and others added 2 commits November 14, 2026 00:26
Copy-and-rename template that lets an acq sandbox authenticate git and
gh against a GitHub Enterprise Server host: egress entry, SSH-to-HTTPS
rewrites, a credential helper reading GH_ENTERPRISE_TOKEN at run time,
and GH_HOST. The token stays on the host (acq secret set --host --env).

Co-authored-by: OpenCode Agent <user@gsa.gov>
Co-authored-by: OpenCode Agent <user@gsa.gov>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant