# Project Workflow (/web/guides/project-workflow) This is the cleanest first-run path when you are setting up Mogplex for a repo or org for the first time. The main thing to keep straight is that Mogplex separates three jobs: * connecting your GitHub identity * getting the right repos into Projects * enabling the routing surface you actually want If you do those in the right order, setup gets much easier to reason about. ## 1. Connect GitHub [#1-connect-github] Start in [Settings](/web/settings) and connect GitHub. That establishes your account identity and is enough to start importing repos. It is **not** the same thing as GitHub App coverage. That distinction matters because Mogplex treats these setup states differently: | State | What it unlocks | What it does not unlock yet | | ---------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------- | | Disconnected | Nothing GitHub-backed | Repo import, repo creation, trigger routing | | OAuth connected | Repo import and repo creation | Webhook-backed routing | | App install pending | Repo import can still work if OAuth is already connected | Trigger-ready coverage until the install completes | | 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 | If you only remember one rule, use this one: * GitHub connection lets Mogplex see repos * GitHub App coverage lets Mogplex route webhook-backed work into them ## 2. Confirm App coverage [#2-confirm-app-coverage] Still in [Settings](/web/settings), check the GitHub App coverage section and the installation list. You want to verify: * the correct account or org is installed * the installation lists the repos you care about * Mogplex has started syncing covered repos into Projects If that is not true yet, use the [GitHub App Coverage](/web/guides/github-app-coverage) guide before going further. ## 3. Create the project structure you actually want [#3-create-the-project-structure-you-actually-want] Go to [Projects](/web/spaces). Projects can be empty. You do not need to wait for a perfect import state before organizing the workspace structure. In practice, you usually choose one of these paths: * keep using the default imported project for synced repos * create additional projects to separate teams, products, or environments * create a brand-new GitHub repo directly inside a project Mogplex supports both imported repos and app-created repos, so "set up Projects" is not the same thing as "sync everything first." ## 4. Import or create repos [#4-import-or-create-repos] From [Projects](/web/spaces), you can: * import repos into the default imported project * create additional projects to group repos * create a new GitHub repo inside a project when GitHub is already connected * add sub-project repos for monorepo targets * configure repo-specific settings such as sandbox behavior, env sync, and linked Vercel project state Two practical nuances matter here: * If GitHub is connected through OAuth, you can still import repos before the App install is finished. * Once installation-backed sync is active, covered repos become the preferred source of truth in Projects, which helps avoid stale OAuth-only duplicates. ## 5. Confirm managed sandbox access if you plan to launch workspaces [#5-confirm-managed-sandbox-access-if-you-plan-to-launch-workspaces] Repo import and routing setup do not require sandbox access, but sandbox-backed workspace sessions do. Hosted sandbox access is billed through Mogplex. Users do not need to attach an external sandbox account for workspace sessions. If you only want to configure routing first, you can do that before the account has managed sandbox access. ## 6. Open a workspace [#6-open-a-workspace] From [Projects](/web/spaces), open a workspace session for the repo you want. If a sandbox is not already running, Mogplex can launch one as part of opening the workspace. This is the fastest route into active repo work. That means the normal operator loop is: 1. import or create the repo 2. open the workspace 3. let Mogplex launch the sandbox if needed 4. start doing repo work from the session This is also the point where repo-scoped controls become practical. If one repo should use a different integration surface than the rest of your account, open the repo-aware Connections pane and decide which tools stay global, which should be excluded, and which belong only to that repo. See [Connection Scope and Overrides](/web/guides/connection-scope-and-overrides). ## 7. Choose the routing model [#7-choose-the-routing-model] Once the repo is imported, choose the lightest surface that matches the job: * Use [Triggers](/web/triggers) for one event to one agent * Use [Assignments](/web/assignments) for durable repo-to-agent routing such as PR review, CI failure, or cron work * 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. ## 8. Watch it in Observability [#8-watch-it-in-observability] After work starts running, move to [Observability](/web/observability). That is where you confirm run status, pressure, failures, call details, tool usage, and sandbox-linked execution state. ## Fastest successful setup path [#fastest-successful-setup-path] If you want the shortest version: 1. Connect GitHub in [Settings](/web/settings) 2. Install the GitHub App for the repo owner 3. Open [Projects](/web/spaces) and import or create the repo 4. Confirm managed sandbox access if you need sandbox-backed workspaces 5. Open a workspace 6. Add a Trigger, Assignment, or Automation 7. Test the exact GitHub event you expect, then confirm it in [Observability](/web/observability)