GitHub App

Create and configure the GitHub App and OAuth app that give a self-hosted Mogplex repository access, webhooks, checks, and PR reviews.

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	Repository listing and import, and reauthorization when a token needs new scopes	`GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`

GitHub sign-in (AUTH_GITHUB_*) is a third, identity-only setting. See Database and auth.

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.

Leave the GITHUB_APP_* variables unset. In production, also set MOGPLEX_SETUP_ENABLED=1. Outside production the page is always available.
Sign in and open /admin/setup/github. Optionally enter an organization to own the App.
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.
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 to the app environment only, then redeploy. The manifest already registers the /api/auth/github/app-user/callback callback URL.
Create the GitHub OAuth app in step 3. The App's own client credentials cannot replace it.

Then continue with Install and verify. The manual steps below do the same thing by hand.

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

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, 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 (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 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

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

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

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):

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

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.

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

Open Developer settings → OAuth Apps → New OAuth App.

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

Mogplex requests the repo, read:org, read:user, and user:email scopes. Store the credentials:

GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...

One OAuth app for sign-in and repo access

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_*.

4. Install and verify

Redeploy so the app reads the new variables.
Sign in, open Settings → Account, and connect GitHub. This installs the App on the accounts or organizations that own your repositories.
Open Installations and confirm coverage. Then sync repositories in Settings → Repositories (see Projects).
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

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 App is not installed on that owner, or the webhook URL points somewhere else.
`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.
Creating a repository in an organization fails with "cannot create repositories yet"	GitHub returned `Resource not accessible by integration`. See 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

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.

Fast path: create the App from your deploymentCopy Anchor Link

1. Create the GitHub AppCopy Anchor Link

Repository permissionsCopy Anchor Link

Organization permissionsCopy Anchor Link

Subscribe to eventsCopy Anchor Link

Client credentials for personal repositoriesCopy Anchor Link

2. Generate a private keyCopy Anchor Link

3. Create the GitHub OAuth appCopy Anchor Link

4. Install and verifyCopy Anchor Link

TroubleshootingCopy Anchor Link

Repository creation failuresCopy Anchor Link

On this page