From 2978490ccdbbb57de8e526d96122b77f200f0989 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Fri, 28 Aug 2026 17:45:20 +0000 Subject: [PATCH 1/4] docs: correct GitHub factory mention and label behavior The GitHub factory page treated unlabeled @warp-factory mentions as ignored and named the routing label after the Foreman agent. Match the page to current warp-server behavior: factory:, default automation filters, unlabeled fallback routing, and create-time snapshots. --- .../docs/factories/integrations/github.mdx | 36 +++++++++++++------ 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/src/content/docs/factories/integrations/github.mdx b/src/content/docs/factories/integrations/github.mdx index 7b4d2708..c1da7a02 100644 --- a/src/content/docs/factories/integrations/github.mdx +++ b/src/content/docs/factories/integrations/github.mdx @@ -22,10 +22,10 @@ When you connect a factory to GitHub, repository activity starts work in your fa That's all the setup GitHub needs. A new factory arrives with two automations already switched on, so it responds to GitHub activity right away: -* **Mentions and assignments** - Start work. See [Mention the factory](#mention-the-factory) below. -* **Pull request merges** - Close out work. Any work items linked to the pull request move to their tracker's completed state. Closing without merging does nothing. +* **Mentions and assignments** (`github-factory-mention-assign`) - Start work when **@warp-factory** is mentioned or assigned on an issue or pull request that carries the factory's `factory:` label. See [Mention the factory](#mention-the-factory). +* **Pull request closed or merged** (`github-pr-closed-or-merged`) - On pull requests with that same label, merging completes linked tracker items and the factory work item when Warp can resolve them. Closing without merging does nothing. -To confirm the connection works, mention the factory on a test issue and check that a work item starts in the factory's [dashboard](/factories/factory-dashboard/). +To confirm the connection works, add the factory's label to a test issue, mention **@warp-factory**, and check that a work item starts in the factory's [dashboard](/factories/factory-dashboard/). ## Add a custom automation @@ -99,18 +99,24 @@ Use filters to route work precisely. For example, send failed runs of a specific Handing an issue or pull request to a factory takes two things: -1. **Add the factory's label.** Each factory has one, named `factory:` followed by its [**Foreman name**](/factories/factory-dashboard/#change-factory-settings). For example, a factory whose foreman is named `payments` uses `factory:payments`. Warp creates the label in every connected repository, so it's already in the list. -2. **Mention or assign @warp-factory**, in the body or in any new comment. - -The factory picks up the request and replies in the same thread. +1. **Add the factory's label.** Each factory has one, named `factory:` followed by its [alias](/factories/factory-as-code/#alias) (the **Foreman name** under **Settings** > **Identity** in the factory dashboard). For example, alias `payments` uses `factory:payments`, not the factory's display name. Warp creates the label in each connected repository. +2. **Mention or assign @warp-factory** in the opening body or in a new comment. {/* VISUAL: An issue with the factory: label and an @warp-factory mention -- the two-part mention ritual is easy to miss from prose alone. */} -Both halves matter, because **@warp-factory** is the account every factory listens through. The label is what decides which of your factories answers, so a mention without one doesn't start work. +**@warp-factory** is the shared GitHub account every factory listens through. The label decides which factory answers. Default automations already filter on that label, and agents add it to every issue or pull request they open or adopt. + +If you mention **@warp-factory** without the label and no automation matches, Warp still tries to route the request when your GitHub account is linked to Warp: + +* **One accessible factory** is connected to the repository - Warp applies that factory's label and starts work. +* **More than one** - Warp asks you to add the right `factory:` label and mention **@warp-factory** again. +* **None** - Warp tells you to connect the repository or ask a factory admin for access. + +Default automations fire on matching GitHub activity even if the author isn't a Warp team member. Unlabeled fallback routing needs a linked Warp account. -Only new content counts as a mention. Edits to existing comments, mentions inside code blocks, and mentions from bots are ignored. +Only new human-authored content counts: the body when you open an issue or pull request, a newly created comment or review comment, or a submitted review. Comment edits, bot content, and mentions inside markdown code do not trigger. Mentions in inline review comments are handled when you submit the review. -You can change what the factory answers to. The handle and the label are the starting filters on its mentions automation: edit them to respond to a different handle, such as your own `@org/team` slug, or remove the label filter so that any mention in the factory's repositories starts work. +The handle and the label are the starting filters on the mentions automation. Edit them to respond to a different handle, such as your own `@org/team` slug, or remove the label filter so any mention in the factory's repositories starts work. Those filters capture the alias and repository list from when the factory was created. Changing either later does not rewrite them, so edit the automation if the filters need to match the current setup. ## How the factory responds on GitHub @@ -118,7 +124,7 @@ The factory posts progress comments in the originating issue, pull request, or r New activity on an issue, pull request, or review thread the factory is already working on continues that work item instead of starting a new one. -Issues and pull requests the factory opens carry its label, the same one you use to mention it. Warp adds the label to each repository you connect and removes it when you disconnect one or delete the factory, so you never create or clean it up by hand. If a label is ever left behind, delete it like any other GitHub label. +Issues and pull requests the factory opens or adopts carry its `factory:` label. Warp removes the label when you disconnect a repository or delete the factory. Renaming the alias does not rename existing labels, so an old label can remain. Delete leftovers like any other GitHub label. Branches and pull requests the factory creates follow the repository's normal rules: branch protection, required reviews, and merge requirements all still apply. @@ -139,6 +145,14 @@ These checks validate the factory's configuration files only. They don't create ## Troubleshooting +### A mention doesn't start work + +Confirm the mention is in new human-authored content, not an edit, a bot comment, or markdown code. The handle is **@warp-factory**, not **@warp-agent**. Then check that the issue or pull request has the factory's `factory:` label. + +If the label is missing, Warp routes an unlabeled mention only when your GitHub account is linked to Warp and you can access exactly one factory connected to the repository. If several factories share the repo, add the right label and mention **@warp-factory** again. + +If you renamed the alias or changed repositories after creating the factory, the default automation's filters still use the original snapshot. Edit that automation so the label and repository filters match. + ### A GitHub event doesn't start work Confirm the app installation covers the event's repository, the repository belongs to the factory, and the automation includes that event. Then check each filter; a label, author, branch, workflow, conclusion, or state mismatch prevents routing. From 8140a167a04a27c8d96b1e2ca6e7ef8366758c1c Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Fri, 28 Aug 2026 17:56:50 +0000 Subject: [PATCH 2/4] docs: tighten GitHub factory mention and label accuracy State the three ANDed seeded filters, describe label create/delete as asynchronous best-effort on installed user repos, derive factory: with normalization and shortening, and key fallback on accessible factories. Distinguish review-thread replies from submitted reviews. --- src/content/docs/factories/integrations/github.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/content/docs/factories/integrations/github.mdx b/src/content/docs/factories/integrations/github.mdx index c1da7a02..8c5ae44d 100644 --- a/src/content/docs/factories/integrations/github.mdx +++ b/src/content/docs/factories/integrations/github.mdx @@ -22,7 +22,7 @@ When you connect a factory to GitHub, repository activity starts work in your fa That's all the setup GitHub needs. A new factory arrives with two automations already switched on, so it responds to GitHub activity right away: -* **Mentions and assignments** (`github-factory-mention-assign`) - Start work when **@warp-factory** is mentioned or assigned on an issue or pull request that carries the factory's `factory:` label. See [Mention the factory](#mention-the-factory). +* **Mentions and assignments** (`github-factory-mention-assign`) - Start work when three filters are ANDed: the repository is one captured at create time, the issue or pull request has the `factory:` label, and **@warp-factory** is mentioned or assigned. See [Mention the factory](#mention-the-factory). * **Pull request closed or merged** (`github-pr-closed-or-merged`) - On pull requests with that same label, merging completes linked tracker items and the factory work item when Warp can resolve them. Closing without merging does nothing. To confirm the connection works, add the factory's label to a test issue, mention **@warp-factory**, and check that a work item starts in the factory's [dashboard](/factories/factory-dashboard/). @@ -99,7 +99,7 @@ Use filters to route work precisely. For example, send failed runs of a specific Handing an issue or pull request to a factory takes two things: -1. **Add the factory's label.** Each factory has one, named `factory:` followed by its [alias](/factories/factory-as-code/#alias) (the **Foreman name** under **Settings** > **Identity** in the factory dashboard). For example, alias `payments` uses `factory:payments`, not the factory's display name. Warp creates the label in each connected repository. +1. **Add the factory's label.** Each factory has one, derived from its [alias](/factories/factory-as-code/#alias) (the **Foreman name** under **Settings** > **Identity** in the factory dashboard) as `factory:`. Warp normalizes the alias and shortens it if needed so the full name stays within GitHub's label limit. For example, alias `payments` uses `factory:payments`, not the factory's display name. Warp attempts, asynchronously and best-effort, to create the label in each configured GitHub user repository covered by an active GitHub App installation. If that attempt fails, the label can be missing from the list. 2. **Mention or assign @warp-factory** in the opening body or in a new comment. {/* VISUAL: An issue with the factory: label and an @warp-factory mention -- the two-part mention ritual is easy to miss from prose alone. */} @@ -109,14 +109,14 @@ Handing an issue or pull request to a factory takes two things: If you mention **@warp-factory** without the label and no automation matches, Warp still tries to route the request when your GitHub account is linked to Warp: * **One accessible factory** is connected to the repository - Warp applies that factory's label and starts work. -* **More than one** - Warp asks you to add the right `factory:` label and mention **@warp-factory** again. +* **More than one accessible factory** - Warp asks you to add the right `factory:` label and mention **@warp-factory** again. * **None** - Warp tells you to connect the repository or ask a factory admin for access. Default automations fire on matching GitHub activity even if the author isn't a Warp team member. Unlabeled fallback routing needs a linked Warp account. -Only new human-authored content counts: the body when you open an issue or pull request, a newly created comment or review comment, or a submitted review. Comment edits, bot content, and mentions inside markdown code do not trigger. Mentions in inline review comments are handled when you submit the review. +Only new human-authored content counts: the body when you open an issue or pull request, a newly created conversation comment, a reply in an existing review thread, or a submitted review. Comment edits, bot content, and mentions inside markdown code do not trigger. A submitted review is one event that includes its summary and root inline comments; those inline comments do not start work on their own, and a mention in a review that is still pending does not start work. -The handle and the label are the starting filters on the mentions automation. Edit them to respond to a different handle, such as your own `@org/team` slug, or remove the label filter so any mention in the factory's repositories starts work. Those filters capture the alias and repository list from when the factory was created. Changing either later does not rewrite them, so edit the automation if the filters need to match the current setup. +The mentions automation starts with three ANDed filters: the repositories captured at create time, the `factory:` label, and **@warp-factory** as the mentioned user or assignee. Edit them to respond to a different handle, such as your own `@org/team` slug, or remove the label filter so any mention in the factory's repositories starts work. Changing the alias or connected repositories later does not rewrite those filters, so edit the automation if they need to match the current setup. ## How the factory responds on GitHub @@ -124,7 +124,7 @@ The factory posts progress comments in the originating issue, pull request, or r New activity on an issue, pull request, or review thread the factory is already working on continues that work item instead of starting a new one. -Issues and pull requests the factory opens or adopts carry its `factory:` label. Warp removes the label when you disconnect a repository or delete the factory. Renaming the alias does not rename existing labels, so an old label can remain. Delete leftovers like any other GitHub label. +Issues and pull requests the factory opens or adopts carry its `factory:` label. Warp attempts, asynchronously and best-effort, to remove the label from a configured GitHub user repository when you disconnect it or delete the factory, if an active GitHub App installation still covers that repository. If deletion fails, the label can be left behind. Renaming the alias does not rename existing labels, so an old label can remain. Delete leftovers like any other GitHub label. Branches and pull requests the factory creates follow the repository's normal rules: branch protection, required reviews, and merge requirements all still apply. @@ -149,7 +149,7 @@ These checks validate the factory's configuration files only. They don't create Confirm the mention is in new human-authored content, not an edit, a bot comment, or markdown code. The handle is **@warp-factory**, not **@warp-agent**. Then check that the issue or pull request has the factory's `factory:` label. -If the label is missing, Warp routes an unlabeled mention only when your GitHub account is linked to Warp and you can access exactly one factory connected to the repository. If several factories share the repo, add the right label and mention **@warp-factory** again. +If the label is missing, Warp routes an unlabeled mention only when your GitHub account is linked to Warp and you can access exactly one factory connected to the repository. If more than one accessible factory is connected to the repo, add the right label and mention **@warp-factory** again. If you renamed the alias or changed repositories after creating the factory, the default automation's filters still use the original snapshot. Edit that automation so the label and repository filters match. From a36ecfd400e3a9045d7b086b71dd10fff9dffa86 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Fri, 28 Aug 2026 18:01:31 +0000 Subject: [PATCH 3/4] docs: distinguish GitHub mention text from assignee control Step 2 of mentioning a factory treated assignment as if it were written in the issue body. Mention stays in new text; assignment uses GitHub's assignee control. --- src/content/docs/factories/integrations/github.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/factories/integrations/github.mdx b/src/content/docs/factories/integrations/github.mdx index 8c5ae44d..2c6b4da2 100644 --- a/src/content/docs/factories/integrations/github.mdx +++ b/src/content/docs/factories/integrations/github.mdx @@ -100,7 +100,7 @@ Use filters to route work precisely. For example, send failed runs of a specific Handing an issue or pull request to a factory takes two things: 1. **Add the factory's label.** Each factory has one, derived from its [alias](/factories/factory-as-code/#alias) (the **Foreman name** under **Settings** > **Identity** in the factory dashboard) as `factory:`. Warp normalizes the alias and shortens it if needed so the full name stays within GitHub's label limit. For example, alias `payments` uses `factory:payments`, not the factory's display name. Warp attempts, asynchronously and best-effort, to create the label in each configured GitHub user repository covered by an active GitHub App installation. If that attempt fails, the label can be missing from the list. -2. **Mention or assign @warp-factory** in the opening body or in a new comment. +2. Mention **@warp-factory** in the opening body or a new comment, or assign **@warp-factory** with GitHub's assignee control. {/* VISUAL: An issue with the factory: label and an @warp-factory mention -- the two-part mention ritual is easy to miss from prose alone. */} From 3d1e7dc26f2532e948881fe1b28326ea3bcc3335 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Fri, 28 Aug 2026 19:43:07 +0000 Subject: [PATCH 4/4] docs: address review feedback, trim GitHub factory mention/label prose - Drop the automation names, ANDed-filter enumeration, and per-event list from the mentions/labels flow. - Drop the best-effort/async GitHub App caveats for label create and delete; keep the underlying facts (label derived from alias, label removed on disconnect/delete, alias rename leaves old labels). - Drop the assign-as-alternative-to-mention detail. - Revert the mention-counts-as and automation-filters paragraphs toward their pre-PR concise phrasing. --- .../docs/factories/integrations/github.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/content/docs/factories/integrations/github.mdx b/src/content/docs/factories/integrations/github.mdx index 2c6b4da2..dc9ae85e 100644 --- a/src/content/docs/factories/integrations/github.mdx +++ b/src/content/docs/factories/integrations/github.mdx @@ -22,10 +22,10 @@ When you connect a factory to GitHub, repository activity starts work in your fa That's all the setup GitHub needs. A new factory arrives with two automations already switched on, so it responds to GitHub activity right away: -* **Mentions and assignments** (`github-factory-mention-assign`) - Start work when three filters are ANDed: the repository is one captured at create time, the issue or pull request has the `factory:` label, and **@warp-factory** is mentioned or assigned. See [Mention the factory](#mention-the-factory). -* **Pull request closed or merged** (`github-pr-closed-or-merged`) - On pull requests with that same label, merging completes linked tracker items and the factory work item when Warp can resolve them. Closing without merging does nothing. +* **Mentions and assignments** - Start work by mentioning **@warp-factory**. See [Mention the factory](#mention-the-factory) below. +* **Pull request merges** - Close out work by merging a pull request with your factory's label. -To confirm the connection works, add the factory's label to a test issue, mention **@warp-factory**, and check that a work item starts in the factory's [dashboard](/factories/factory-dashboard/). +To confirm the connection works, mention **@warp-factory** on a test issue and check that a work item starts in the factory's [dashboard](/factories/factory-dashboard/). ## Add a custom automation @@ -99,8 +99,8 @@ Use filters to route work precisely. For example, send failed runs of a specific Handing an issue or pull request to a factory takes two things: -1. **Add the factory's label.** Each factory has one, derived from its [alias](/factories/factory-as-code/#alias) (the **Foreman name** under **Settings** > **Identity** in the factory dashboard) as `factory:`. Warp normalizes the alias and shortens it if needed so the full name stays within GitHub's label limit. For example, alias `payments` uses `factory:payments`, not the factory's display name. Warp attempts, asynchronously and best-effort, to create the label in each configured GitHub user repository covered by an active GitHub App installation. If that attempt fails, the label can be missing from the list. -2. Mention **@warp-factory** in the opening body or a new comment, or assign **@warp-factory** with GitHub's assignee control. +1. **Add the factory's label.** Each factory has one, derived from its [alias](/factories/factory-as-code/#alias) (the **Foreman name** under **Settings** > **Identity** in the factory dashboard) as `factory:`. For example, alias `payments` uses `factory:payments`, not the factory's display name. Warp creates the label automatically when you create the factory. +2. Mention **@warp-factory** in the opening body or a new comment. {/* VISUAL: An issue with the factory: label and an @warp-factory mention -- the two-part mention ritual is easy to miss from prose alone. */} @@ -114,9 +114,9 @@ If you mention **@warp-factory** without the label and no automation matches, Wa Default automations fire on matching GitHub activity even if the author isn't a Warp team member. Unlabeled fallback routing needs a linked Warp account. -Only new human-authored content counts: the body when you open an issue or pull request, a newly created conversation comment, a reply in an existing review thread, or a submitted review. Comment edits, bot content, and mentions inside markdown code do not trigger. A submitted review is one event that includes its summary and root inline comments; those inline comments do not start work on their own, and a mention in a review that is still pending does not start work. +Only new content counts as a mention. Edits to existing comments, mentions inside code blocks, and mentions from bots are ignored. -The mentions automation starts with three ANDed filters: the repositories captured at create time, the `factory:` label, and **@warp-factory** as the mentioned user or assignee. Edit them to respond to a different handle, such as your own `@org/team` slug, or remove the label filter so any mention in the factory's repositories starts work. Changing the alias or connected repositories later does not rewrite those filters, so edit the automation if they need to match the current setup. +You can change what the factory answers to. The handle and the label are the starting filters on its mentions automation: edit them to respond to a different handle, such as your own `@org/team` slug, or remove the label filter so that any mention in the factory's repositories starts work. ## How the factory responds on GitHub @@ -124,7 +124,7 @@ The factory posts progress comments in the originating issue, pull request, or r New activity on an issue, pull request, or review thread the factory is already working on continues that work item instead of starting a new one. -Issues and pull requests the factory opens or adopts carry its `factory:` label. Warp attempts, asynchronously and best-effort, to remove the label from a configured GitHub user repository when you disconnect it or delete the factory, if an active GitHub App installation still covers that repository. If deletion fails, the label can be left behind. Renaming the alias does not rename existing labels, so an old label can remain. Delete leftovers like any other GitHub label. +Issues and pull requests the factory opens or adopts carry its `factory:` label. Warp removes the label when you disconnect the repository or delete the factory. Renaming the alias does not rename existing labels, so an old label can remain. Delete leftovers like any other GitHub label. Branches and pull requests the factory creates follow the repository's normal rules: branch protection, required reviews, and merge requirements all still apply.