Infrastructure
Configure a GitHub App for a self-hosted Chalk metadata plane.
Chalk’s GitHub integration lets dashboard users install a GitHub App into their GitHub organization, connect Chalk projects to GitHub repositories, and import repository contents into volumes. The integration is powered by a GitHub App whose credentials are held by the metadata plane (the Chalk API server).
In Chalk Cloud, Chalk operates this app for you. When you self-host the metadata plane, you must register your own GitHub App and configure your API server with its credentials. This page walks metadata-plane administrators through that setup.
The API server authenticates to GitHub as a GitHub App:
No user-level OAuth is involved, and GitHub credentials are never sent to the browser: the dashboard talks only to the API server, which proxies all GitHub API access.
Create a new GitHub App at https://github.com/organizations/<your-org>/settings/apps/new
(or Settings → Developer settings → GitHub Apps → New GitHub App for a
personal account). Configure it as follows:
| Setting | Value |
|---|---|
| GitHub App name | Anything you like, e.g. Acme Chalk. The URL slug GitHub derives from it is used below. |
| Homepage URL | Your dashboard URL, e.g. https://chalk.acme.com |
| Setup URL | https://<your-dashboard-host>/github-redirect |
| Redirect on update | Enabled |
| Webhook | Disabled (the integration does not consume webhooks) |
| Where can this App be installed? | “Only on this account” is sufficient if all of your GitHub repositories live in one organization |
The Setup URL is required: after a user installs the app, GitHub redirects
their browser there with an installation_id, and that page records the
installation with the API server. If it is missing or points at the wrong
host, installs will succeed on GitHub but never appear in Chalk.
Grant the following repository permissions. All are read-only:
| Permission | Access | Used for |
|---|---|---|
| Metadata | Read-only | Listing the repositories an installation can access |
| Contents | Read-only | Listing branches and downloading repository archives for volume imports |
| Pull requests | Read-only | Listing pull requests |
No account permissions or event subscriptions are needed.
After creating the app, scroll to Private keys and click Generate a
private key. GitHub downloads a .pem file.
Keep the key in the format GitHub provides: an RSA (PKCS#1) PEM beginning with
-----BEGIN RSA PRIVATE KEY-----. Do not convert it to PKCS#8
(-----BEGIN PRIVATE KEY-----); the API server only accepts the PKCS#1
format.
Note down from the app’s settings page:
Iv23...)https://github.com/apps/<slug>Provide the app’s identity to the API server through environment variables:
| Environment variable | Required | Description |
|---|---|---|
CHALK_GITHUB_APP_ID | Yes | The numeric App ID |
CHALK_GITHUB_APP_SLUG | Yes | The app’s URL slug; the dashboard’s “Install GitHub App” button links to https://github.com/apps/<slug>/installations/new |
CHALK_GITHUB_APP_PRIVATE_KEY | Yes | The full PEM contents of the private key, including the BEGIN/END lines |
CHALK_GITHUB_APP_CLIENT_ID | No | The app’s client ID |
CHALK_GITHUB_APP_CLIENT_SECRET | No | Reserved for future use; not currently required |
All three required variables must be set together: if only some are present, the API server logs an error at startup and disables the integration (teams with their own explicit configuration are unaffected).
If the API server runs on Kubernetes, the typical pattern is to add the variables to the secret that already backs the API server’s environment:
kubectl -n <api-server-namespace> patch secret <api-server-env-secret> \
--type merge \
-p "$(jq -n --rawfile key chalk-app.private-key.pem '{stringData: {
CHALK_GITHUB_APP_ID: "123456",
CHALK_GITHUB_APP_SLUG: "acme-chalk",
CHALK_GITHUB_APP_CLIENT_ID: "Iv23xxxxxxxxxxxxxxxx",
CHALK_GITHUB_APP_PRIVATE_KEY: $key
}}')"Then restart the API server pods so they pick up the new environment. On a successful boot, the API server logs:
githubapp: default GitHub App enabled from environment
This environment-provided app acts as the default for every team on the
metadata plane. A team can override it with its own GitHub App through the
GitHubAppService/UpsertGitHubAppConfig RPC; an explicit per-team
configuration always takes precedence over the environment default.
https://github.com/apps/<slug>/installations/new; pick an organization
and confirm./github-redirect on your dashboard, which
records the installation and links back to the settings page. The new
installation appears in the Installations list.| Symptom | Likely cause |
|---|---|
failed_precondition: GitHub App not configured for this team | The CHALK_GITHUB_APP_* variables are not visible to the API server process (not set, set on the wrong deployment, or the pods were not restarted after the change), and the team has no explicit configuration. |
githubapp: ignoring invalid default GitHub App env configuration in API server logs | The variables are partially set, or CHALK_GITHUB_APP_ID is not a number. Set all of CHALK_GITHUB_APP_ID, CHALK_GITHUB_APP_SLUG, and CHALK_GITHUB_APP_PRIVATE_KEY. |
| Install completes on GitHub but never appears in the dashboard | The app’s Setup URL does not point at https://<your-dashboard-host>/github-redirect, or the installing user’s browser could not reach the dashboard afterwards. Use Sync from GitHub on the settings page to reconcile. |
| Errors mentioning the private key when listing repositories or completing an installation | The key was converted to PKCS#8. Re-download the key from GitHub (it must begin with -----BEGIN RSA PRIVATE KEY-----), or rotate it and configure the new one. |
| Repository missing from the picker | The installation only grants access to selected repositories. Update the repository selection for the installation on GitHub, then Sync from GitHub. |
To rotate the app’s private key:
CHALK_GITHUB_APP_PRIVATE_KEY wherever the API server’s
environment is managed.Installation tokens are short-lived and re-minted on demand, so no other state needs to change.