charlesrhoward · Nov 9, 2026 · Nov 9, 2026 · Nov 9, 2026 · Nov 9, 2026 · Nov 9, 2026
@@ -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

@@ -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
 

@@ -65,7 +65,7 @@ known, but the sequence still matters.
   <Card
     title="GitHub App Coverage"
     href="/web/guides/github-app-coverage"
-    description="Debug the difference between OAuth repo visibility and GitHub App triggerability."
+    description="Debug the difference between GitHub sign-in and GitHub App coverage, and check that the right installation is linked to you."
   />
   <Card
     title="GitHub Mention Routing"

@@ -18,7 +18,7 @@ contract before changing agents, prompts, routes, or models.
 
 | Check | Why it matters |
 | --- | --- |
-| GitHub App coverage | Hosted work needs installation-backed repo access, not only OAuth visibility |
+| GitHub App coverage | Hosted work needs repo access from a GitHub App installation linked to you; GitHub sign-in alone grants none |
 | Repo import state | Mogplex needs a repo record before it can launch workspace or API runs |
 | Root directory | Monorepos need the exact app/package path instead of repo root |
 | Install command | Dependency setup should match the package manager and workspace path |

@@ -13,8 +13,8 @@ work started.
 
 | Symptom | Most likely layer |
 | --- | --- |
-| Repo is missing or stale | account sync or Projects |
-| Repo is visible but GitHub events do not fire | GitHub App coverage |
+| 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 |
 | Route exists but no run appears | route source, coverage, enabled state, or published automation |
