# GitHub App (/self-hosting/github-app)





A self-hosted deployment needs its **own** GitHub App. The hosted Mogplex App
sends its webhooks to mogplex.com, not to your deployment.

GitHub has two separate jobs in Mogplex. Configure both:

| Piece            | What it unlocks                                                                                                                                                                        | Variables                                                                                                                                                   |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GitHub App       | Installation-backed repo access, webhooks, check runs, PR reviews, triggers, and automations                                                                                           | `GITHUB_APP_ID`, `GITHUB_APP_NAME`, `GITHUB_APP_PRIVATE_KEY`, `GITHUB_WEBHOOK_SECRET`, and optionally `GITHUB_APP_CLIENT_ID` and `GITHUB_APP_CLIENT_SECRET` |
| GitHub OAuth app | User identity and org membership, used to find and link installations, and reauthorization when a token needs new scopes. Without a GitHub App, it also lists and imports repositories | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`                                                                                                                  |

GitHub *sign-in* (`AUTH_GITHUB_*`) is a third, identity-only setting. See
[Database and auth](/self-hosting/database-and-auth#sign-in-providers).

## Fast path: create the App from your deployment [#fast-path-create-the-app-from-your-deployment]

Mogplex can create the GitHub App for you with GitHub's manifest flow. The
permissions, events, and URLs come from `github-app-manifest.json` in the repo.

1. Leave the `GITHUB_APP_*` variables unset. In production, also set
   `MOGPLEX_SETUP_ENABLED=1`. Outside production the page is always available.
2. Sign in and open `/admin/setup/github`. Optionally enter an organization to
   own the App.
3. Approve the App on GitHub. GitHub returns to `/admin/setup/github/complete`,
   which shows `GITHUB_APP_ID`, `GITHUB_APP_NAME`, `GITHUB_APP_PRIVATE_KEY`, and
   `GITHUB_WEBHOOK_SECRET` **once**. Mogplex does not store them.
4. Copy them into your environment and into Trigger.dev, remove
   `MOGPLEX_SETUP_ENABLED`, and redeploy.

   To let users create repositories in personal accounts, also add the
   [client credentials](#client-credentials-for-personal-repositories) to the
   app environment only, then redeploy. The manifest already registers the
   `/api/auth/github/app-user/callback` callback URL.
5. Create the GitHub OAuth app in [step 3](#3-create-the-github-oauth-app). The
   App's own client credentials cannot replace it.

Then continue with [Install and verify](#4-install-and-verify). The manual
steps below do the same thing by hand.

## 1. Create the GitHub App [#1-create-the-github-app]

Open **GitHub → Settings → Developer settings → GitHub Apps → New GitHub App**.
To create the App under an organization, use the organization's settings.
Enter these values, or paste them from `github-app-manifest.json`.

| Field                            | Value                                                                                                                                                                                                                                                      |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Homepage URL                     | `https://<domain>`                                                                                                                                                                                                                                         |
| Callback URL                     | `https://<domain>/api/auth/github/app-user/callback` (only for [personal repositories](#client-credentials-for-personal-repositories)). Leave **Request user authorization (OAuth) during installation** unchecked: installs return through the Setup URL. |
| Setup URL                        | `https://<domain>/api/auth/github/callback` (also select **Redirect on update**)                                                                                                                                                                           |
| Webhook                          | Active                                                                                                                                                                                                                                                     |
| Webhook URL                      | `https://<domain>/api/webhooks/github`                                                                                                                                                                                                                     |
| Webhook secret                   | A random value. Store the same value as `GITHUB_WEBHOOK_SECRET`.                                                                                                                                                                                           |
| Where can this App be installed? | **Any account**, if users outside your organization will install it                                                                                                                                                                                        |

### Repository permissions [#repository-permissions]

| Permission          | Access         | Used for                                                                                                                                                                     |
| ------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Contents            | Read and write | Clone, push branches, read files                                                                                                                                             |
| Pull requests       | Read and write | Open, update, review, and merge PRs                                                                                                                                          |
| Repository creation | Read and write | Create repositories from Mogplex, in organizations and, with [client credentials](#client-credentials-for-personal-repositories), in personal accounts (optional; see below) |
| Issues              | Read and write | Read and update issues, post comments                                                                                                                                        |
| Checks              | Read and write | The Mogplex PR review check run                                                                                                                                              |
| Commit statuses     | Read and write | Automation `set_status` actions                                                                                                                                              |
| Actions             | Read-only      | Read CI workflow runs and job logs                                                                                                                                           |
| Metadata            | Read-only      | Required by GitHub                                                                                                                                                           |
| Dependabot alerts   | Read-only      | [Dependabot remediation](/integrations/dependabot) (optional)                                                                                                                |

Repository creation is GitHub's narrow alternative to Administration: it
creates repositories without rename, delete, transfer, settings, or access
management. Organization owners must approve it. Leave it out if you never
create repositories from Mogplex. The [fast path](#fast-path-create-the-app-from-your-deployment)
always requests it, because `github-app-manifest.json` includes it; to drop it,
remove it under the App's **Permissions & events** after you create the App.

### Organization permissions [#organization-permissions]

| Permission | Access    | Used for                                 |
| ---------- | --------- | ---------------------------------------- |
| Members    | Read-only | Lists org members when you create a team |

### Subscribe to events [#subscribe-to-events]

* Pull request
* Push
* Issues
* Issue comment
* Pull request review comment
* Commit comment
* Check run
* Workflow run
* Repository
* Dependabot alert (optional, for Dependabot remediation)

GitHub always sends `installation` and `installation_repositories` events to an
App. Mogplex uses those events to keep repository coverage in sync.

### Client credentials for personal repositories [#client-credentials-for-personal-repositories]

This part is optional. Mogplex creates a repository in a personal account with
that user's own App authorization, so it acts as the user there. To let users
do this, copy the **Client ID** from
the App page's **About** section, select **Generate a new client secret**, and
store both in the app environment (Trigger.dev does not need them):

```bash
GITHUB_APP_CLIENT_ID=Iv23...
GITHUB_APP_CLIENT_SECRET=...
```

The App also needs the Repository creation permission and the
`/api/auth/github/app-user/callback` callback URL from the table above. If you
created the App before Mogplex added this callback, add it under **Callback
URL** on the App page.

Mogplex stores each user's authorization and refreshes it in the background.
The authorization lapses only if it goes unused for about six months or the
user revokes the App, and Mogplex then asks them to authorize again. This
assumes user-to-server token expiration is enabled for the App, as it is by
default.

Without these variables, users can create repositories only in organizations.

## 2. Generate a private key [#2-generate-a-private-key]

On the App page, select **Generate a private key**. Store the PEM as
`GITHUB_APP_PRIVATE_KEY`. In a single-line env file, replace each newline with
`\n`.

```bash
GITHUB_APP_ID=123456
GITHUB_APP_NAME=my-mogplex          # the App's URL slug: github.com/apps/<slug>
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIE...\n-----END RSA PRIVATE KEY-----\n"
GITHUB_WEBHOOK_SECRET=...
```

Mogplex treats the App as configured only when `GITHUB_APP_ID`,
`GITHUB_APP_PRIVATE_KEY`, and `GITHUB_APP_NAME` are all set.
`GITHUB_APP_NAME` builds the install link
`https://github.com/apps/<GITHUB_APP_NAME>/installations/new`.

## 3. Create the GitHub OAuth app [#3-create-the-github-oauth-app]

Open **Developer settings → OAuth Apps → New OAuth App**.

| Field                      | Value                                       |
| -------------------------- | ------------------------------------------- |
| Homepage URL               | `https://<domain>`                          |
| Authorization callback URL | `https://<domain>/api/auth/github/callback` |

With a GitHub App configured, Mogplex requests the `read:org`, `read:user`, and
`user:email` scopes. Repository access comes only from App installations. In a
deployment without a GitHub App, Mogplex also requests `repo` so it can list and
import repositories. Store the credentials:

```bash
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
```

<Callout title="One OAuth app for sign-in and the GitHub connection">
  GitHub accepts any redirect path under an OAuth app's callback URL. If you set
  the callback URL to `https://<domain>/api/auth`, one OAuth app serves both
  `/api/auth/github/callback` and GitHub sign-in at
  `/api/auth/callback/github`. Then use the same credentials for
  `GITHUB_CLIENT_*` and `AUTH_GITHUB_*`.
</Callout>

## 4. Install and verify [#4-install-and-verify]

1. Redeploy so the app reads the new variables.
2. Sign in, open **Settings → Account**, and select **Install GitHub App**.
   Install the App on your personal account, or on an organization where you
   are an owner. Mogplex links the installation when GitHub returns you to the
   deployment. Organization members who are not owners cannot link the org
   installation. See
   [Who can link an installation](/web/installations#who-can-link-an-installation).
3. Check the linked installations under **Settings → Account** (see
   [Installations](/web/installations)) and confirm coverage. Then sync
   repositories in **Settings → Repositories** (see [Projects](/web/spaces)).
4. In the App's **Advanced → Recent deliveries**, confirm that deliveries return
   `2xx`. A `401` means `GITHUB_WEBHOOK_SECRET` does not match the App's
   webhook secret.

## Troubleshooting [#troubleshooting]

| Symptom                                                                              | Check                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Connect GitHub** opens an OAuth screen instead of the App install                  | One of `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, or `GITHUB_APP_NAME` is missing.                                                                                                                                  |
| Repos are listed but triggers never fire                                             | The webhook URL points somewhere else, or webhook deliveries fail. Check **Advanced → Recent deliveries**.                                                                                                          |
| An organization does not appear after install                                        | The installation is not linked. An organization owner installs or configures the App so the callback links it. See [An org you belong to does not appear](/web/installations#an-org-you-belong-to-does-not-appear). |
| `invalid_state` after the GitHub redirect                                            | The callback reached a different domain than the one that started the flow. Make `NEXT_PUBLIC_APP_URL` match the public URL.                                                                                        |
| New permissions have no effect                                                       | Each installation must accept the new permissions on GitHub. For repository creation, see [Repository creation failures](#repository-creation-failures).                                                            |
| Creating a repository in an organization fails with "cannot create repositories yet" | GitHub returned `Resource not accessible by integration`. See [Repository creation failures](#repository-creation-failures).                                                                                        |
| Creating a repository in a personal account asks to authorize again                  | `GITHUB_APP_CLIENT_ID` or `GITHUB_APP_CLIENT_SECRET` is missing or wrong, the App has no `/api/auth/github/app-user/callback` callback URL, or the user revoked Mogplex in GitHub **Settings → Applications**.      |

### Repository creation failures [#repository-creation-failures]

Check these in order:

* **Pending permission request.** The organization owner must accept Repository
  creation for the installation. The request shows in the installation's
  settings on GitHub.
* **App created before Mogplex asked for the permission.** Add Repository
  creation under the App's **Permissions & events**. Then the owner accepts it.
* **Organization policy.** If GitHub accepts the permission but creation still
  fails, check that **Settings → Member privileges → Repository creation**
  allows the visibility you chose (public or private). This policy applies to
  GitHub Apps too.
