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

# Run GitHub work

> Connect a repository, request firmware changes with an @embedder comment, and get automatic pull request reviews.

Comment `@embedder` in a connected repository to request a change, or turn on automatic pull request reviews. Your daemon host does the work, using the Embedder project mapped to that repository.

## Before you start

* A running [daemon](https://docs.embedder.com/headless/daemon.md) on a machine with the project's toolchain and any hardware the work needs. [Start the daemon](https://docs.embedder.com/headless/daemon.md#start-the-daemon) before you connect the repository, so your first request has a machine to run on. The daemon's Embedder account must belong to the team that owns the project.
* An Embedder project for the repository. [Create the project](https://docs.embedder.com/quickstart.md#connect-a-firmware-project) first if it doesn't exist.
* An owner or admin role in the Embedder organization that owns the project's team. If you don't have one, ask your Embedder administrator to connect the repository.
* Permission in GitHub to install the Embedder GitHub App on the repository.
* GitHub linked as a sign-in method on your Embedder account. In [the Embedder app](https://app.embedder.com), open **Settings** and choose **Link** beside **GitHub** under **Sign-in methods**.

## Connect a repository

1. In [the Embedder app](https://app.embedder.com), select the team that owns the project and choose **GitHub** in the sidebar.
2. Choose **Connect GitHub**. Complete the installation on GitHub and grant the app access to the repository.
3. GitHub returns you to the **GitHub Integration** page, which confirms **GitHub installation linked**. If the installation doesn't appear, choose **Refresh**. If the page shows **GitHub App installed but not linked yet**, choose **Finish linking**.
4. Find the repository under the installation. If its list is collapsed, select the installation's name to expand it. Use **Search repositories** to filter the list.
5. In the project selector beside the repository, choose your Embedder project. Wait for **Repository connected**. A project can back only one repository. A project that is already linked appears as **Already linked to** followed by the repository name, and you can't select it.
6. On the daemon host, run `embedder monitor` and confirm that the Daemon Monitor shows the daemon as **connected**. If it shows **No active daemon found**, run `embedder start daemon`.

When the team has a linked installation and at least one mapped repository, the page shows **GitHub linked and ready**. [Request a change](#request-a-change) to try it.

To stop routing work from a repository, set its project to **Not connected**. To remove the whole installation from the team, choose **Disconnect** on the installation. This deactivates its repository mappings.

## Request a change

Comment `@embedder` followed by your request in any of these places:

* A comment on an issue or pull request.
* A review comment on a pull request's changed lines.
* The body of a new issue.

```text theme={"theme":"css-variables"}
@embedder fix the UART reconnect race in this pull request. Preserve the
public API, add a regression test, and run the UART tests and debug build.
```

Embedder reads the text after `@embedder` up to the first blank line. A mention with no request after it does nothing, and comments from bots are ignored.

Embedder runs requests from people with write or admin access to the repository, and from members of the Embedder team the repository is mapped to who have linked GitHub under **Sign-in methods** in **Settings**. Anyone else gets a reply that they can't start Embedder.

While the request waits for a daemon, Embedder posts a status reply, starting with **On it**, and edits that reply when the request finishes. See [Status replies](https://docs.embedder.com/headless/overview.md#status-replies) for what each reply means.

Until a daemon picks up the request, you can edit the comment to change it. To cancel it, remove the mention or delete the comment. After the run starts, editing the comment doesn't change the request. Embedder replies asking you to leave a new comment instead.

Embedder commits and pushes its changes, then reports the pull request, branch and commit. Where you ask decides the branch:

| Where you ask | What Embedder does |
| - | - |
| A pull request | Pushes to that pull request's branch. |
| An issue with no open Embedder pull request | Creates `embedder/work/<work-item-id>` from the default branch and opens a pull request. |
| An issue with one open Embedder pull request | Continues that pull request. |
| An issue with several open Embedder pull requests | Asks which to continue. Reply with the command it shows, ending in `use #<number>` or `open new`. |

See [Review what Embedder publishes](https://docs.embedder.com/headless/overview.md#review-what-embedder-publishes) for asking for local-only work and for merging.

Embedder doesn't work on pull requests opened from forks, or on pull requests that are no longer open. A request on a fork pull request stays waiting and never starts.

If someone pushes to the pull request branch while Embedder is working, Embedder's push can fail. Request a new run against the current branch instead of overwriting their work.

## Answer a question

When Embedder needs input, it posts a question with a reply command. Post a new comment with that command and your answer:

```text theme={"theme":"css-variables"}
@embedder reply <id-from-embedder> use the 115200 baud default and keep the
existing log format
```

Copy the exact command from Embedder's comment, because it identifies the paused run. The reply must come from the person who made the request. The run resumes in the same checkout.

Embedder keeps the checkout of a paused or failed run on the daemon host so a reply can resume it. Checkouts older than seven days are removed when the daemon starts. After that, start a new request with the relevant context.

## Review pull requests

Embedder can review pull requests automatically. A review reads the diff, posts findings on changed lines and never edits files or runs build commands.

### Turn on automatic reviews

1. On the team's **GitHub Integration** page, find the installation. If its list is collapsed, select the installation's name to expand it.
2. Turn on **Review** beside each mapped repository you want reviewed.
3. Keep a daemon online for that repository's team and project. Reviews run only while a daemon can pick them up.

**Review** is unavailable when the repository isn't mapped to a project, when you can't manage the integration, or when reviews are stopped for the installation.

Automatic reviews run when a pull request is opened, reopened, marked ready for review, or receives new commits. Draft pull requests aren't reviewed.

To request a review yourself, comment `@embedder review` on a pull request in a mapped repository. This works even when **Review** is off for the repository.

### Read the review

Each review posts:

* An overview of the change with a risk rating of high, medium or low.
* Findings on the changed lines, each with a severity and sometimes a suggested fix. A review reports at most 50 findings.
* An **Embedder Review** check. It passes when there are no findings, fails when any finding is high severity, and is neutral otherwise.

A review is skipped when the pull request has no diff or the diff is larger than about 400 KB. Split large changes into focused pull requests. A clean review doesn't replace the project's tests.

To give reviewers project rules, such as generated-code boundaries or error-handling requirements, add `.embedder/REVIEW.md` to the repository. Embedder reads the first 32 KB.

### Choose installation settings

The installation's **Automatic pull request review** section controls defaults for all its repositories:

| Setting | Effect |
| - | - |
| **Review new repositories by default** | Turns on review for repositories that have no setting of their own. A repository's own **Review** switch takes precedence. |
| **Autofix by default** | Turns on autofix for repositories that have no setting of their own. |
| **Automatic reviews per month** | Limits automatic reviews for each repository in a calendar month. Leave it empty for no limit. Reviews requested with `@embedder review` don't count. |
| **Stop all reviews** | Stops every review and autofix under the installation, including requested reviews. Choose **Resume auto review** to allow them again. |

Check the **Review** and **Autofix** switches on each repository instead of assuming the defaults apply.

### Use autofix

Turn on **Autofix** beside a repository to have Embedder fix review findings. **Autofix** needs **Review** turned on. When a review finds issues, Embedder queues a separate fix run, shown as an **Embedder Autofix** check. That run pushes to the pull request branch.

Leave **Autofix** off if you only want findings.

## Troubleshoot

* **GitHub isn't in the sidebar, or connect controls are missing:** ask your Embedder administrator whether integrations are available for your team and whether you have an owner or admin role in the organization.
* **You do not have permission to perform this action:** connecting, mapping and review settings need an owner or admin role in the Embedder organization. Ask your Embedder administrator.
* **GitHub identity link required:** link GitHub under **Sign-in methods** in **Settings**, then choose **Connect GitHub** again.
* **GitHub connection expired:** choose **Manage GitHub sign-in**, choose **Reconnect** beside GitHub, then retry **Connect GitHub**.
* **GitHub install session expired** or **GitHub install could not be completed:** choose **Connect GitHub** again from the **GitHub Integration** page.
* **Only the installer can link this installation:** ask the person who installed the GitHub App to open the page and choose **Finish linking**. Or uninstall the app on GitHub and install it again from the **GitHub Integration** page.
* **This GitHub installation can't be linked here:** the installation is linked to another organization, or was removed or suspended on GitHub.
* **The repository is missing:** confirm the GitHub App has access to it, finish any pending link, and choose **Refresh**.
* **No work starts, or Embedder replies Waiting for a bench to take this or No bench takes work for the repository yet:** check that the repository is mapped, a daemon is connected, and the daemon's account belongs to the project's team. If the daemon is limited to one project, check that it's this project. In these replies, a bench is a machine running the daemon.
* **Only collaborators with write access to this repository, or members of the Embedder team it is connected to, can start Embedder:** ask for write access to the repository. Or ask your Embedder administrator to add you to the team the repository is mapped to, then link GitHub under **Sign-in methods** in **Settings**.
* **I can't tell which Embedder account is yours:** link GitHub under **Sign-in methods** in **Settings**.
* **No automatic review appears:** check that **Review** is on, the pull request isn't a draft or opened from a fork, and a daemon is online for the mapped project. Check **Automatic reviews per month**. If no daemon picks up a review within six hours, the check closes as **No runner picked this up**. Push to the pull request to start a new review.
* **A request on a pull request from a fork stays at Waiting for a bench to take this:** Embedder doesn't work on fork pull requests. Push the branch to the connected repository and open the pull request from there.
* **Embedder says the pull request is no longer open:** the pull request was closed or merged before the run started. Leave a new `@embedder` comment on an issue to start a new pull request from the default branch.
* **GitHub CLI isn't available on the daemon host:** Embedder uses `gh` from the host's `PATH` or downloads its own copy. If the host can't download it, install GitHub CLI and set `EMBEDDER_GH_PATH` to its absolute path. Embedder signs in to `git` and `gh` for each run, so you don't need a separate `gh` login.
* **Update the daemon: agent-owned publishing is required:** update Embedder on the daemon host, then stop and start the daemon.
* **Build tools are missing:** install or configure them on the daemon host, then request a new run.
* **The push fails:** check whether the pull request branch changed during the run.
* **Work waits for hardware:** run `embedder monitor` on the daemon host to find the active task in the Daemon Monitor. Let it finish, or stop it deliberately.

See [Operate the daemon](https://docs.embedder.com/headless/daemon.md) for authentication and host controls.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.