Skip to content
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
feat(acq-kits): add github-enterprise-kit template
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>
  • Loading branch information
mogul and OpenCode Agent committed Nov 14, 2026
commit fe7040772c8df99259bb11041c2c808af131a612
1 change: 1 addition & 0 deletions integrations/isolation/acq-kits/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ they are exempt from — and must stay out of — the `kits.yaml` registry. See
|----------|---------|
| [`examples/team-kit/`](examples/team-kit/) | A team's scope-layer mixin: conventions and agent settings through the OpenCode config tier, applied via `ACQ_EXTRA_KITS` after the global kits. Pattern and composition rules: [`../docs/scope-layers.md`](../docs/scope-layers.md). |
| [`examples/personal-kit/`](examples/personal-kit/) | A person's own mixin, stacked last: shell drop-ins, git preferences, and an OpenCode TUI theme. Its verify proves the global, team, and personal stack. |
| [`examples/github-enterprise-kit/`](examples/github-enterprise-kit/) | Lets `git` and `gh` in a sandbox authenticate to a GitHub Enterprise Server host: egress, SSH-to-HTTPS rewrites, a credential helper, and `GH_HOST`. The token stays on the host (`acq secret set --host --env`). Replace the example host in three places. |

## What is a hybrid/v1 kit?

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,157 @@
# github-enterprise-kit (template for a GitHub Enterprise Server host, `hybrid/v1`)

