# GitHub (/integrations/github)



GitHub is the first integration most Mogplex accounts need.

It does two separate jobs:

* 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 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 [#setup-order]

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

## Repository access [#repository-access]

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

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 [#repository-creation]

Creating a repository from Mogplex has its own requirements:

* **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).
* **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
  authorization, so it acts as you there. Mogplex renews the authorization in
  the background; you authorize again only if it goes unused for about six
  months or you revoke Mogplex in GitHub **Settings → Applications**. If you
  self-host, configure the
  [App client credentials](/self-hosting/github-app#client-credentials-for-personal-repositories).

## What GitHub can start [#what-github-can-start]

Mogplex GitHub routing can start work from issue comments, PR comments, PR
review comments, commit comments, repo events, and the specific routing events
exposed by the current trigger or automation surface.

The important choice is scope:

* use [Triggers](/web/triggers) for one GitHub event waking one agent
* use [Assignments](/web/assignments) for durable repo-owned work
* use [Automations](/web/automations) for graph-shaped work with branching,
  delays, publishing, or parallel agents

## Mention routing [#mention-routing]

Mogplex recognizes two mention forms in GitHub comments:

* `@mogplex`
* `@mogplex/<agent-slug>`

Bare `@mogplex` routes only to the default mention target. Targeted mentions
route by agent slug.

Use [GitHub Mention Routing](/web/guides/github-mention-routing) for the exact
rules, including entry-agent behavior in automations.

## Where to check state [#where-to-check-state]

* [Settings](/web/settings): GitHub connection state and account-level setup
* [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 [#common-failures]

* **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.
* **Automation cannot find the expected repo**: check installation coverage and
  repo sync before editing the automation.
* **PR review work starts in the wrong shape**: use an Assignment for standing
  repo responsibility, not a one-off Trigger.

## Dependabot alerts [#dependabot-alerts]

GitHub can also start work when it reports a vulnerable dependency. See
[Dependabot](/integrations/dependabot) to have Mogplex open a reviewed fix PR
for each new alert.

## Read next [#read-next]

<Cards>
  <Card title="GitHub App Coverage" href="/https/docs.mogplex.com/web/guides/github-app-coverage" />

  <Card title="GitHub Mention Routing" href="/https/docs.mogplex.com/web/guides/github-mention-routing" />

  <Card title="Project Workflow" href="/https/docs.mogplex.com/web/guides/project-workflow" />

  <Card title="Choose the Right Routing Surface" href="/https/docs.mogplex.com/web/guides/choose-routing-surface" />

  <Card title="Dependabot" href="/https/docs.mogplex.com/integrations/dependabot" />
</Cards>
