# GitHub App Setup
source: https://docs.chalk.ai/docs/github-app-setup

## Configure a GitHub App for an air-gapped Chalk deployment.

Chalk's GitHub integration lets dashboard users install a GitHub App into their
GitHub organization, connect Chalk projects to GitHub repositories, import
repository contents into volumes, and open pull requests from a volume's
contents. A GitHub App powers the integration, and the metadata plane (the
Chalk API server) holds its credentials.

In Chalk Serverless and self-hosted deployments, Chalk operates this app for you.
In an air-gapped deployment, you run the
metadata plane, so you register your own GitHub App and configure your API server
with its credentials. This page walks metadata-plane administrators through
that setup.

### How the integration works

The API server authenticates to GitHub as a GitHub App:

- It signs a short-lived JWT with the app's private key.
- It exchanges that JWT for installation access tokens, scoped to the
GitHub organizations (or user accounts) that installed the app.
- It uses installation tokens to list repositories, branches, and pull
requests, validate project↔repository connections, download repository
archives for volume imports, and push branches and open pull requests from
volumes.

The installing user authorizes the app once during installation so the API
server can confirm they can access the installation; the resulting user token is
discarded after that check. GitHub credentials are never sent to the browser:
the dashboard talks only to the API server, which proxies all GitHub API access.

### Step 1: Register a GitHub App

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**                                        | A name for the app, such as `Acme Chalk`. GitHub derives the app's URL slug from it, and you use the slug in Step 2. |
| **Homepage URL**                                           | Your dashboard URL, such as `https://chalk.acme.com`                                                                 |
| **Redirect URI**                                           | `https:///github-redirect` (GitHub formerly labeled this field Callback URL)                                         |
| **Request user authorization (OAuth) during installation** | Enabled                                                                                                              |
| **Webhook**                                                | Disabled (the integration does not consume webhooks)                                                                 |
| **Where can this App be installed?**                       | "Only on this account" works when all of your GitHub repositories are in one organization                            |

Turning on user authorization during installation clears the Setup URL and
disables the field, so installs redirect to the Redirect URI. If you turn it off
again, you must re-enter the Setup URL.

The Redirect URI is required. GitHub sends the install redirect to it with
the installation_id, the state value from the install link, and an OAuth
code. That page records the installation with the API server, which exchanges
the code to confirm the installing user can access the installation. If the
Redirect URI is missing or points at the wrong host, the installation succeeds
on GitHub but never appears in Chalk.

### Repository permissions

Grant the following repository permissions:

| Permission        | Access                    | Used for                                                                                                                                                                            |
| ----------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Metadata**      | Read-only                 | Listing the repositories an installation can access                                                                                                                                 |
| **Contents**      | Read and write            | Listing branches and downloading repository archives for volume imports (read), and pushing a branch for a pull request opened from a volume (write)                                |
| **Pull requests** | Read and write            | Listing pull requests (read), and opening a pull request from a volume (write)                                                                                                      |
| **Workflows**     | Read and write (optional) | Opening a pull request from a volume when the pull request adds, changes, or deletes files under `.github/workflows/`. Without this permission, GitHub rejects those pull requests. |

A pull request opened from a volume makes the repository match the volume, so
it deletes repository files that are not in the volume. If the repository has
files under .github/workflows/ and the volume does not, the pull request
deletes them and needs the Workflows permission.

No account permissions or event subscriptions are needed.

### Generate a client secret

On the app's settings page, under Client secrets, click Generate a new
client secret and copy it immediately: GitHub shows it only once.

### Generate a private key

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:

- App ID: a number, shown under "About"
- Client ID: a string such as Iv23...
- Client secret: the value you generated above
- Slug: the final path segment of the app's public page,
https://github.com/apps/<slug>

### Step 2: Configure the API server

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//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`     | Yes, for installs | The app's client ID, used to confirm the installing user's access                                                           |
| `CHALK_GITHUB_APP_CLIENT_SECRET` | Yes, for installs | The app's client secret. Without it, or without the client ID, completing an installation fails with `failed_precondition`. |

Set the first three variables together. If only some are present, the API
server logs an error at startup and disables the integration for every team
without its own explicit configuration.

