Connect GitHub

Broker a real repository through a GitHub App installation.

Where to run this

Every command on this page runs from a clone of the AgentBox repository on the trusted host — never inside the agent workspace. If you haven't cloned it yet, start with the quickstart.

Create a GitHub App

Grant Contents: read and write (plus the automatic Metadata: read). For workspace PR and CI commands, also grant Pull requests: read and write and Actions: read. Install it on a disposable test repository first.

Organization → Members: read is only needed for the GitHub teams entitlement source.

Record identifiers

Note the App ID, installation ID, and the numeric repository ID. Download the private key to a location only the trusted broker can read.

Copy the example configuration

cp .env.example .env
cp examples/config.json config.local.json

Edit .env with the App ID and absolute private key path. Edit config.local.json with your runtime identity, OWNER/REPO, repository ID, installation ID, and rules. Replace YOUR_ORG/YOUR_REPO in every rule.

Generate a workspace token

umask 077; openssl rand -hex 32 > ~/.agentgate-client-token
echo "AGENTGATE_CLIENT_TOKEN_FILE=$HOME/.agentgate-client-token" >> .env

Without AGENTGATE_CLIENT_TOKEN_FILE the daemon refuses to start.

Start the broker

npm start

In another terminal:

curl http://127.0.0.1:7432/healthz
git -c credential.helper= \
  -c http.extraHeader="Authorization: Bearer $(cat ~/.agentgate-client-token)" \
  clone http://127.0.0.1:7432/OWNER/REPO.git

Never in shared deployments

AGENTGATE_ALLOW_UNAUTHENTICATED=1 runs the broker with no workspace bearer token. Any client that can reach the listener would act as the runtime identity. Use it for local demos only.

Protected branches

List every sensitive branch in protectedBranches. The broker refuses to start unless GitHub reports deletion, non_fast_forward, and pull_request rules on each one, because it can't tell force pushes from updates itself. AGENTGATE_SKIP_RULESET_CHECK=1 exists for offline demos only.

Keep the key in a KMS

For production, set AGENTGATE_SIGN_COMMAND instead of GITHUB_PRIVATE_KEY_PATH. Any program that reads stdin and writes an RSASSA-PKCS1-v1_5 SHA-256 signature works. examples/sign-with-aws-kms.sh shows AWS KMS; under Compose, layer the override:

docker compose -f compose.yaml -f compose.kms.yaml up -d --build agentd

The override drops the PEM secret entirely. Its script needs the aws CLI, which the shipped image doesn't include — build a derived image or point AGENTGATE_SIGN_COMMAND at your own signer.

TLS between workspace and broker

The broker serves plain HTTP only while AGENTGATE_HOST is loopback. Any other address requires TLS (or AGENTGATE_ALLOW_PLAINTEXT=1 for local demos).

sh scripts/make-dev-cert.sh ~/.agentgate-tls

Set AGENTGATE_TLS_CERT_FILE / AGENTGATE_TLS_KEY_FILE on the broker and AGENTGATE_CA_FILE in the workspace; AGENTGATE_URL must then use https://. Production certificates come from your own PKI.

Local development is not isolation

An agent running as the same OS user can read that user's files and reach the admin socket. Use a separate runtime with configuration and state outside its filesystem — see Docker workspace.

Test against live GitHub

npm run test:live drives a real installation end to end: clone, allowed push, denied push to main, approval-gated push, draft PR open/close, PR and CI listing, and a check that no installation token leaked into the audit log. Put LIVE_GITHUB_APP_ID, LIVE_GITHUB_PRIVATE_KEY_PATH, LIVE_REPO, LIVE_REPO_ID, and LIVE_INSTALLATION_ID in .env.live.