Connect boxes to GitHub repositories without putting a GitHub token into every box. A deployment-scoped GitHub App lets zomg-api mint short-lived GitHub installation tokens. Boxes get only a Zomg proxy token, and zomg-api uses the GitHub App credentials server-side when Git needs repository access. Use this when different boxes need different repositories or different permission scopes.
The proxy token is not a GitHub token. It only authenticates the box to Zomg’s GitHub proxy. The GitHub installation token is minted by zomg-api for the attached grant and is not returned to the box.

​
Mental model

  • A GitHub App belongs to one Zomg deployment profile.
  • The GitHub App’s configured permissions are the maximum permission envelope for that deployment.
  • A Zomg GitHub grant narrows that envelope to specific repositories and permission levels.
  • A grant is attached to one or more boxes.
  • Git traffic goes through zomg-api, which verifies the box proxy token, checks the attached grant, mints a short-lived GitHub installation token, and forwards the smart-HTTP Git request to GitHub.
box git client
  -> Zomg GitHub proxy
  -> GitHub App installation token
  -> GitHub repository

​
Create the deployment GitHub App

Run the assisted GitHub App setup flow for the deployment profile: 
zomg setup github-app --profile prod --deploy
The browser page lets you choose a personal account or enter a GitHub organization login. To skip that choice and go straight to an organization, pass the GitHub organization login: 
zomg setup github-app --profile prod --owner example-org --deploy
The command opens GitHub’s manifest flow, waits for the callback, exchanges the manifest code, stores the generated app credentials in the setup profile, and redeploys only zomg-api. Without --deploy, the credentials are stored locally but the running API does not see them until you deploy: 
zomg setup github-app --profile prod
zomg setup deploy --profile prod
Deployment materializes a Kubernetes Secret named zomg-github-app in boxes-system and zomg-api reads: 
ZOMG_GITHUB_APP_ID
ZOMG_GITHUB_APP_PRIVATE_KEY_B64
For check-in friendly profile config, run zomg setup secrets after the GitHub App flow. It writes deploy-time secrets, including the GitHub App material, into infra/secrets/<profile>.sops.yaml, encrypted by SOPS. Check whether the running API has GitHub App config: 
zomg github config

​
Agent-assisted setup

If you are working with a coding agent, ask it to run the GitHub setup flow for you: 
zomg setup github-app --owner example-org --deploy
The agent should run the setup command and API-only deploy, not just describe the steps. If the agent has browser automation or a browser MCP/tool, it can offer to complete the GitHub manifest approval page. If not, you complete the GitHub page in your browser while the CLI waits for the local callback.
If you rotate or recreate the GitHub App, run zomg setup github-app --deploy again so the new app id and private key reach zomg-api.
After creating the app, install it on the GitHub repositories or organization Zomg should be able to access. Zomg grants can only narrow the repositories and permissions the GitHub App installation already has. Deployment verification uses a dedicated private repository and expects the deployment GitHub App id 4126581. The app installation must include that repository. Run the live GitHub verify with: 
just verify --only 01d-github-git-access
The live verify creates a temporary grant and box, attaches the grant, checks that in-box Git is configured automatically, and clones the repository with a normal GitHub URL.

​
Create a repository grant

A grant names the repositories and permissions the boxes you attach it to can use. 
zomg github grant create work-api \
  --repo example-org/api \
  --repo example-org/shared-lib \
  --permission contents=read \
  --permission pull_requests=write
List grants: 
zomg github grant list
Delete a grant: 
zomg github grant delete work-api
A grant cannot exceed the permissions configured on the GitHub App. If the app was created with contents:read, a grant cannot make repository contents writable.

​
Attach a grant to a box

Attach the grant to the box that should use it: 
zomg github attach my-box work-api
Inspect attached grants: 
zomg github box-grants my-box
Detach the grant: 
zomg github detach my-box work-api

​
Clone through the proxy

zomg github attach configures Git inside the box. It stores the box’s Zomg proxy token in /etc/zomg/github-proxy-token, installs a system credential helper, and adds URL rewrites for each repository in the grant. After attaching the grant, clone with the normal GitHub URL inside the box: 
zomg exec my-box -- git clone https://github.com/example-org/api.git /work/api
SSH-style GitHub URLs are rewritten too: 
zomg exec my-box -- git clone git@github.com:example-org/api.git /work/api
The proxy URL shape is an implementation detail: 
https://api.<zomg_domain>/github-proxy/projects/<project>/boxes/<box>/<grant>/<owner>/<repo>.git
For non-default projects, include the project in the attach command: 
zomg github attach my-project:my-box work-api

​
Security properties

Zomg limits blast radius in a few places:
  • The GitHub App private key lives in the SOPS-encrypted profile secrets file and the zomg-github-app Kubernetes Secret.
  • GitHub installation tokens are minted server-side and scoped to one repository plus the grant permissions.
  • The box receives only a Zomg proxy token.
  • Detaching the grant stops future proxy access for that box.
  • Rotating the box proxy token invalidates the previous proxy token.
Any secret passed into a running box can be copied by code in that box while it is available. Use the narrowest repository grants that fit the box, rotate proxy tokens when needed, and detach grants when the box no longer needs access.

​
Common workflows

1

Create the GitHub App

zomg setup github-app --profile prod --owner example-org --deploy
2

Create a grant

zomg github grant create work-api \
  --repo example-org/api \
  --permission contents=read
3

Attach the grant

zomg github attach my-box work-api
4

Clone through the proxy

zomg exec my-box -- git clone https://github.com/example-org/api.git /work/api