If the API server runs on Kubernetes, 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_CLIENT_SECRET: "<client-secret>",
    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.

### Step 3: Verify

- In the dashboard, open Settings → Team → GitHub. The app card shows
your app's slug and App ID instead of a "not configured" notice.
- Click Install GitHub App. You land on the app's installation page on
GitHub. Pick an organization and confirm.
- GitHub asks you to authorize the app, then redirects back to
/github-redirect on your dashboard, which records the installation and
links back to the settings page. The new installation appears in the
Installations list.
- Connect a project to a repository under Connected projects. On a
volume page, use Import from GitHub to clone a repository into the
volume, or Open pull request to open a pull request from the volume's
contents.

Start every installation with Install GitHub App in the dashboard. The
link it opens carries a signed state value that ties the installation to
your Chalk team, and the link expires after 30 minutes. An installation
started from the app's page on GitHub has no state, and the redirect page
shows Finish this installation from Chalk instead of recording it.

When the app is already installed on the GitHub account, Install GitHub App
opens GitHub's configure page and GitHub does not redirect back to Chalk. To
record an installation that exists on GitHub but not in Chalk, uninstall the app
on GitHub (account or organization Settings → Applications or GitHub Apps →
Configure → Uninstall), then click Install GitHub App in Chalk.

Connecting an installation requires write access to every repository it covers,
so install the app on selected repositories your engineers can write to. An
install on all repositories normally needs an organization owner to connect it.
Members who cannot install the app request it. After an owner approves the
request on GitHub, someone with write access to every covered repository must
connect it from Chalk. If GitHub does not redirect back because the app is
already installed, uninstall it on GitHub first. The app needs no extra
permissions for this check.

### Troubleshooting