@@ -41,12 +41,15 @@ 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 is covered by the Mogplex GitHub App.
+2. Confirm the repo owner's Mogplex GitHub App installation is linked to you.
+   If an org you belong to is missing, see
+   [An org you belong to does not appear](/web/installations#an-org-you-belong-to-does-not-appear).
 3. Confirm the route is on the same installation or repo that owns the event.
 4. Confirm the route is enabled, or the automation is published.
 5. If work starts, continue into [Observability](/web/observability).

@@ -299,7 +299,8 @@ finish, then drill into the product surface that owns it.
 After the first hour, these should all be true:
 
 - Mogplex can see the repos you expect.
-- The repo owner has GitHub App coverage, not only OAuth visibility.
+- The repo owner's GitHub App installation is linked to you, or the repo is
+  shared to your Mogplex team.
 - At least one reusable agent is configured the way you expect.
 - One local CLI run completes successfully.
 - You know whether the next job belongs in Triggers, Assignments, or

@@ -7,50 +7,69 @@ GitHub is the first integration most Mogplex accounts need.
 
 It does two separate jobs:
 
-- identity and repo discovery through GitHub OAuth
-- webhook-backed routing through the Mogplex GitHub App
+- 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
 
-Keep those separate while debugging. A repo can be visible in
-[Projects](/web/spaces) and still fail to trigger hosted work if the owner does
-not have GitHub App coverage.
+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
 
-1. Open [Settings](/web/settings) and connect GitHub.
-2. Install the Mogplex GitHub App for the user or org that owns the repos.
-3. Confirm installation coverage in [Installations](/web/installations).
-4. Sync or import repos in [Projects](/web/spaces).
+1. Open **Settings → Account** and select **Install GitHub App**. If your
+   GitHub account is not connected yet, GitHub asks you to authorize Mogplex
+   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 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
    [Automations](/web/automations).
 6. Verify the first run in [Observability](/web/observability).
 
-## OAuth vs GitHub App coverage
+## Repository access
 
-| State | What it unlocks | What it does not unlock yet |
-| --- | --- | --- |
-| GitHub disconnected | Nothing GitHub-backed | Repo import, repo creation, webhook routing |
-| OAuth connected | Account identity and repo import | Webhook-backed routing |
-| App installed | Repo coverage for GitHub events | Synced repos until import or sync completes |
-| App installed and repos synced | Full GitHub-backed setup | N/A |
+| State | What you can use |
+| --- | --- |
+| GitHub connected, no installation linked | No repositories, except repositories shared to your Mogplex team |
+| Installation linked | Every repository in that installation, for repo work, webhooks, triggers, and automations |
+| Installation linked and repos synced | Full GitHub-backed setup |
 
-Use [GitHub App Coverage](/web/guides/github-app-coverage) when a repo is
-visible but [Triggers](/web/triggers) or [Automations](/web/automations) cannot
-route work into it.
+The rules that decide this:
+
+- You can link an installation on your own personal account, or on an org where
+  you are an org owner. Linking gives you the installation's whole repository
+  set.
+- Org members who are not owners do not link the org installation. They use
+  team-shared repositories instead. See
+  [Who can link an installation](/web/installations#who-can-link-an-installation).
+- If an installation is uninstalled or suspended on GitHub, your access to its
+  repositories ends. See
+  [When an installation is removed](/web/installations#when-an-installation-is-removed).
+
+For how linking happens, see
+[How an installation gets linked](/web/installations#how-an-installation-gets-linked).
+If an org you belong to is missing, see
+[An org you belong to does not appear](/web/installations#an-org-you-belong-to-does-not-appear).
+
+Self-hosted deployments without a GitHub App work differently: there, the GitHub
+OAuth app lists and imports repositories. See
+[Self-hosted GitHub App](/self-hosting/github-app).
 
 ## Repository creation
 
 Creating a repository from Mogplex has its own requirements:
 
-- **In an organization**, the App must be installed there and an organization
-  owner must accept the App's Repository creation permission on GitHub. If
-  Mogplex says the App "cannot create repositories yet", the request is still
-  pending or the organization's repository creation policy blocks it. If you
-  self-host, see also
+- **In an organization**, you must be an org owner, and the org's installation
+  must be linked to you. An org owner must also accept the App's Repository
+  creation permission on GitHub. If Mogplex says the App "cannot create
+  repositories yet", the request is still pending or the organization's
+  repository creation policy blocks it. If you self-host, see also
   [GitHub App troubleshooting](/self-hosting/github-app#repository-creation-failures).
-
-  Separately, only organization owners can create organization repositories
-  from Mogplex. That is a Mogplex rule, not a GitHub setting.
 - **In your personal account**, the App must be installed on your account, so
   Mogplex can work in the new repository. Then select **Authorize GitHub** when
   Mogplex asks. Mogplex creates personal repositories with your own GitHub
@@ -89,17 +108,19 @@ rules, including entry-agent behavior in automations.
 ## Where to check state
 
 - [Settings](/web/settings): GitHub connection state and account-level setup
-- [Installations](/web/installations): App coverage, repo eligibility, and
-  synced repo state
+- [Installations](/web/installations): linked installations, repo eligibility,
+  and synced repo state
 - [Projects](/web/spaces): imported repo list, repo settings, and workspace
   entry points
 - [Observability](/web/observability): run status and failure trail after a
   GitHub event starts work
 
 ## Common failures
 
-- **Repo is visible but triggers are empty**: OAuth is connected, but App
-  coverage is missing for the repo owner.
+- **An org you belong to does not appear**: the org's installation is not
+  linked to you. An org owner installs or configures the App; see
+  [An org you belong to does not appear](/web/installations#an-org-you-belong-to-does-not-appear).
+- **Triggers are empty**: no installation is linked to you for the repo owner.
 - **Mention does not wake the expected agent**: the comment may be bare
   `@mogplex` when it needed `@mogplex/<agent-slug>`, or the wrong route is
   marked default.

@@ -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
 

@@ -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

@@ -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).
 
@@ -153,11 +154,12 @@ 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. 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).
 
@@ -222,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).
 

@@ -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

@@ -97,8 +97,11 @@ ID and secret are set.
 | Microsoft | `AUTH_MICROSOFT_CLIENT_ID`, `AUTH_MICROSOFT_CLIENT_SECRET`, `AUTH_MICROSOFT_TENANT_ID` (default `common`) | `https://<domain>/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. 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.
 
 ## Email
 

@@ -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/<slug>`. |
 | `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. |