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.
  • 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

​
The deployment GitHub App

Your instance’s operator installs a GitHub App for the deployment and installs it on the GitHub organization or repositories Zomg should be able to reach. Once the app is installed, the grant commands below work — grants can only narrow the repositories and permissions the app installation already has. Check whether your instance has a GitHub App configured: 
zomg github config
If grant or clone commands fail with a GitHub App error, ask your operator to install the app or extend its installation to the repository you need.

​
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.ai/github-proxy/projects/<project>/boxes/<box>/<grant>/<owner>/<repo>.git
To target a box in another project, 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 stays server-side with zomg-api; it is never sent to a box.
  • 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

Check the GitHub App is configured

zomg github config
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