--- title: Request your review description: Put yourself on every pull request the factory opens, with a workflow in the target repository for unattended runs and a prompt change for attended ones. type: guide summary: One workflow file in the target repo, one reviewer constant, and one line in Foreman's delivery step. related: - /docs/trust-model - /docs/configuration - /docs/tools --- # Request your review , and the slug is the last path segment. The bot's login is that slug with "[bot]" appended. 2. My GitHub username, which is the reviewer to request. Ground truth first: read AGENTS.md in the repository root, then read agent/instructions.ts, agent/lib/constants.ts, agent/extensions/github.ts, and agent/lib/github/approval.ts in full. Follow the conventions already in those files rather than inventing new ones. Facts you need, so you don't re-derive them wrongly: - requestReviewers is already in the include allowlist in agent/extensions/github.ts and is already mapped to writePolicy. Do not add it, and do not change its policy. - writePolicy denies unattended runs. That is deliberate: an unattended run is driven by an issue body, and untrusted input must not be able to choose who gets pinged. Do not write a new policy to work around it, and do not touch agent/lib/trust.ts. - github__requestReviewers is already in GITHUB_WRITE_TOOLS in evals/helpers.ts. Leave it. Changes in this repository: 1. Add a FACTORY_REVIEWER constant to agent/lib/constants.ts, read from the environment with no default, following the style of FACTORY_LABEL and FACTORY_BRANCH_PREFIX including the doc comment. It is optional: unset must keep today's behavior exactly. 2. In agent/instructions.ts, extend section 7 ("Delivering the work"). After the bullet about opening the draft pull request, add one bullet telling Foreman to request a review from the configured username with github__requestReviewers. Interpolate FACTORY_REVIEWER the way FACTORY_REPO is already interpolated, and omit the bullet entirely when the variable is unset rather than emitting an empty name. 3. Word that bullet so an unattended run skips the call instead of attempting it and being denied: say that when the run is unattended the repository's own workflow requests the review, so it should not call the tool. Keep the existing rule that Foreman never narrates permissions or blocked actions. 4. Add FACTORY_REVIEWER to .env.example under the optional overrides block, with a one-line comment matching the surrounding style. 5. Show me the diff for agent/instructions.ts on its own, so I can read the prompt change. Then, for the target repository (FACTORY_REPO), which is a different repository from this one: 6. Write out the full contents of .github/workflows/request-review.yml for me to add there. Do not try to commit it into this repository. Read the recipe page linked at the end of this prompt and use the workflow it gives under "The workflow" verbatim, with the bot login and my username substituted in, and the branches filter matching that repo's default branch (ask me if you are not sure what it is). Do not write one from memory. 7. The workflow must have no checkout step. Explain in one line in your summary why pull_request_target is safe here only because of that. 8. Verify the actions/github-script pin before you hand it to me: check that the commented version tag matches the pinned commit SHA, and if you cannot verify it, say so and give me the current release SHA to use instead. 9. Tell me that pull_request_target workflows only run once the file is on the default branch, so it does nothing until it is merged there. Finish by running pnpm validate and confirming 0 errors and 0 warnings, then run pnpm eval --tag fast and report the result. Do not deploy. Full recipe, with the reasoning behind each step: https://ask-foreman.dev/recipes/request-your-review`} /> Put yourself on every pull request the factory opens, so it lands in your review queue instead of waiting for you to notice it. The factory delivers a draft pull request and then stops. Nobody is assigned as a reviewer, so it sits in the repository's pull request list until you happen to look. ## When to use it Reach for this once the factory opens pull requests often enough that checking the repository by hand stops being reliable. Getting them into your review queue is the difference between finished work waiting for you and finished work sitting unnoticed. Skip it if you already watch the repository closely, or if a team-wide `CODEOWNERS` file assigns reviewers for you. ## What it touches Two repositories are involved, the target repository the factory works on and the template. | Repository | File | Change | | ---------------------------- | -------------------------------------- | -------------------------------------------------------------- | | Target repo (`FACTORY_REPO`) | `.github/workflows/request-review.yml` | New workflow requesting your review on the bot's pull requests | | Template | `agent/lib/constants.ts` | New `FACTORY_REVIEWER` environment variable | | Template | `agent/instructions.ts` | One line in the delivery step | | Template | `.env.example` | Document the new variable | Nothing in `agent/extensions/github.ts` or `agent/lib/github/approval.ts` changes, and `github__requestReviewers` is already in `GITHUB_WRITE_TOOLS`, so the read-only evals keep guarding it. ## What you need first The prompt asks you for two things, so have them ready. Your GitHub App's slug. The bot that opens the pull requests logs in as `[bot]`, and that login is what the workflow matches on. The slug is the last segment of the app's URL, so `https://github.com/apps/acme-foreman` means the slug is `acme-foreman` and the login is `acme-foreman[bot]`. It is also the name you already `@mention` the factory with, since the template resolves that from the same slug. Your GitHub username, as the reviewer. You need read access to the target repository for the request to land, which you already have if you can open its pull requests. ## Before you run it The username ends up in two places, the workflow YAML and `FACTORY_REVIEWER`. Changing reviewers later means changing both, and only the workflow takes effect immediately. `FACTORY_REVIEWER` is compiled into the prompt at build time, the same way `FACTORY_REPO` is, so changing it in the Vercel project needs a redeploy before Foreman sees the new value. Review requests are not review. Getting the notification is the point; the pull request is still a draft that a person marks ready. ## Why it takes two changes `requestReviewers` is already in the GitHub extension's allowlist, mapped to `writePolicy`. Foreman is never told to use it. Mounting is not the whole story though, because `writePolicy` denies unattended runs: | Caller | `github__requestReviewers` | | ------------------------------------------ | ------------------------------------------ | | Unattended run (factory label, red-CI fix) | Denied | | Trusted mention or Linear session | Runs immediately | | Anyone else | Stops and waits for a person to approve it | The unattended run is the one that opens the pipeline's draft pull requests. So a prompt change on its own would cover the attended paths and miss the main one. The fix is a workflow in the target repository for pull requests the factory opens unattended, plus the prompt change for the attended paths. GitHub does not stack duplicate reviewer requests, so the overlap between the two costs nothing. It is tempting to write a `reviewPolicy` that lets unattended runs through instead of adding a workflow. Don't. An unattended run is driven by an issue body, and an issue body is untrusted input, so a run that can pick reviewers is a run that can be talked into pinging whoever the issue names. The workflow's reviewer list lives in the base branch, where no model-readable content can reach it. ## The workflow The workflow the prompt writes into the target repository: ```yaml name: Request review on: pull_request_target: types: - opened - ready_for_review - reopened branches: - main jobs: request-review: name: Request review # Only PRs opened by the factory bot; human PRs already have their author. if: github.event.pull_request.user.login == 'acme-foreman[bot]' runs-on: ubuntu-slim timeout-minutes: 5 permissions: pull-requests: write steps: - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 with: script: | await github.rest.pulls.requestReviewers({ owner: context.repo.owner, repo: context.repo.repo, pull_number: context.payload.pull_request.number, reviewers: ['your-username'], }) ``` Three details worth understanding before you ship it. `pull_request_target` runs the workflow definition from the base branch, so a pull request cannot change the workflow that runs on it. That trigger is normally the dangerous one, because it hands a write token to a job that then checks out the pull request's code. This job has no checkout step, which is the entire reason it is safe here. Adding `actions/checkout` under `pull_request_target` runs untrusted head code with a token that can write to your pull requests. If you need the diff, use a separate `pull_request` workflow. The pull request number comes from `context.payload.pull_request.number` rather than a `${{ }}` expression. Numbers are harmless either way, but interpolating workflow expressions into a `script` block is the habit that bites people when the value is a title or a body. `opened` covers the draft the pipeline delivers, `ready_for_review` covers the moment a person marks it ready, and `reopened` covers a close and reopen. Change `main` if your default branch is named something else. ## Verify ```bash pnpm validate pnpm eval --tag fast ``` The fast evals matter here because the change touches the delivery path. `read-only-question` asserts that a read-only turn calls nothing in `WRITE_TOOLS`, and `github__requestReviewers` is on that list, so a new instruction that leaks outside the delivery step shows up as a failure. Then merge the workflow to the target repository's default branch and label a scratch issue. When the pipeline opens its draft pull request, the workflow should run and add you as a reviewer. Set `FACTORY_REVIEWER` in the Vercel project and redeploy to get the attended path too, then `@mention` the factory on an issue and take it through to a pull request. That run is trusted, so it requests the review with the tool and no approval card. ## What to expect Most pull requests get their reviewer from the workflow, not from Foreman, because most of them come from unattended runs. The prompt change is the smaller half, covering trusted mentions and Linear sessions. Failures are loud rather than silent. If the username cannot review the repository, the workflow step fails with a red check on the pull request instead of quietly doing nothing. ## FAQ Yes. The rule that stops workflows from triggering other workflows applies to the Actions `GITHUB_TOKEN` specifically. The factory pushes and opens pull requests with its own GitHub App installation token, brokered through Vercel Connect, which is a different token, so the `pull_request_target` event fires normally. You can. The factory's branches are pushed to the target repository itself rather than a fork, so a `pull_request` workflow would get a writable token and work fine. `pull_request_target` is the better default because the definition always comes from the base branch, so the workflow cannot be edited by the pull request it runs on. That only holds while the job has no checkout step. Yes, and it is worth doing if the same GitHub App opens pull requests for other reasons. Add a branch check to the `if`: ```yaml if: >- github.event.pull_request.user.login == 'acme-foreman[bot]' && startsWith(github.event.pull_request.head.ref, 'factory/') ``` Keep it in sync with `FACTORY_BRANCH_PREFIX` if you have overridden that. On `reopened` and `ready_for_review`, yes. Submitting a review clears the request, so a later event puts you back in the queue. If that annoys you, drop `reopened` from the trigger list and keep `opened` and `ready_for_review`. Yes, on an organization repository. In the workflow, pass `team_reviewers` alongside `reviewers`, taking team slugs without the organization prefix. Foreman's tool exposes the same thing as `teamReviewers`. Teams do not work on personal repositories, where the reviewer also has to be a collaborator. It is the 1 vCPU runner, which is the right size for a job that makes one API call. It caps jobs at 15 minutes, well above the 5 minute timeout here. It carries a much smaller toolset than `ubuntu-latest`, which is fine for `github-script` and would not be if you later added steps that expect preinstalled tooling. Swap to `ubuntu-latest` if that happens. Delete `.github/workflows/request-review.yml` from the target repository, and unset `FACTORY_REVIEWER` in the Vercel project. Unsetting the variable is enough to drop the instruction from the prompt on the next build, so reverting the template changes is optional. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)