| 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`.                                                                                                                                                                                                                                                                                                                                                                                                      |
| The redirect page shows **Finish this installation from Chalk**                                                                                                                  | The installation was started from GitHub instead of from Chalk. Uninstall the app on GitHub (account or organization **Settings → Applications** or **GitHub Apps → Configure → Uninstall**), then click **Install GitHub App** in **Settings → Team → GitHub**. While the app stays installed, GitHub opens its configure page and does not redirect back to Chalk.                                                                                                                                                                                                           |
| `the GitHub installation link is invalid or has expired; start the installation again from Chalk`                                                                                | The install link is more than 30 minutes old, or the private key was rotated after the link was created. Click **Install GitHub App** again.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `the GitHub account "" is already connected to a different Chalk team; disconnect it there first`                                                                                | Each GitHub account can be connected to one Chalk team. Remove the installation from the other team's **Installations** list, then install again.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Install completes on GitHub but never appears in the dashboard                                                                                                                   | The installation exists on GitHub but Chalk never recorded it, because the app's **Redirect URI** does not point at `https:///github-redirect` or the installing user's browser could not reach the dashboard afterwards. Fix the Redirect URI, uninstall the app on GitHub (account or organization **Settings → Applications** or **GitHub Apps → Configure → Uninstall**), then click **Install GitHub App** in Chalk. GitHub does not redirect back while the app is installed. **Refresh from GitHub** updates installations Chalk already has and does not add new ones. |
| `failed_precondition: GitHub App client ID or secret is not configured`                                                                                                          | `CHALK_GITHUB_APP_CLIENT_ID` or `CHALK_GITHUB_APP_CLIENT_SECRET` is not visible to the API server process. Set both and restart the pods.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `invalid_argument: code required`                                                                                                                                                | The app's **Request user authorization (OAuth) during installation** setting is off, so GitHub sent no `code` (or the Chalk frontend is older than the API server and did not forward it; finish the upgrade first). Enable it, uninstall the app on GitHub (account or organization **Settings → Applications** or **GitHub Apps → Configure → Uninstall**), then click **Install GitHub App** in **Settings → Team → GitHub**. While the app stays installed, GitHub opens its configure page and does not redirect back to Chalk.                                           |
| `failed_precondition: GitHub App user authorization is misconfigured`                                                                                                            | The client ID or secret is wrong, or the app's **Redirect URI** does not match the one GitHub expects. Fix the app settings or `CHALK_GITHUB_APP_CLIENT_ID`/`CHALK_GITHUB_APP_CLIENT_SECRET`, restart the pods, uninstall the app on GitHub (account or organization **Settings → Applications** or **GitHub Apps → Configure → Uninstall**), then click **Install GitHub App** in **Settings → Team → GitHub**. While the app stays installed, GitHub opens its configure page and does not redirect back to Chalk.                                                           |
| `permission_denied: GitHub user authorization failed; uninstall the GitHub App on GitHub, then install it again from Chalk` or `the GitHub user cannot access this installation` | The authorization code was already used or expired, or the installing GitHub user cannot access the installation. Uninstall the app on GitHub (account or organization **Settings → Applications** or **GitHub Apps → Configure → Uninstall**), then click **Install GitHub App** in **Settings → Team → GitHub**. While the app stays installed, GitHub opens its configure page and does not redirect back to Chalk.                                                                                                                                                         |
| `permission_denied: connecting this installation requires write access to every repository it covers`                                                                            | The installing GitHub user cannot push to at least one repository the installation covers. Install the app on selected repositories the user can write to, or have a user with write access to every covered repository (such as an organization owner) connect it. Then uninstall the app on GitHub and click **Install GitHub App** in **Settings → Team → GitHub**.                                                                                                                                                                                                         |
| `permission_denied: you can't see every repository this installation covers; connecting requires write access to all of them`                                                    | The installing GitHub user can write to every repository they can see, but cannot see all the repositories the installation covers. Have a user with access to all of them connect it, or install the app on selected repositories, then uninstall and install again from Chalk.                                                                                                                                                                                                                                                                                               |
| `failed_precondition: this installation covers too many repositories to check; install the app on selected repositories instead`                                                 | The installation covers more repositories than Chalk can check. Uninstall the app on GitHub, then install it on selected repositories from Chalk.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `failed_precondition: this GitHub App installation is suspended on GitHub`                                                                                                       | GitHub has suspended the installation. Unsuspend it (**Settings → Applications → Configure**), then uninstall the app and click **Install GitHub App** in Chalk.                                                                                                                                                                                                                                                                                                                                                                                                               |
| `not_found: GitHub does not know installation `                                                                                                                                  | The installation was removed on GitHub before Chalk finished recording it. Click **Install GitHub App** in Chalk again.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `failed_precondition: GitHub refused the repository access check: authorize SSO for the organization on GitHub, then uninstall and install the app again from Chalk`             | GitHub sent an `X-GitHub-SSO` header: the organization requires SAML SSO and the installing user has not authorized it, so GitHub refused or filtered the repository list. Authorize SSO for the organization on GitHub, uninstall the app, then click **Install GitHub App** in Chalk.                                                                                                                                                                                                                                                                                        |
| `unavailable: GitHub had an error completing the installation; uninstall the GitHub App on GitHub, then install it again from Chalk`                                             | GitHub failed after it had already issued the one-time authorization code, so reloading cannot succeed. Uninstall the app on GitHub, then click **Install GitHub App** in **Settings → Team → GitHub**.                                                                                                                                                                                                                                                                                                                                                                        |
| `permission_denied: your GitHub email address is not verified`                                                                                                                   | GitHub refuses authorization for a user without a verified email address. Verify it in your GitHub email settings, then uninstall the app on GitHub and click **Install GitHub App** in Chalk.                                                                                                                                                                                                                                                                                                                                                                                 |
| 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 click **Refresh from GitHub**.                                                                                                                                                                                                                                                                                                                                                                                                              |
| Opening a pull request from a volume fails on files under `.github/workflows/`                                                                                                   | The app does not have the **Workflows** permission. Add it in the app's settings on GitHub, then accept the updated permissions for the installation.                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Key rotation

To rotate the app's private key:

- Generate a new private key on the GitHub App settings page.
- Update CHALK_GITHUB_APP_PRIVATE_KEY wherever the API server's
environment is managed.
- Restart the API server pods.
- Delete the old key on GitHub once the restart is complete.

Installation tokens are short-lived and re-minted on demand, so no other state
needs to change. Install links created before the restart stop working; start
any installation in progress again from the dashboard.





