> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub integration

> Install the Embedder GitHub App, map repositories to projects, and trigger work with @embedder mentions

Once the GitHub App is installed and a repository is mapped to an Embedder project, anyone with access to the repository can hand Embedder work by mentioning `@embedder` on an issue or pull request. A [daemon](/headless/daemon) on your machine executes the work and Embedder posts the result back — usually as a pull request.

## Before you begin

Make sure you have:

* **Owner or admin access** to your Embedder organization. Members can view the integration but not change it.
* **GitHub linked as a sign-in method** on your Embedder account. Open [the dashboard](https://app.embedder.com/account) → **Account** → **Profile** and link GitHub before installing — Embedder uses it to match the installation back to your organization.
* **An Embedder project for each repository** you want to connect. Create projects from the CLI or the VS Code extension first; the mapping step links each repository to an existing project.

## Install and connect

<Steps>
  <Step title="Open the GitHub integration page">
    In [the dashboard](https://app.embedder.com), select your team in the sidebar, then open **GitHub**.
  </Step>

  <Step title="Connect GitHub">
    Select **Connect GitHub**. You are handed off to GitHub's own App installation screen, where you choose the organization or account to install into and whether to grant access to **all repositories** or **only selected repositories**.

    After you approve, GitHub redirects you back to the dashboard.

    <Check>
      The dashboard confirms with **GitHub installation linked**, and the installation appears with a **Connected** badge.
    </Check>

    <Note>
      One GitHub installation links to one Embedder organization. If a colleague installed the App but didn't finish, the original installer sees a **Finish linking** button instead.
    </Note>
  </Step>

  <Step title="Map repositories to projects">
    Expand the installation with **Show repositories**. Each repository row has a **Project** dropdown — select the Embedder project that repository should run under.

    Mapping rules:

    * **A project backs exactly one repository.** Projects already linked elsewhere appear disabled in the dropdown.
    * **Mappings are per team.** The same repository can be mapped in more than one team of your organization.
    * Selecting a project saves immediately (**Repository connected**); choosing **Not connected** removes the mapping.

    <Warning>
      Mentions on an **unmapped repository are silently ignored** — no reaction, no reply. Map every repository you want Embedder to work on.
    </Warning>
  </Step>

  <Step title="Start a daemon">
    Headless work only executes while a daemon is online. Follow [Run the daemon](/headless/daemon):

    ```bash theme={"system"}
    embedder start daemon
    ```
  </Step>

  <Step title="Trigger work">
    Comment on any issue or pull request in a mapped repository:

    ```text theme={"system"}
    @embedder please fix the flaky I2C init and open a PR
    ```

    When a daemon claims the work, the comment gets a 🚀 reaction. When the work finishes, Embedder posts a completion comment with a link to the pull request it opened or updated.
  </Step>
</Steps>

## Where mentions work

Embedder reacts to `@embedder` (case-insensitive) in:

* **Issue comments** and **pull request comments**
* **Pull request review comments** — mention it on a specific diff line and it replies in that review thread
* **Issue bodies** — opening (or editing in) an issue that contains `@embedder` queues work for it

<Tip>
  The request is everything after the mention up to the first blank line. Keep the whole instruction in one paragraph directly after `@embedder`.
</Tip>

For work triggered from an issue, Embedder creates a branch and opens a pull request titled `Fix #<issue>: <title>`. For work triggered from a pull request, it pushes to the PR's existing branch.

## Follow-up questions

If the agent needs input, it posts a comment asking for clarification and pauses the work item — freeing your daemon for other work. The comment includes the exact reply command to use, in the form:

```text theme={"system"}
@embedder reply <work-id> <your answer>
```

Reply from the **same GitHub account** that made the original request. The work item resumes from where it left off, with the same working state.

## Automatic PR reviews

The GitHub App can also review every pull request automatically. Reviews are read-only: the agent checks out the PR, reads the diff, and reports findings as a check run named **Embedder Review** plus inline comments — it never modifies code unless you ask.

<Frame caption="A review posted by embedder-bot: a findings summary with severities, plus inline comments with suggested changes">
  <img src="https://mintcdn.com/embedder/_xHO9pAtDOGBmFZI/images/github-embedder-bot-review.png?fit=max&auto=format&n=_xHO9pAtDOGBmFZI&q=85&s=09015dde6a6f1fb6fcf66945d6d22994" alt="Pull request review by embedder-bot showing a severity table with one low issue and an inline diff comment explaining the problem with a suggested change" width="2252" height="1838" data-path="images/github-embedder-bot-review.png" />
</Frame>

Automatic review is **off by default**. On the GitHub integration page, each installation has an **Automatic pull request review** section:

* **Review: On / Off** — enable review per repository. The repository must be mapped to a project first.
* **Default: review all repos / review off** — the default for repositories without a per-repo setting.
* **Stop all reviews** — an organization-wide kill switch.
* **Automatic reviews per month** — an optional cap. Manually requested reviews don't count toward it.

You can also request a one-off review on any PR by commenting exactly:

```text theme={"system"}
@embedder review
```

To have Embedder fix what a review found, comment `@embedder fix review issues` on the PR.

<Note>
  Reviews run on your own daemon too. A repository with review enabled is only reviewed while a daemon is online for its mapped team and project. Draft PRs are skipped, and very large diffs (over 400 KB) are skipped with a note.
</Note>

To give the reviewer repository-specific instructions, add a `.embedder/REVIEW.md` file to the repository — its contents are included in every review of that repository.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Nothing happens when I mention @embedder">
    Silence means the request never became claimable work:

    * **The repository isn't mapped.** Unmapped repositories are ignored without any error. Check the **Project** dropdown for the repository on the GitHub integration page.
    * **The GitHub App doesn't cover the repository.** If you installed with "only selected repositories", add this one to the installation on GitHub.
  </Accordion>

  <Accordion title="The comment got a 🚀 reaction but no reply yet">
    The 🚀 means a daemon claimed the work and is executing it. Watch progress with `embedder monitor` on the daemon machine. A single run can take a while but is capped at 30 minutes.
  </Accordion>

  <Accordion title="No 🚀 reaction appears">
    The work is queued but no daemon has claimed it. Check that a daemon is running (`embedder monitor`), that its user is a member of the team the repository is mapped to, and that it isn't pinned to a different team or project with `--team`/`--project`.
  </Accordion>

  <Accordion title="The Embedder Review check stays queued">
    No daemon was online to run the review. The check closes as neutral after 6 hours; push to the pull request to trigger a fresh review once a daemon is running.
  </Accordion>

  <Accordion title="Editing my comment doesn't re-run the work">
    Each comment triggers work once. Embedder replies that the comment already triggered GitHub work — post a new comment to run again.
  </Accordion>

  <Accordion title="My reply to a follow-up question is ignored">
    Use the exact `@embedder reply …` command from the bot's comment, in the same thread, from the same GitHub account that made the original request.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Run the daemon" icon="server" href="/headless/daemon">
    Start, monitor, and manage the daemon that executes GitHub work.
  </Card>

  <Card title="Slack integration" icon="slack" href="/headless/slack">
    Start the same headless work from a Slack thread.
  </Card>
</CardGroup>