Forkr can connect boxes to GitHub repositories without putting a GitHub token into every box. A deployment-scoped GitHub App gives forkr-api permission to mint short-lived GitHub installation tokens. Boxes receive only a Forkr proxy token, and forkr-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 Forkr’s GitHub proxy. The GitHub installation token is minted by forkr-api for the attached grant and is not returned to the box.

​
Mental model

  • A GitHub App belongs to one Forkr deployment profile.
  • The GitHub App’s configured permissions are the maximum permission envelope for that deployment.
  • A Forkr GitHub grant narrows that envelope to specific repositories and permission levels.
  • A grant is attached to one or more boxes.
  • Git traffic goes through forkr-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
  -> Forkr GitHub proxy
  -> GitHub App installation token
  -> GitHub repository

​
Create the deployment GitHub App

Run the assisted GitHub App setup flow for the deployment profile: 
4kr 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 directly to an organization, pass the GitHub organization login: 
4kr 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 forkr-api. Without --deploy, the credentials are stored locally but the running API does not see them until you deploy: 
4kr setup github-app --profile prod
4kr setup deploy --profile prod
Deployment materializes a Kubernetes Secret named forkr-github-app in forks-system and forkr-api reads: 
FORKR_GITHUB_APP_ID
FORKR_GITHUB_APP_PRIVATE_KEY_B64
For check-in friendly profile config, run 4kr 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: 
4kr github config

​
Agent-assisted setup

If you are working with a coding agent, ask it to run the GitHub setup flow for you: 
4kr setup github-app --owner example-org --deploy
The agent should run the setup command and API-only deploy, not only describe the steps. If the agent has access to browser automation or a browser MCP/tool, it can offer to help 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 4kr setup github-app --deploy again so the new app id and private key reach forkr-api.
After creating the app, install it on the GitHub repositories or organization that Forkr should be able to access. Forkr grants can only narrow repositories and permissions that the GitHub App installation already has. Deployment verification uses the dedicated private repository loopwork/forkr-verify 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 that can be used by boxes you attach it to. 
4kr github grant create work-api \
  --repo example-org/api \
  --repo example-org/shared-lib \
  --permission contents=read \
  --permission pull_requests=write
List grants: 
4kr github grant list
Delete a grant: 
4kr 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: 
4kr github attach my-box work-api
Inspect attached grants: 
4kr github box-grants my-box
Detach the grant: 
4kr github detach my-box work-api

​
Clone through the proxy

4kr github attach configures Git inside the box. It stores the box’s Forkr proxy token in /etc/forkr/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: 
4kr exec my-box -- git clone https://github.com/example-org/api.git /work/api
SSH-style GitHub URLs are rewritten too: 
4kr exec my-box -- git clone git@github.com:example-org/api.git /work/api
The proxy URL shape is an implementation detail: 
https://api.<forkr_domain>/github-proxy/projects/<project>/boxes/<box>/<grant>/<owner>/<repo>.git
For non-default projects, include the project in the attach command: 
4kr github attach my-project:my-box work-api

​
Security properties

Forkr limits blast radius in several places:
  • The GitHub App private key lives in the SOPS-encrypted profile secrets file and the forkr-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 Forkr 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

4kr setup github-app --profile prod --owner example-org --deploy
2

Create a grant

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

Attach the grant

4kr github attach my-box work-api
4

Clone through the proxy

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