A **template, not a deployable kit**: the starting point for a kit that lets
`git` and `gh` inside an `acq` sandbox authenticate to a GitHub Enterprise
Server (GHES) host. `acq` never applies this directory; you copy it, rename it,
and replace the example host. `hybrid/v1` has no parameters, so a kit cannot
take your hostname as an input. The pattern, the composition rules, the parser
rules to check against your `acq`, and the backend differences are in
`integrations/isolation/docs/scope-layers.md` in
[agentic-coding-patterns](https://github.com/GSA-TTS/agentic-coding-patterns)
(the pattern doc); the placement decision is ADR 0005 beside it, in
`docs/decisions/`.

Why a kit is needed. `acq`'s GitHub support is built for `github.com`: the
first-run token prompt, `acq github-scope`, and the built-in `github` secret
all cover only `github.com` and its API and codeload hosts. A custom GHES host
gets none of that, so push and pull fail in the sandbox. This kit supplies the
three pieces a kit can: egress to the host, git configuration that uses the
injected token, and `GH_HOST` for `gh`. The token itself is never in the kit.

## What is and is not verified

| Claim | Status |
|-------|--------|
| `spec.yaml` is valid `hybrid/v1`; `validate-kits.py --strict` and `acq kit validate` pass | Verified offline. |
| The startup step rewrites `git@HOST:` and `ssh://git@HOST/` remotes to HTTPS, leaves other hosts alone, and is idempotent | Verified offline in a scratch `HOME` (`scripts/verify`, section 4). |
| The credential helper prints `username=x-access-token` and `password=<value of GH_ENTERPRISE_TOKEN>`, expanded when git runs it, and the value is never written to git config | Verified offline (`scripts/verify`, section 4). |
| One GHES hostname serves git, REST (`/api/v3`), and uploads (`/api/uploads`), so one egress entry is enough | From GitHub's GHES documentation, not tested against a live instance. With subdomain isolation enabled, GHES also serves some content from subdomains such as `raw.`, `codeload.`, `uploads.`, and `media.`; `git` over HTTPS and `gh api` calls on the main host do not need them. Add a subdomain to `caps.network.allow` only if a feature you use fails (downloading a release asset or an archive, for example). |
| On msb, the proxy swaps the placeholder into git's `Authorization: Basic` header for the bound host | Documented for `github.com` in the quickstart repo's ADR 0011 and confirmed live there with a private-repo `git ls-remote`. **Not tested against a GHES host.** |
| On sbx, the custom-secret proxy rewrites `Authorization: Basic` for the bound host | **Unverified.** `acq` stores this service through `sbx secret set-custom`, which injects by environment placeholder; whether it rewrites Basic credentials has not been checked. Run the live checks on sbx before relying on it. |
| The sandbox gets the token end to end (`git ls-remote`, `gh api user` against a real GHES host) | **Needs a real host, a real token, and a sandbox.** `scripts/verify` runs these when you opt in (see "Verifying"). Nothing in this repo has run them. |

## Use

1. Copy this directory into a repo your team owns and **rename both the
directory and `name:` in `spec.yaml`** (kebab-case; keep them equal). Update
`displayName:` and `description:`.
2. **Replace the host in three places**, all marked `REPLACE`, with the same
value (`scripts/verify` fails if they differ): the `caps.network.allow`
entry, `GHE_HOST` in the startup step, and `GH_HOST` under `environment`.
The shipped value, `ghe.example.org`, is an IANA-reserved example domain.
Use the hostname only: no scheme, no path, no port.
3. Create a personal access token **in the GHES web UI**. `acq`'s pre-filled
token link and `acq github-scope` are `github.com` only, so neither helps
here. Give it the least access that does the job:
- Prefer a **fine-grained** token limited to the repositories you need, if
your GHES version and organization policy allow them, with repository
permissions *Contents* (read and write), *Pull requests* and *Issues* (read
and write, only if the agent uses them), and *Metadata* (read).
- Otherwise a **classic** token with the `repo` scope. Add `read:org` only if
a `gh` command you use needs it.
- Set an expiry.
4. Store the token on the host, **before the sandbox is created** on msb:

```bash
acq secret set -g github-enterprise --host ghe.example.org --env GH_ENTERPRISE_TOKEN
```

`acq` prompts for the value without echoing it and never takes it on the
command line. On msb it also reads one line from piped stdin; on sbx a piped
value is not fed to sbx, so `acq` prints an `sbx secret set-custom` command
to run yourself instead. `github-enterprise` is just a
service name for `acq`'s secret store (letters, digits, `_`, `-`); the
`--host` and `--env` flags are what bind it. Use the same host as in
`spec.yaml`. Use `acq secret set SANDBOX github-enterprise ...` instead of
`-g` to limit the token to one sandbox, which is safer than a global token;
that needs the sandbox name fixed up front (`acq create --name`), and
`scripts/verify` supports only the global form.
5. Validate, then start a sandbox with the kit:

```bash
acq kit validate /path/to/your-copy
acq run opencode --kit /path/to/your-copy .
```

or put the path in `ACQ_EXTRA_KITS` (see "Host-side defaults" in the
pattern doc). Egress is fixed when a sandbox is created, so after changing
the host, run `acq rm <sandbox>` and create it again.

Inside the sandbox the token is a **placeholder**: `GH_ENTERPRISE_TOKEN` holds
a value that is useless anywhere else. The proxy substitutes the real token in
transit, only for the bound host. Do not run `env` or `printenv` in an agent
session (see "Backend differences" in the pattern doc).

## What it carries

| Extension point | Value | Why |
|-----------------|-------|-----|
| `caps.network.allow` | `ghe.example.org` | The strict and balanced egress tiers deny by default. |
| `commands[]` | One idempotent `startup` step, `user: "1000"` | Rewrites `git@HOST:` and `ssh://git@HOST/` to HTTPS, because SSH remotes do not work through msb's egress, and registers a credential helper that reads `GH_ENTERPRISE_TOKEN` when git runs it. |
| `environment` | `GH_HOST` | Points `gh` at the enterprise host. `gh` reads `GH_ENTERPRISE_TOKEN` for any host other than `github.com`. |

Both SSH forms are values of one `insteadOf` key: `--replace-all` sets the
first and `--add` appends the second, so a re-run never piles up duplicates. The
`ssh://` form ends in a slash so it cannot match a look-alike host, and an
`ssh://` URL with a port is not rewritten. The helper is written inside single quotes so `${GH_ENTERPRISE_TOKEN}` is expanded by
git's shell each time it asks for credentials, not when the step writes the
config.

## What it does not carry, on purpose

- **The token.** Host-side only, through `acq secret set`.
- **A real hostname.** The template ships a reserved example domain.
- **`github.com` routing.** The same recipe for `github.com` belongs in the
global layer; see "Git over HTTPS" in the pattern doc.
- **Changes to `gh` for github.com.** `GH_HOST` makes the enterprise host `gh`'s
default for the whole sandbox, so `gh` against `github.com` then needs
`--repo github.com/OWNER/REPO` or `GH_HOST=github.com` on that command.
- **Several hosts.** One host, one copy. Make a second copy of the kit for a
second GHES instance, with its own service name, env var, and `GH_HOST`;
note that `GH_HOST` is last-wins, so only one copy can own it.

## Verifying

```bash
./scripts/verify
```

The offline checks run anywhere with `git` and `sh`, and need no sandbox and no
network. With a real host, a stored secret, and a sandbox-capable machine:

```bash
GHE_VERIFY=1 GHE_HOST=ghe.corp.example GHE_REPO=owner/private-repo ./scripts/verify
```

`GHE_HOST` must equal the host in `spec.yaml`. `GHE_REPO` should be a **private**
repository your token can read: a repository readable without credentials is
reported as SKIP, because it would prove nothing about the token. The live section creates a
throwaway sandbox with the kit applied, then checks `GH_HOST`, that the token
variable is set (it never prints it), the SSH-to-HTTPS rewrite, egress, `git
ls-remote` with only the placeholder, and `gh api user`. Without `GHE_VERIFY=1`
and `GHE_HOST` it prints SKIP, never PASS. Run it on each backend you use;
`ACQ_BACKEND` selects one. Set `GHE_SECRET_SERVICE` if you used a service name
other than `github-enterprise`.

## Backend parity

The kit is declarative only (`caps`, `commands[]`, `environment`), with no
`backend_shortcuts` or `backend_extras`, and `scripts/verify` uses only `acq`
verbs. The backends still differ for this kit:

- **msb** binds a secret to its host at sandbox **create**. Store it before the
first `acq run`. msb cannot add a new secret to a running sandbox: for an
existing sandbox, `acq stop` it and re-run `acq secret set` (a stopped sandbox
accepts the binding), or recreate it. `acq secret set` can rotate an existing
binding on a running sandbox. SSH remotes do not work, which
is why the kit rewrites them. Git's `Authorization: Basic` header is rewritten
by msb's TLS interception (ADR 0011 in the quickstart repo, confirmed for
`github.com`).
- **sbx** injects a custom secret by placeholder. Whether it rewrites git's
Basic credentials for a custom host is **unverified**. To rotate, `acq`
refuses to overwrite an existing secret and prints the `sbx secret rm`
command; see "Backend differences" in the pattern doc.

