From c10797deb1ca625676d2496897bad7b31159043a Mon Sep 17 00:00:00 2001
From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com>
Date: Sun, 8 Nov 2026 21:08:37 -0500
Subject: [PATCH 1/7] docs: describe how GitHub App installations link to
Mogplex
---
content/docs/guides/common-use-cases.mdx | 4 +-
content/docs/guides/index.mdx | 2 +-
.../docs/guides/sandbox-setup-checklist.mdx | 2 +-
content/docs/guides/troubleshooting.mdx | 6 +-
content/docs/index.mdx | 3 +-
content/docs/integrations/github.mdx | 80 ++++++-----
content/docs/quickstart.mdx | 8 +-
content/docs/reference/glossary.mdx | 14 +-
.../reference/security-and-data-handling.mdx | 4 +-
.../docs/self-hosting/database-and-auth.mdx | 5 +-
.../self-hosting/environment-variables.mdx | 2 +-
content/docs/self-hosting/github-app.mdx | 21 ++-
.../web/guides/choose-routing-surface.mdx | 7 +-
.../docs/web/guides/github-app-coverage.mdx | 37 ++---
content/docs/web/guides/index.mdx | 2 +-
content/docs/web/guides/project-workflow.mdx | 28 ++--
content/docs/web/index.mdx | 6 +-
.../coverage-and-triggerability.mdx | 62 +++++----
content/docs/web/installations/index.mdx | 131 ++++++++++++------
.../installations/repo-sync-and-rebinding.mdx | 40 ++++--
content/docs/web/settings.mdx | 21 +--
content/docs/web/spaces.mdx | 13 +-
content/docs/web/triggers.mdx | 6 +-
23 files changed, 305 insertions(+), 199 deletions(-)
diff --git a/content/docs/guides/common-use-cases.mdx b/content/docs/guides/common-use-cases.mdx
index a5b50d4..376b10d 100644
--- a/content/docs/guides/common-use-cases.mdx
+++ b/content/docs/guides/common-use-cases.mdx
@@ -171,8 +171,8 @@ Check in this order:
or [Automations](/web/automations)
5. [Observability](/web/observability), but only after a run actually exists
-If the repo is only visible through OAuth, hosted GitHub routing will not be
-healthy yet. Fix App coverage first.
+If the repo owner's GitHub App installation is not linked to you, hosted GitHub
+routing will not be healthy yet. Fix App coverage first.
## Use the hosted API
diff --git a/content/docs/guides/index.mdx b/content/docs/guides/index.mdx
index aacbe64..44a9c19 100644
--- a/content/docs/guides/index.mdx
+++ b/content/docs/guides/index.mdx
@@ -65,7 +65,7 @@ known, but the sequence still matters.
`, or the wrong route is
marked default.
diff --git a/content/docs/quickstart.mdx b/content/docs/quickstart.mdx
index 7ea6a97..b286e5d 100644
--- a/content/docs/quickstart.mdx
+++ b/content/docs/quickstart.mdx
@@ -22,9 +22,11 @@ needs before it can do useful work:
- Slack workspace and channel links if work should start from Slack
- shared connections and MCP definitions, if the repo needs external tools
-If a repo is visible through OAuth but not covered by the GitHub App, hosted
-routing will still fail later. Use [Installations](/web/installations) to
-confirm coverage before debugging triggers or automations. The
+GitHub sign-in alone does not give Mogplex repository access. The repo owner's
+GitHub App installation must be linked to you: install the App on your personal
+account, or on an org where you are an org owner. Use
+[Installations](/web/installations) to confirm coverage before debugging
+triggers or automations. The
[GitHub integration guide](/integrations/github) explains the full setup model.
## 2. Open the repo
diff --git a/content/docs/reference/glossary.mdx b/content/docs/reference/glossary.mdx
index fba1f00..d2ce188 100644
--- a/content/docs/reference/glossary.mdx
+++ b/content/docs/reference/glossary.mdx
@@ -85,9 +85,10 @@ Read next: [Custom Slash Commands](/configure-and-extend/custom-slash-commands).
The state that lets Mogplex receive webhook-backed GitHub events for a user or
organization.
-OAuth visibility can make repos visible in the app, but GitHub App coverage is
-what makes hosted routing healthy for Triggers and Automations. If a repo is
-visible but events do not start work, check App coverage first.
+GitHub sign-in identifies you but grants no repository access. GitHub App
+coverage, from an installation linked to you, is what gives Mogplex repo access
+and makes hosted routing healthy for Triggers and Automations. If a repo is
+missing or events do not start work, check App coverage first.
Read next: [GitHub App Coverage](/web/guides/github-app-coverage).
@@ -155,9 +156,10 @@ Read next: [Projects](/web/spaces).
Whether Mogplex can see a repo through account sync.
-Visibility is not the same as triggerability. A repo can be visible through
-OAuth but still unable to start hosted GitHub-event work until the owning user
-or organization has GitHub App coverage.
+Visibility is not the same as triggerability. With a GitHub App, Mogplex lists
+repos from installations linked to you and repos shared to your team. Only a
+self-hosted deployment without a GitHub App lists repos through GitHub OAuth,
+and those repos cannot start hosted GitHub-event work.
Read next: [GitHub](/integrations/github).
diff --git a/content/docs/reference/security-and-data-handling.mdx b/content/docs/reference/security-and-data-handling.mdx
index e80550d..d610b1b 100644
--- a/content/docs/reference/security-and-data-handling.mdx
+++ b/content/docs/reference/security-and-data-handling.mdx
@@ -13,8 +13,8 @@ when debugging.
Mogplex crosses several systems:
-- GitHub OAuth and the Mogplex GitHub App for identity, repo discovery, and
- webhook-backed routing
+- GitHub OAuth for identity and org membership, and the Mogplex GitHub App for
+ repository access and webhook-backed routing
- managed sandbox access for preview runtimes
- managed model access for hosted execution
- Slack OAuth and webhooks for Slack conversations and repo-agent starts
diff --git a/content/docs/self-hosting/database-and-auth.mdx b/content/docs/self-hosting/database-and-auth.mdx
index 047455b..18a0bb4 100644
--- a/content/docs/self-hosting/database-and-auth.mdx
+++ b/content/docs/self-hosting/database-and-auth.mdx
@@ -97,8 +97,9 @@ ID and secret are set.
| Microsoft | `AUTH_MICROSOFT_CLIENT_ID`, `AUTH_MICROSOFT_CLIENT_SECRET`, `AUTH_MICROSOFT_TENANT_ID` (default `common`) | `https:///api/auth/callback/microsoft` |
| Email and password | Resend (below) | None |
-GitHub sign-in is identity only. Repository access comes from a separate GitHub
-OAuth app and your [GitHub App](/self-hosting/github-app).
+GitHub sign-in is identity only. Repository access comes from your
+[GitHub App](/self-hosting/github-app) installations. A deployment without a
+GitHub App lists repositories through a separate GitHub OAuth app instead.
## Email
diff --git a/content/docs/self-hosting/environment-variables.mdx b/content/docs/self-hosting/environment-variables.mdx
index c491347..54a2b30 100644
--- a/content/docs/self-hosting/environment-variables.mdx
+++ b/content/docs/self-hosting/environment-variables.mdx
@@ -66,7 +66,7 @@ See [Database and auth](/self-hosting/database-and-auth#use-a-least-privilege-ru
| `GITHUB_APP_NAME` | GitHub App slug, as in `github.com/apps/`. |
| `GITHUB_APP_PRIVATE_KEY` | PEM. Write newlines as `\n` in single-line env files. |
| `GITHUB_WEBHOOK_SECRET` | Must match the App's webhook secret. |
-| `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | Classic GitHub OAuth app for repository listing and reauthorization. The GitHub App's own client credentials do not work here. |
+| `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | Classic GitHub OAuth app for user identity, org membership, and reauthorization. Without a GitHub App, it also lists repositories. The GitHub App's own client credentials do not work here. |
| `GITHUB_APP_CLIENT_ID`, `GITHUB_APP_CLIENT_SECRET` | Optional. The App's own OAuth client credentials, used only to create repositories in personal accounts. App service only; Trigger.dev does not need them. Callback: `/api/auth/github/app-user/callback`. See [GitHub App](/self-hosting/github-app#client-credentials-for-personal-repositories). |
| `MOGPLEX_SETUP_ENABLED` | `1` enables `/admin/setup/github` in production while the GitHub App is unconfigured. Remove it after setup. |
diff --git a/content/docs/self-hosting/github-app.mdx b/content/docs/self-hosting/github-app.mdx
index 5466fc6..8f446fb 100644
--- a/content/docs/self-hosting/github-app.mdx
+++ b/content/docs/self-hosting/github-app.mdx
@@ -13,7 +13,7 @@ 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 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).
@@ -155,15 +155,17 @@ Open **Developer settings → OAuth Apps → New OAuth App**.
| Homepage URL | `https://` |
| Authorization callback URL | `https:///api/auth/github/callback` |
-Mogplex requests the `repo`, `read:org`, `read:user`, and `user:email` scopes.
-Store the credentials:
+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=...
```
-
+
GitHub accepts any redirect path under an OAuth app's callback URL. If you set
the callback URL to `https:///api/auth`, one OAuth app serves both
`/api/auth/github/callback` and GitHub sign-in at
@@ -174,8 +176,12 @@ GITHUB_CLIENT_SECRET=...
## 4. Install and verify
1. Redeploy so the app reads the new variables.
-2. Sign in, open **Settings → Account**, and connect GitHub. This installs the
- App on the accounts or organizations that own your repositories.
+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. Open [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
@@ -187,7 +193,8 @@ GITHUB_CLIENT_SECRET=...
| 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. |
+| 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). |
diff --git a/content/docs/web/guides/choose-routing-surface.mdx b/content/docs/web/guides/choose-routing-surface.mdx
index 2b5851c..9c2df61 100644
--- a/content/docs/web/guides/choose-routing-surface.mdx
+++ b/content/docs/web/guides/choose-routing-surface.mdx
@@ -17,8 +17,7 @@ Answer these questions first:
1. is the source of truth a GitHub App installation event, one repo, or a
workflow graph?
-2. does the repo owner already have GitHub App coverage, or is it only synced
- through OAuth?
+2. is the repo owner's GitHub App installation linked to you yet?
3. do you need draft and publish control, or should the route be live as soon
as it is created?
4. is this standing responsibility for one repo, or policy for an installation?
@@ -49,8 +48,8 @@ Use Triggers when you want the smallest routing surface that still works.
Two prerequisite details matter:
- Triggers are installation-scoped, so GitHub App coverage is required.
-- Seeing a repo in [Projects](/web/spaces) is not enough if that repo is only
- synced through OAuth.
+- GitHub sign-in alone is not enough. The installation for the repo owner must
+ be linked to you.
If the trigger form has no usable installations, stop and fix App coverage
before debugging the agent.
diff --git a/content/docs/web/guides/github-app-coverage.mdx b/content/docs/web/guides/github-app-coverage.mdx
index a241cca..a46fdfe 100644
--- a/content/docs/web/guides/github-app-coverage.mdx
+++ b/content/docs/web/guides/github-app-coverage.mdx
@@ -1,32 +1,34 @@
---
title: GitHub App Coverage
-description: Understand the difference between GitHub OAuth and GitHub App coverage, and verify why a repo is or is not triggerable.
+description: Understand the difference between GitHub sign-in and GitHub App coverage, and verify why a repo is or is not triggerable.
---
Most confusion in Mogplex setup comes from mixing up two different GitHub
states:
-- **GitHub connected** through OAuth
-- **GitHub App installed** for the account or org that owns the repo
+- **GitHub connected** through GitHub sign-in
+- **GitHub App installed** for the account or org that owns the repo, with the
+ installation linked to you
They are related, but they do different jobs.
-## OAuth vs App coverage
+## Sign-in vs App coverage
-GitHub OAuth gives Mogplex your user identity and basic account connection.
+GitHub sign-in gives Mogplex your user identity and your org memberships. It
+does not grant repository access.
-GitHub App coverage determines which repos Mogplex can treat as triggerable for
-webhook-backed work such as [Triggers](/web/triggers) and
-[Automations](/web/automations).
-
-That means a repo can be visible in [Projects](/web/spaces) but still not be
-usable for triggered routing if the App is not installed for that owner.
+GitHub App coverage determines which repos Mogplex can access, and which it can
+treat as triggerable for webhook-backed work such as [Triggers](/web/triggers)
+and [Automations](/web/automations). Coverage comes from an installation linked
+to you: on your personal account, or on an org where you are an org owner. Org
+members who are not owners use team-shared repositories instead. See
+[Who can link an installation](/web/installations#who-can-link-an-installation).
## Common symptoms of missing App coverage
- Triggers is empty even though GitHub is connected
- Automations cannot find the installation or repo you expect
-- A repo appears in Projects, but GitHub-backed routing is unavailable
+- An org you belong to is missing from Settings
- Settings shows GitHub connected, but installation coverage is missing or for
the wrong owner
@@ -45,14 +47,17 @@ confirm the App is installed where you think it is.
## What to do next
-If GitHub is connected but the App is not installed for the repo owner:
+If GitHub is connected but no installation is linked to you for the repo owner:
-1. Install the Mogplex GitHub App for that owner
+1. Install or configure the Mogplex GitHub App for that owner. For an org, an
+ org owner must do this. See
+ [An org you belong to does not appear](/web/installations#an-org-you-belong-to-does-not-appear).
2. Return to [Settings](/web/settings) and refresh the installation state
3. Go back to [Projects](/web/spaces) and sync repos again
4. Re-check [Triggers](/web/triggers) or [Automations](/web/automations)
## Rule of thumb
-If the question is "why can Mogplex see this repo but not route webhook work
-for it?", the answer is usually App coverage, not OAuth.
+If the question is "why can't Mogplex use this repo or route webhook work for
+it?", the answer is usually an installation that is not linked to you, not
+GitHub sign-in.
diff --git a/content/docs/web/guides/index.mdx b/content/docs/web/guides/index.mdx
index e655e4d..d54f296 100644
--- a/content/docs/web/guides/index.mdx
+++ b/content/docs/web/guides/index.mdx
@@ -20,7 +20,7 @@ not just route-by-route descriptions.
Date: Sun, 8 Nov 2026 21:43:08 -0500
Subject: [PATCH 2/7] docs: fix webhook linking rule and Not covered label
wording
---
.../installations/coverage-and-triggerability.mdx | 11 +++++------
.../web/installations/repo-sync-and-rebinding.mdx | 14 ++++++++------
2 files changed, 13 insertions(+), 12 deletions(-)
diff --git a/content/docs/web/installations/coverage-and-triggerability.mdx b/content/docs/web/installations/coverage-and-triggerability.mdx
index 5ceea7e..9290b2f 100644
--- a/content/docs/web/installations/coverage-and-triggerability.mdx
+++ b/content/docs/web/installations/coverage-and-triggerability.mdx
@@ -64,14 +64,13 @@ Each repo effectively falls into one of these buckets:
| --- | --- |
| `Trigger-ready` | The repo has a `github_installation_id` and can participate in App-backed routing |
| `Synced only` | The repo is in Projects, but has no App coverage |
-| `Not covered` | The App is installed somewhere for the user, but not for this repo's owner or scope |
+| `Not covered` | An installation is linked to you, but none of your linked installations covers this repo |
With a GitHub App, once an installation is linked to you, Mogplex lists only
repos covered by a linked installation, so listed repos are `Trigger-ready`.
`Synced only` appears in a self-hosted deployment without a GitHub App, or for
-older repo rows while no installation is linked to you. `Not covered` marks an
-older repo row whose owner has no installation linked to you; Mogplex hides
-those rows from the repo list.
+older repo rows while no installation is linked to you. With a GitHub App,
+Mogplex hides `Not covered` rows from the repo list.
This is the state that matters when the question is "will this route wake up?"
@@ -115,8 +114,8 @@ When coverage is missing or wrong, users usually see one of these:
- Automations cannot find the installation they expect
- an org you belong to is missing from Settings
- Settings says GitHub is connected, but the status is still `OAuth only`
-- Settings shows an App installation, but the repo you care about is still
- `Synced only` or `Not covered`
+- Settings shows an App installation, but the repo you care about is missing
+ from Projects
## Mental model
diff --git a/content/docs/web/installations/repo-sync-and-rebinding.mdx b/content/docs/web/installations/repo-sync-and-rebinding.mdx
index f958761..4218153 100644
--- a/content/docs/web/installations/repo-sync-and-rebinding.mdx
+++ b/content/docs/web/installations/repo-sync-and-rebinding.mdx
@@ -93,15 +93,17 @@ The important webhook-backed update paths are:
and suspend
- `installation_repositories` events when repos are added to or removed from an
installation
-
-Only `installation` events for `created`, `new_permissions_accepted`, and
-`unsuspend`, and `installation_repositories` events for `added`, link an
-installation. A repository admin who adds one repo to an installation is not
-linked to it. See
-[How an installation gets linked](/web/installations#how-an-installation-gets-linked).
- `repository` events such as create, rename, transfer, visibility changes, and
delete
+Some of these events also link an installation: `installation` events for
+`created`, `new_permissions_accepted`, and `unsuspend`, and
+`installation_repositories` events for `added`. Each one links the installation
+to the Mogplex user who made the change, if that user owns the account. A
+repository admin who adds one repo to an org installation does not own the org,
+so that event does not link the installation. See
+[How an installation gets linked](/web/installations#how-an-installation-gets-linked).
+
## Rebinding stale trigger and automation state
Automations and triggers are installation-scoped too.
From ce4d76b8e9a1441a18b66880a40759b7663e24ce Mon Sep 17 00:00:00 2001
From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com>
Date: Sun, 8 Nov 2026 23:38:44 -0500
Subject: [PATCH 3/7] docs: replace remaining visible-but-not-triggerable
wording
---
content/docs/configure-and-extend/index.mdx | 2 +-
content/docs/guides/troubleshooting.mdx | 7 ++++---
.../docs/platform/how-mogplex-fits-together.mdx | 15 +++++++++------
content/docs/reference/glossary.mdx | 8 ++++----
content/docs/self-hosting/database-and-auth.mdx | 4 +++-
content/docs/support.mdx | 2 +-
.../docs/web/guides/choose-routing-surface.mdx | 2 +-
content/docs/web/guides/project-workflow.mdx | 8 ++++----
content/docs/web/index.mdx | 7 ++++---
.../installations/coverage-and-triggerability.mdx | 6 +++---
.../web/installations/repo-sync-and-rebinding.mdx | 4 ++--
content/docs/web/settings.mdx | 12 +++++-------
12 files changed, 41 insertions(+), 36 deletions(-)
diff --git a/content/docs/configure-and-extend/index.mdx b/content/docs/configure-and-extend/index.mdx
index ce46a4c..18898c0 100644
--- a/content/docs/configure-and-extend/index.mdx
+++ b/content/docs/configure-and-extend/index.mdx
@@ -94,7 +94,7 @@ team, or local workflow needs.
- Agent tools are missing or too broad: start with
[Connections and MCP](/configure-and-extend/connections-and-mcp), then check
[Connection Scope and Overrides](/web/guides/connection-scope-and-overrides).
-- Repo is visible but cannot trigger hosted work: start with
+- A repo is missing or cannot trigger hosted work: start with
[GitHub](/integrations/github) and [Installations](/web/installations).
- Sandbox launch reports missing access: start with
[Plans & Billing](/plans-and-billing), then confirm repo settings in
diff --git a/content/docs/guides/troubleshooting.mdx b/content/docs/guides/troubleshooting.mdx
index 48472a5..ea835f7 100644
--- a/content/docs/guides/troubleshooting.mdx
+++ b/content/docs/guides/troubleshooting.mdx
@@ -14,7 +14,7 @@ work started.
| Symptom | Most likely layer |
| --- | --- |
| Repo is missing or stale | installation not linked to you, account sync, or Projects |
-| Repo is visible but GitHub events do not fire | GitHub App coverage |
+| GitHub events do not fire for a repo | linked installation or route binding |
| Mention does not route | agent slug, default mention route, or route enabled state |
| Slack mention replies but does not start repo work | Slack channel link, user mapping, repo-agent enabled state, or workspace limits |
| Route exists but no run appears | route source, coverage, enabled state, or published automation |
@@ -41,9 +41,10 @@ work started.
9. Check [Worktrees](/web/worktrees) when a planned coding task uses an
isolated checkout.
-## Repo is visible but events do not fire
+## GitHub events do not fire
-Visibility and triggerability are different.
+Events start work only for repos covered by an installation linked to you, and
+only through a route bound to that installation or repo.
1. Open [Installations](/web/installations).
2. Confirm the repo owner's Mogplex GitHub App installation is linked to you.
diff --git a/content/docs/platform/how-mogplex-fits-together.mdx b/content/docs/platform/how-mogplex-fits-together.mdx
index 9b7f621..f1088a3 100644
--- a/content/docs/platform/how-mogplex-fits-together.mdx
+++ b/content/docs/platform/how-mogplex-fits-together.mdx
@@ -27,7 +27,7 @@ Each object answers a different question.
| Object | Owns | Start here when |
| --- | --- | --- |
| Account state | Identity, managed model and sandbox access, CLI tokens, model defaults, Slack installs, connections, MCP definitions | sign-in, model, billing, token, Slack, or connection state looks wrong |
-| GitHub installation | App-backed coverage for one GitHub user or org | repos are visible but GitHub events do not trigger work |
+| GitHub installation | App-backed coverage for one GitHub user or org | repos are missing or GitHub events do not trigger work |
| Repo | Imported repository state and repo-specific settings | the target repo is missing, duplicated, hidden, or needs runtime settings |
| Agent | Reusable behavior, slug, prompt, model, skills, rules, and context | the worker itself behaves wrong or a mention slug does not resolve |
| Route | The rule that decides what wakes work | the wrong event, repo, or workflow starts work |
@@ -60,13 +60,16 @@ Each object answers a different question.
### Visibility vs triggerability
-Repo visibility means Mogplex can see a repo through account sync.
+Repo visibility means Mogplex lists a repo. With a GitHub App, Mogplex lists
+repos from installations linked to you and repos shared to your team.
-Triggerability means the owning GitHub user or org has App-backed coverage, so
-GitHub webhook events can start hosted work.
+Triggerability means the owning GitHub user or org has App-backed coverage, and
+a route is bound to that installation or repo, so GitHub webhook events can
+start hosted work.
-A repo can be visible without being triggerable. When that happens, fix
-[GitHub App coverage](/web/guides/github-app-coverage) before editing routes.
+If a repo is missing, fix [GitHub App coverage](/web/guides/github-app-coverage).
+If a listed repo does not trigger, check the route's installation binding
+before editing the agent.
### Agent definition vs route binding
diff --git a/content/docs/reference/glossary.mdx b/content/docs/reference/glossary.mdx
index d2ce188..73cae78 100644
--- a/content/docs/reference/glossary.mdx
+++ b/content/docs/reference/glossary.mdx
@@ -224,11 +224,11 @@ Read next: [Triggers](/web/triggers).
## Triggerability
-Whether a visible repo can actually start hosted GitHub-event work.
+Whether a repo can actually start hosted GitHub-event work.
-Triggerability requires the right GitHub App coverage. If a repo appears in
-Projects but Triggers or Automations do not fire, debug triggerability before
-changing the agent.
+Triggerability requires the right GitHub App coverage and a route bound to the
+installation that owns the event. If Triggers or Automations do not fire for a
+repo, debug triggerability before changing the agent.
Read next: [Coverage and Triggerability](/web/installations/coverage-and-triggerability).
diff --git a/content/docs/self-hosting/database-and-auth.mdx b/content/docs/self-hosting/database-and-auth.mdx
index 18a0bb4..a7120ae 100644
--- a/content/docs/self-hosting/database-and-auth.mdx
+++ b/content/docs/self-hosting/database-and-auth.mdx
@@ -97,7 +97,9 @@ ID and secret are set.
| Microsoft | `AUTH_MICROSOFT_CLIENT_ID`, `AUTH_MICROSOFT_CLIENT_SECRET`, `AUTH_MICROSOFT_TENANT_ID` (default `common`) | `https:///api/auth/callback/microsoft` |
| Email and password | Resend (below) | None |
-GitHub sign-in is identity only. Repository access comes from your
+GitHub sign-in is identity only. Org membership, which Mogplex uses to find and
+link installations, comes from the GitHub connection through the separate
+GitHub OAuth app (`GITHUB_CLIENT_*`). Repository access comes from your
[GitHub App](/self-hosting/github-app) installations. A deployment without a
GitHub App lists repositories through a separate GitHub OAuth app instead.
diff --git a/content/docs/support.mdx b/content/docs/support.mdx
index 60ce8e9..a075e05 100644
--- a/content/docs/support.mdx
+++ b/content/docs/support.mdx
@@ -14,7 +14,7 @@ repo coverage, routing, execution, and local CLI state.
| Symptom | Start here |
| --- | --- |
| A charge, invoice, credit balance, payment method, or due date looks wrong | [Plans & Billing](/plans-and-billing), then email [support@mogplex.com](mailto:support@mogplex.com) |
-| Repo is visible but GitHub events do not start work | [GitHub](/integrations/github) and [Installations](/web/installations) |
+| A repo is missing or GitHub events do not start work | [GitHub](/integrations/github) and [Installations](/web/installations) |
| A model is missing from a picker or CLI run | [Available Models](/web/models) and [Model Selection and Cost](/guides/model-selection-and-cost) |
| Hosted run cannot call an external service | [Connections and MCP](/configure-and-extend/connections-and-mcp) and [Connection Scope and Overrides](/web/guides/connection-scope-and-overrides) |
| Slack mention does not start repo work | [Slack](/integrations/slack), [Settings](/web/settings#slack), and [Observability Runbook](/guides/observability-runbook) |
diff --git a/content/docs/web/guides/choose-routing-surface.mdx b/content/docs/web/guides/choose-routing-surface.mdx
index 9c2df61..6bcbcb8 100644
--- a/content/docs/web/guides/choose-routing-surface.mdx
+++ b/content/docs/web/guides/choose-routing-surface.mdx
@@ -93,7 +93,7 @@ If you need branching, publish control, or a workflow that spans multiple
steps, use Automations.
The setup nuance is the same as Triggers: Automations are installation-scoped
-and need GitHub App coverage, not just synced repos.
+and need GitHub App coverage on the installation that owns the event.
The operating nuance is different: the draft graph is not the live route until
you publish it.
diff --git a/content/docs/web/guides/project-workflow.mdx b/content/docs/web/guides/project-workflow.mdx
index 0acd135..18847f6 100644
--- a/content/docs/web/guides/project-workflow.mdx
+++ b/content/docs/web/guides/project-workflow.mdx
@@ -135,10 +135,10 @@ Once the repo is imported, choose the lightest surface that matches the job:
- Use [Automations](/web/automations) when you need branching, multiple steps,
or publish control
-For webhook-backed routing, make sure the repo is App-covered, not just synced.
-
-That is the most common setup miss when a repo looks available in Projects but
-still will not wake Triggers or Automations.
+For webhook-backed routing, confirm the route is bound to the installation or
+repo that owns the event. A repo can be covered while the route points at a
+different installation, or at a stale installation id. See
+[Repo Sync and Rebinding](/web/installations/repo-sync-and-rebinding).
## 8. Watch it in Observability
diff --git a/content/docs/web/index.mdx b/content/docs/web/index.mdx
index 96e30ec..f280585 100644
--- a/content/docs/web/index.mdx
+++ b/content/docs/web/index.mdx
@@ -146,9 +146,10 @@ For the full redirect map, use [Legacy Routes](/web/guides/legacy-routes).
- **Why is Triggers empty?** Usually because GitHub is connected but no Mogplex
GitHub App installation is linked to you for the owner that holds the repo.
Check [Installations](/web/installations).
-- **Why can I see repos but not launch the kind of work I want?** Repo sync and
- webhook coverage are separate concerns. Projects can show synced repos before
- they are fully triggerable.
+- **Why is a repo missing from Projects, or why do Triggers not fire for it?**
+ The repo owner's installation is not linked to you, or the repo is not shared
+ to your Mogplex team. If the repo is listed but a route does not fire, check
+ that the route is bound to the installation that owns the event.
- **Where do I set up models and external tools?** Use
[Settings](/web/settings) for account access,
[Connections](/configure-and-extend/connections-and-mcp) for external services, and
diff --git a/content/docs/web/installations/coverage-and-triggerability.mdx b/content/docs/web/installations/coverage-and-triggerability.mdx
index 9290b2f..e7b63dd 100644
--- a/content/docs/web/installations/coverage-and-triggerability.mdx
+++ b/content/docs/web/installations/coverage-and-triggerability.mdx
@@ -64,13 +64,13 @@ Each repo effectively falls into one of these buckets:
| --- | --- |
| `Trigger-ready` | The repo has a `github_installation_id` and can participate in App-backed routing |
| `Synced only` | The repo is in Projects, but has no App coverage |
-| `Not covered` | An installation is linked to you, but none of your linked installations covers this repo |
With a GitHub App, once an installation is linked to you, Mogplex lists only
repos covered by a linked installation, so listed repos are `Trigger-ready`.
`Synced only` appears in a self-hosted deployment without a GitHub App, or for
-older repo rows while no installation is linked to you. With a GitHub App,
-Mogplex hides `Not covered` rows from the repo list.
+older repo rows while no installation is linked to you. With a GitHub App, once
+an installation is linked to you, Mogplex hides repos that none of your linked
+installations covers.
This is the state that matters when the question is "will this route wake up?"
diff --git a/content/docs/web/installations/repo-sync-and-rebinding.mdx b/content/docs/web/installations/repo-sync-and-rebinding.mdx
index 4218153..0bc2a99 100644
--- a/content/docs/web/installations/repo-sync-and-rebinding.mdx
+++ b/content/docs/web/installations/repo-sync-and-rebinding.mdx
@@ -144,8 +144,8 @@ sync or binding problem, not a prompt problem.
1. Check [Settings](/web/settings) to confirm the right installation exists for
the repo owner
-2. Check [Projects](/web/spaces) to confirm the repo is App-covered, not just
- visible
+2. Check [Projects](/web/spaces) to confirm the repo is listed. With a GitHub
+ App, a listed repo is covered by an installation linked to you
3. Re-run repo sync if coverage recently changed
4. Re-test the exact GitHub event that should wake the route
5. Use [Observability](/web/observability) to confirm whether the event reached
diff --git a/content/docs/web/settings.mdx b/content/docs/web/settings.mdx
index 24cf1ec..ec26a5b 100644
--- a/content/docs/web/settings.mdx
+++ b/content/docs/web/settings.mdx
@@ -181,10 +181,8 @@ For each installation, Mogplex can show:
- a GitHub manage link when one can be derived
- the list of synced repos under that installation
-This is the fastest way to answer a common setup problem:
-
-**Can Mogplex merely see this repo, or is it actually covered for App-backed
-work?**
+Use it to confirm that the App is installed on the right owner and that the
+installation is linked to you.
## Connections
@@ -371,9 +369,9 @@ models, and repo-level exclusions.
Slack section of **Connections**.
- **Sandbox launch says access is unavailable**: check the account plan and
entitlement state before changing repo settings.
-- **The repo is visible, but webhook-backed work still does not fire**:
- visibility and App-backed coverage are different states. Check the
- installation list here first.
+- **A repo is missing, or webhook-backed work does not fire for it**: the repo
+ owner's installation may not be linked to you. Check the installation list
+ here first.
## Why Settings matters
From 8c826133d26df512bf24be551b53e450c58e8333 Mon Sep 17 00:00:00 2001
From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com>
Date: Mon, 9 Nov 2026 06:04:51 -0500
Subject: [PATCH 4/7] docs: document the Not covered repo label and reword
triggers coverage hint
---
.../coverage-and-triggerability.mdx | 16 ++++++++++------
content/docs/web/triggers.mdx | 4 ++--
2 files changed, 12 insertions(+), 8 deletions(-)
diff --git a/content/docs/web/installations/coverage-and-triggerability.mdx b/content/docs/web/installations/coverage-and-triggerability.mdx
index e7b63dd..c2137b4 100644
--- a/content/docs/web/installations/coverage-and-triggerability.mdx
+++ b/content/docs/web/installations/coverage-and-triggerability.mdx
@@ -63,14 +63,18 @@ Each repo effectively falls into one of these buckets:
| Repo label | Meaning |
| --- | --- |
| `Trigger-ready` | The repo has a `github_installation_id` and can participate in App-backed routing |
-| `Synced only` | The repo is in Projects, but has no App coverage |
+| `Synced only` | The repo is in Projects, but has no App coverage and no installation is linked to you |
+| `Not covered` | An installation is linked to you, but none of your linked installations covers this repo |
+
+With a GitHub App, once an installation is linked to you, the Projects list
+shows only repos covered by a linked installation, so listed repos are
+`Trigger-ready`. Repos that no linked installation covers are hidden from the
+list. You see them as `Not covered` only when you open one directly or show
+hidden repos. To fix it, add the repo to the installation on GitHub, or install
+the App on the account that owns it.
-With a GitHub App, once an installation is linked to you, Mogplex lists only
-repos covered by a linked installation, so listed repos are `Trigger-ready`.
`Synced only` appears in a self-hosted deployment without a GitHub App, or for
-older repo rows while no installation is linked to you. With a GitHub App, once
-an installation is linked to you, Mogplex hides repos that none of your linked
-installations covers.
+older repo rows while no installation is linked to you.
This is the state that matters when the question is "will this route wake up?"
diff --git a/content/docs/web/triggers.mdx b/content/docs/web/triggers.mdx
index d16f41e..65a13a9 100644
--- a/content/docs/web/triggers.mdx
+++ b/content/docs/web/triggers.mdx
@@ -68,8 +68,8 @@ form says no installations are available, check
Mogplex GitHub App installed and the installation is linked to you.
The creation form searches installations by both account scope and synced repos,
-so this page is often the fastest way to notice that repos are synced but still
-not webhook-covered.
+so this page is often the fastest way to notice that a repo is in Projects but
+no linked installation covers it.
## How to create a good trigger
From 758016bed2d1896731256c7d27a896a68d4d8d25 Mon Sep 17 00:00:00 2001
From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com>
Date: Mon, 9 Nov 2026 06:08:11 -0500
Subject: [PATCH 5/7] docs: cover team-shared repos in the repo coverage model
---
.../coverage-and-triggerability.mdx | 32 ++++++++++---------
.../installations/repo-sync-and-rebinding.mdx | 3 +-
2 files changed, 19 insertions(+), 16 deletions(-)
diff --git a/content/docs/web/installations/coverage-and-triggerability.mdx b/content/docs/web/installations/coverage-and-triggerability.mdx
index c2137b4..ff5697f 100644
--- a/content/docs/web/installations/coverage-and-triggerability.mdx
+++ b/content/docs/web/installations/coverage-and-triggerability.mdx
@@ -58,23 +58,24 @@ These are account signals, not repo signals.
### Repo-level coverage state
-Each repo effectively falls into one of these buckets:
+Mogplex tracks each repo's coverage as one of these states:
-| Repo label | Meaning |
+| State | Meaning |
| --- | --- |
-| `Trigger-ready` | The repo has a `github_installation_id` and can participate in App-backed routing |
-| `Synced only` | The repo is in Projects, but has no App coverage and no installation is linked to you |
-| `Not covered` | An installation is linked to you, but none of your linked installations covers this repo |
+| `Trigger-ready` | The repo has a `github_installation_id`, from an installation linked to you or from the teammate who shared the repo to your team, and can participate in App-backed routing |
+| `Synced only` | The repo has no installation id, and no installation is linked to you |
+| `Not covered` | An installation is linked to you, but the repo has no installation id |
-With a GitHub App, once an installation is linked to you, the Projects list
-shows only repos covered by a linked installation, so listed repos are
-`Trigger-ready`. Repos that no linked installation covers are hidden from the
-list. You see them as `Not covered` only when you open one directly or show
-hidden repos. To fix it, add the repo to the installation on GitHub, or install
-the App on the account that owns it.
+Projects does not show these labels. It uses them to decide what to list. Once
+an installation is linked to you, Projects lists only repos that have an
+installation id, whether it comes from your own installation or from the
+teammate who shared the repo. Repos without one stay out of the list, unless
+none of your repos has one. If a repo you expect is missing, add it to the
+installation on GitHub, or install the App on the account that owns it.
-`Synced only` appears in a self-hosted deployment without a GitHub App, or for
-older repo rows while no installation is linked to you.
+While no installation is linked to you, Projects lists every repo you can use,
+including `Synced only` repos. That is the normal state in a self-hosted
+deployment without a GitHub App.
This is the state that matters when the question is "will this route wake up?"
@@ -134,8 +135,9 @@ If the question is about routing, coverage is the thing that matters.
1. Check [Settings](/web/settings) and read the current GitHub status label
2. Confirm the expected owner or org appears in [Installations](/web/installations)
-3. Check whether the repo is actually `Trigger-ready` in
- [Projects](/web/spaces)
+3. Check that the repo is listed in [Projects](/web/spaces), then use
+ [Repo-level coverage state](#repo-level-coverage-state) to read what the
+ list tells you
4. If the App install recently changed, reopen **Settings → Account** so
discovery runs, or rerun repo sync
5. Retry the exact GitHub event you expect, then confirm it in
diff --git a/content/docs/web/installations/repo-sync-and-rebinding.mdx b/content/docs/web/installations/repo-sync-and-rebinding.mdx
index 0bc2a99..ace07d0 100644
--- a/content/docs/web/installations/repo-sync-and-rebinding.mdx
+++ b/content/docs/web/installations/repo-sync-and-rebinding.mdx
@@ -145,7 +145,8 @@ sync or binding problem, not a prompt problem.
1. Check [Settings](/web/settings) to confirm the right installation exists for
the repo owner
2. Check [Projects](/web/spaces) to confirm the repo is listed. With a GitHub
- App, a listed repo is covered by an installation linked to you
+ App, a listed repo is covered by an installation linked to you, or by the
+ installation of the teammate who shared it
3. Re-run repo sync if coverage recently changed
4. Re-test the exact GitHub event that should wake the route
5. Use [Observability](/web/observability) to confirm whether the event reached
From ca47751ba7e89c12bfb727fc8295a9fd72442925 Mon Sep 17 00:00:00 2001
From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com>
Date: Mon, 9 Nov 2026 06:10:53 -0500
Subject: [PATCH 6/7] docs: attribute org membership to the GitHub connection
and state the member trigger path
---
content/docs/guides/troubleshooting.mdx | 2 +-
content/docs/integrations/github.mdx | 8 +++++---
content/docs/reference/glossary.mdx | 2 +-
content/docs/web/guides/github-app-coverage.mdx | 5 +++--
.../installations/coverage-and-triggerability.mdx | 11 +++++++----
content/docs/web/installations/index.mdx | 15 +++++++++++----
content/docs/web/settings.mdx | 5 +++--
content/docs/web/triggers.mdx | 6 ++++++
8 files changed, 37 insertions(+), 17 deletions(-)
diff --git a/content/docs/guides/troubleshooting.mdx b/content/docs/guides/troubleshooting.mdx
index ea835f7..118ef3e 100644
--- a/content/docs/guides/troubleshooting.mdx
+++ b/content/docs/guides/troubleshooting.mdx
@@ -13,7 +13,7 @@ work started.
| Symptom | Most likely layer |
| --- | --- |
-| Repo is missing or stale | installation not linked to you, account sync, or Projects |
+| Repo is missing or stale | installation not linked to you, repo not shared to your team, or repo sync |
| GitHub events do not fire for a repo | linked installation or route binding |
| Mention does not route | agent slug, default mention route, or route enabled state |
| Slack mention replies but does not start repo work | Slack channel link, user mapping, repo-agent enabled state, or workspace limits |
diff --git a/content/docs/integrations/github.mdx b/content/docs/integrations/github.mdx
index 32f7d85..e43b838 100644
--- a/content/docs/integrations/github.mdx
+++ b/content/docs/integrations/github.mdx
@@ -7,12 +7,14 @@ GitHub is the first integration most Mogplex accounts need.
It does two separate jobs:
-- GitHub sign-in identifies you and reads your org memberships
+- the GitHub connection (GitHub OAuth) identifies your GitHub account and reads
+ your org memberships
- the Mogplex GitHub App gives Mogplex access to repositories and sends the
webhooks that start work
-Repository access comes only from a Mogplex GitHub App installation that is
-linked to you. GitHub sign-in never grants repository access on its own.
+Repository access comes from a Mogplex GitHub App installation that is linked
+to you, or from repositories a teammate has shared to your Mogplex team. Neither
+GitHub sign-in nor the GitHub connection grants repository access on its own.
## Setup order
diff --git a/content/docs/reference/glossary.mdx b/content/docs/reference/glossary.mdx
index 73cae78..4804cfb 100644
--- a/content/docs/reference/glossary.mdx
+++ b/content/docs/reference/glossary.mdx
@@ -154,7 +154,7 @@ Read next: [Projects](/web/spaces).
## Repo visibility
-Whether Mogplex can see a repo through account sync.
+Whether a repo appears in Projects for you.
Visibility is not the same as triggerability. With a GitHub App, Mogplex lists
repos from installations linked to you and repos shared to your team. Only a
diff --git a/content/docs/web/guides/github-app-coverage.mdx b/content/docs/web/guides/github-app-coverage.mdx
index a46fdfe..4437823 100644
--- a/content/docs/web/guides/github-app-coverage.mdx
+++ b/content/docs/web/guides/github-app-coverage.mdx
@@ -14,8 +14,9 @@ They are related, but they do different jobs.
## Sign-in vs App coverage
-GitHub sign-in gives Mogplex your user identity and your org memberships. It
-does not grant repository access.
+The GitHub connection (GitHub OAuth) gives Mogplex your GitHub identity and
+your org memberships. It does not grant repository access.
+Signing in to Mogplex with GitHub is a separate step that only identifies you.
GitHub App coverage determines which repos Mogplex can access, and which it can
treat as triggerable for webhook-backed work such as [Triggers](/web/triggers)
diff --git a/content/docs/web/installations/coverage-and-triggerability.mdx b/content/docs/web/installations/coverage-and-triggerability.mdx
index ff5697f..c1ce1b6 100644
--- a/content/docs/web/installations/coverage-and-triggerability.mdx
+++ b/content/docs/web/installations/coverage-and-triggerability.mdx
@@ -13,8 +13,9 @@ Those are related, but they are not the same thing.
## Sign-in is not enough
-GitHub sign-in (GitHub OAuth) identifies you and reads your org memberships. It
-does not give Mogplex access to repositories.
+The GitHub connection (GitHub OAuth) identifies your GitHub account and reads
+your org memberships. It does not give Mogplex access to repositories.
+Signing in to Mogplex with GitHub is a separate step that only identifies you.
Repository access and webhook-backed routing both come from a GitHub App
installation linked to you. Until one is linked, you can use only repositories
@@ -69,8 +70,10 @@ Mogplex tracks each repo's coverage as one of these states:
Projects does not show these labels. It uses them to decide what to list. Once
an installation is linked to you, Projects lists only repos that have an
installation id, whether it comes from your own installation or from the
-teammate who shared the repo. Repos without one stay out of the list, unless
-none of your repos has one. If a repo you expect is missing, add it to the
+teammate who shared the repo. Repos without one stay out of the list.
+If none of your repos has an installation id yet, for example before the first
+sync after an install, Projects shows all your repos so the list is not empty.
+If a repo you expect is missing, add it to the
installation on GitHub, or install the App on the account that owns it.
While no installation is linked to you, Projects lists every repo you can use,
diff --git a/content/docs/web/installations/index.mdx b/content/docs/web/installations/index.mdx
index f1291a6..0865001 100644
--- a/content/docs/web/installations/index.mdx
+++ b/content/docs/web/installations/index.mdx
@@ -10,11 +10,12 @@ docs section describes the GitHub App installation state surfaced in
[Settings](/web/settings) and consumed by [Projects](/web/spaces),
[Triggers](/web/triggers), and [Automations](/web/automations).
-## Sign-in and installations do different jobs
+## The GitHub connection and installations do different jobs
-- **GitHub sign-in** (GitHub OAuth) identifies you and reads your org
- memberships. It never grants repository access when Mogplex uses a GitHub
- App.
+- **The GitHub connection** (GitHub OAuth, made when you choose **Connect
+ GitHub** or **Install GitHub App**) identifies your GitHub account and reads
+ your org memberships. It never grants repository access when Mogplex uses a
+ GitHub App. Signing in to Mogplex with GitHub is a separate step that only identifies you.
- **A linked GitHub App installation** gives you its repositories and sends the
webhooks that start work for the installed account or org.
@@ -49,6 +50,12 @@ repositories that a teammate with the linked installation has shared to the
Mogplex team. Joining a team does not add your teammates' personal repositories
to it.
+Team members can work on a team-shared repository in Projects and agent runs.
+[Triggers](/web/triggers) and [Automations](/web/automations) are different:
+each one belongs to an installation linked to the person who creates it. To
+add a trigger or an automation for an org's repositories, ask an org owner who
+has linked the org installation to create it.
+
## How an installation gets linked
Mogplex links an installation to you in three ways:
diff --git a/content/docs/web/settings.mdx b/content/docs/web/settings.mdx
index 259b633..fa388d1 100644
--- a/content/docs/web/settings.mdx
+++ b/content/docs/web/settings.mdx
@@ -96,8 +96,9 @@ The **Account** page shows:
Two distinctions matter here:
-- **GitHub sign-in** identifies you and reads your org memberships. It does not
- grant repository access.
+- **The GitHub connection** (GitHub OAuth) identifies your GitHub account and
+ reads your org memberships. It does not grant repository access.
+ Signing in to Mogplex with GitHub is a separate step that only identifies you.
- **A linked GitHub App installation** gives you its repositories and makes
them triggerable for reviews, automations, and webhook-backed routing.
diff --git a/content/docs/web/triggers.mdx b/content/docs/web/triggers.mdx
index 65a13a9..6009daf 100644
--- a/content/docs/web/triggers.mdx
+++ b/content/docs/web/triggers.mdx
@@ -67,6 +67,12 @@ form says no installations are available, check
[Installations](/web/installations) and confirm the correct user or org has the
Mogplex GitHub App installed and the installation is linked to you.
+A trigger belongs to an installation linked to the person who creates it.
+Org members who are not org owners cannot link the org installation, so they
+cannot create triggers for its repositories, even for repositories shared to
+their team. Ask an org owner who has linked the installation to create the
+trigger.
+
The creation form searches installations by both account scope and synced repos,
so this page is often the fastest way to notice that a repo is in Projects but
no linked installation covers it.
From 82208836e29905e86b3cfa88651fe1de67301493 Mon Sep 17 00:00:00 2001
From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com>
Date: Mon, 9 Nov 2026 06:13:12 -0500
Subject: [PATCH 7/7] docs: qualify OAuth-only state for self-hosted and point
at Settings for installations
---
content/docs/integrations/github.mdx | 3 ++-
content/docs/self-hosting/github-app.mdx | 3 ++-
content/docs/web/guides/project-workflow.mdx | 5 ++++-
.../web/installations/coverage-and-triggerability.mdx | 9 +++++----
4 files changed, 13 insertions(+), 7 deletions(-)
diff --git a/content/docs/integrations/github.mdx b/content/docs/integrations/github.mdx
index e43b838..f87d3b9 100644
--- a/content/docs/integrations/github.mdx
+++ b/content/docs/integrations/github.mdx
@@ -23,7 +23,8 @@ GitHub sign-in nor the GitHub connection grants repository access on its own.
first.
2. Install the App on your personal account, or on an org where you are an org
owner. Mogplex links the installation when GitHub returns you to Mogplex.
-3. Confirm the installation in [Installations](/web/installations).
+3. Confirm the installation under **Settings → Account** (see
+ [Installations](/web/installations)).
4. Sync repos in [Projects](/web/spaces).
5. Choose the routing surface that matches the work:
[Triggers](/web/triggers), [Assignments](/web/assignments), or
diff --git a/content/docs/self-hosting/github-app.mdx b/content/docs/self-hosting/github-app.mdx
index 8f446fb..bc5210e 100644
--- a/content/docs/self-hosting/github-app.mdx
+++ b/content/docs/self-hosting/github-app.mdx
@@ -182,7 +182,8 @@ GITHUB_CLIENT_SECRET=...
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. Open [Installations](/web/installations) and confirm coverage. Then sync
+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
diff --git a/content/docs/web/guides/project-workflow.mdx b/content/docs/web/guides/project-workflow.mdx
index 18847f6..4077337 100644
--- a/content/docs/web/guides/project-workflow.mdx
+++ b/content/docs/web/guides/project-workflow.mdx
@@ -37,6 +37,9 @@ differently:
| App installed, no synced repos yet | Installation coverage exists | Repos will not show up in Projects until they are synced or imported |
| App installed with synced repos | Full GitHub-backed setup | N/A |
+In a self-hosted deployment without a GitHub App, `OAuth only` still lists and
+imports repos through OAuth. Those repos cannot start App-backed work.
+
If you only remember one rule, use this one:
- GitHub sign-in tells Mogplex who you are
@@ -91,7 +94,7 @@ Two practical nuances matter here:
- Repo import needs a linked installation. GitHub sign-in alone does not
import repos.
- Once installation-backed sync is active, Projects lists only repos covered by
- a linked installation, which hides stale OAuth-only rows.
+ a linked installation, which hides stale `Synced only` rows.
## 5. Confirm managed sandbox access if you plan to launch workspaces
diff --git a/content/docs/web/installations/coverage-and-triggerability.mdx b/content/docs/web/installations/coverage-and-triggerability.mdx
index c1ce1b6..32c93bf 100644
--- a/content/docs/web/installations/coverage-and-triggerability.mdx
+++ b/content/docs/web/installations/coverage-and-triggerability.mdx
@@ -50,7 +50,7 @@ The account connection can show up in states like:
| State | Meaning |
| --- | --- |
-| `OAuth only` | GitHub sign-in is connected, but no installation is linked to you. You have no repository access of your own yet. In a self-hosted deployment without a GitHub App, this is the normal connected state. |
+| `OAuth only` | The GitHub connection exists, but no installation is linked to you. With a GitHub App, you have no repository access of your own yet. In a self-hosted deployment without a GitHub App, this is the normal connected state: repos are listed and imported through OAuth, but none of them can start hosted GitHub-event work. |
| `Install pending` | The App install was started, but no installation is linked to you yet. If it stays here after you finish on GitHub, see [An org you belong to does not appear](/web/installations#an-org-you-belong-to-does-not-appear). |
| `App installed` | Coverage exists, but no covered repos are synced into Projects yet |
| `Ready` | App coverage is active and covered repos are already synced |
@@ -107,8 +107,8 @@ Mogplex does not only rely on the install callback.
Each time you open **Settings → Account**, Mogplex looks for installations on
your own account and on your GitHub orgs, and links the ones you own. Orgs that
restrict third-party OAuth apps are not visible to discovery. A GitHub webhook
-can also link an installation when you install the App or add repositories to
-it. See
+can also link an installation when you install the App or, as the account or
+org owner, add repositories to it. See
[How an installation gets linked](/web/installations#how-an-installation-gets-linked).
That is why these pages can sometimes "heal" after an install finishes in
@@ -137,7 +137,8 @@ If the question is about routing, coverage is the thing that matters.
## Good troubleshooting order
1. Check [Settings](/web/settings) and read the current GitHub status label
-2. Confirm the expected owner or org appears in [Installations](/web/installations)
+2. Confirm the expected owner or org appears under **Settings → Account** (see
+ [Installations](/web/installations))
3. Check that the repo is listed in [Projects](/web/spaces), then use
[Repo-level coverage state](#repo-level-coverage-state) to read what the
list tells you