## Troubleshooting

See [`TROUBLESHOOTING.md`](TROUBLESHOOTING.md).
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
# Troubleshooting — github-enterprise-kit (template)

Failure modes any copy of this kit inherits. Every command is an `acq` command.
The rules behind these entries live in the pattern doc
(`integrations/isolation/docs/scope-layers.md`); each entry names the section.
Replace `HOST` with your GHES hostname.

## The host is blocked (curl code `000` or `403`)

`acq exec <sandbox> -- curl -sS -o /dev/null -w '%{http_code}\n' https://HOST/`
prints `000` (msb) or `403` (sbx's proxy) when the host is not allowed. The
kit's egress entry is missing, misspelled, or the kit was not applied to this
sandbox. Check the entry, then recreate: egress is fixed at creation on every
backend, and `acq run` alone does not add it.

```bash
acq rm <sandbox> && acq run opencode --kit /path/to/your-copy .
```

Under org governance, org network rules override kit rules; a host that stays
blocked despite the entry must be allowed at the org level.

## TLS errors: `unexpected eof`, or `certificate verify failed`

A GHES host often has a certificate from an internal CA. The guest must trust
that CA, and on msb so must the host-side proxy that rewrites the token
(`ACQ_MSB_UPSTREAM_CA_CERT`, in the quickstart repo's backend guide). This kit
carries no CA; use your organization's CA kit or host trust setup. Do not
disable certificate verification (`http.sslVerify false`).

## `git push` prompts for a username, or fails with `401`/`403`

Work through these in order:

1. **No token in the guest.** `acq exec <sandbox> -- sh -c 'test -n "$GH_ENTERPRISE_TOKEN" && echo set'`.
If it prints nothing, the secret was not bound. On msb a secret is bound at
create, and msb cannot add a new secret to a running sandbox. If you stored
it afterwards, `acq stop <sandbox>` then re-run `acq secret set`, or store
it first and recreate.
`acq secret ls -g` shows the service, host, and env (never the value).
2. **Wrong host or env var in `acq secret set`.** The `--host` must equal the
kit's host, and `--env` must be `GH_ENTERPRISE_TOKEN`: the helper reads that
name. Set it again with the right flags.
3. **Credential helper not registered.** `acq exec <sandbox> -- git config --global --get-regexp 'credential|url'`
should list the helper and both `insteadOf` rules. If empty, the startup step
did not run: look for a "skipping command" warning in the create output (a
comment after `phase:` or `user:`), and see "Check against your acq" in the
pattern doc.
4. **The token is rejected by the server.** The placeholder was substituted but
the real token is expired, revoked, lacks access to the repository, or the
organization requires SSO authorization for it. Create a new token in the GHES
web UI and rotate it (below).
5. **Basic-auth substitution not happening (sbx).** Unverified on sbx for a
custom host. If the token is right and the sandbox is on sbx, this is the
likely cause; report it and use msb until it is confirmed.

## An SSH remote hangs or is refused

`git@HOST:owner/repo.git` and `ssh://git@HOST/...` are rewritten to HTTPS by the
kit's startup step, but only for the host named in `GHE_HOST`. Check what git
will contact:

```bash
acq exec <sandbox> -- git -C /path/in/guest/to/repo ls-remote --get-url origin
```

If it still prints an SSH URL, the host in the remote differs from `GHE_HOST`
(a different name for the same server), or the step did not run. A remote with
a port, such as `ssh://git@HOST:2222/...`, is deliberately not rewritten: HTTPS
does not use the SSH port, so rewrite it yourself with `git remote set-url`, or
extend the step for the form you use.

## `gh` says it is not logged in, or targets the wrong host

`gh auth status` reports hosts from `gh`'s own config; with the environment
token it can still say you are not logged in to `github.com`, which is expected.
Check `acq exec <sandbox> -- sh -c 'echo $GH_HOST'` (should print your host) and
`acq exec <sandbox> -- gh api user -q .login`. Common causes:

- `GH_HOST` is shadowed: it is last-wins across kits, so a kit applied after this
one that sets `GH_HOST` replaces it. Check the kits listed after this one.
- `GH_TOKEN` or `GITHUB_TOKEN` is set in the sandbox (for example by the global
`github` secret). `gh` uses those for `github.com` only; for `GH_HOST` it reads
`GH_ENTERPRISE_TOKEN`. Do not set `GH_TOKEN` to your enterprise token: it would
go to `github.com`.
- You are in a repository whose remote points at `github.com`: `gh` then targets
`github.com`. Use `gh --repo HOST/OWNER/REPO ...` or `GH_REPO=HOST/OWNER/REPO`.

## A `github.com` token went to the wrong host, or the reverse

Each token is bound to exactly one host by its `acq secret set --host` value. A
placeholder sent to a different host is not substituted; msb's proxy fails closed
and drops the connection, and the rest of that agent session breaks (see
"Backend differences" in the pattern doc). Keep the GHES token only under the
`github-enterprise` service and `GH_ENTERPRISE_TOKEN`, and never reuse one token
for both hosts.

## Rotating the token

On msb, re-run `acq secret set -g github-enterprise --host HOST --env GH_ENTERPRISE_TOKEN`
with the new value; it is re-fed to running sandboxes. On sbx, `acq` refuses to
overwrite and prints the `sbx secret rm` command: remove it, then set it again
with the same placeholder. See "Backend differences" in the pattern doc.

## Other failure modes

Kit content missing, create failures from the backend, SSH-fetched global kits,
and startup commands that run nothing despite a passing validate are shared with
every kit: see the `team-kit` template's `TROUBLESHOOTING.md` and "Check against
your acq" in the pattern doc.
Loading
Loading