diff --git a/src/content/docs/factories/automation-filters.mdx b/src/content/docs/factories/automation-filters.mdx index 6a64b4419..115401eb0 100644 --- a/src/content/docs/factories/automation-filters.mdx +++ b/src/content/docs/factories/automation-filters.mdx @@ -5,7 +5,6 @@ description: >- runs — matching rules, per-source filters, and what they don't control. sidebar: label: Automation filters -topic: factories --- Automation filters decide which events from your connected tools start factory work. Every trigger on a [factory automation](/factories/connect-your-factory/) carries filters — conditions such as a repository, channel, team, project, label, or author — and an event starts a run only when it matches them. Filters let a factory watch busy channels and repositories without acting on everything in them. @@ -14,9 +13,9 @@ Automation filters decide which events from your connected tools start factory w An event starts an automation only when it matches the trigger's provider, its event type, and every filter set on that trigger: -* **Every filter must match** - Filters combine with AND. A trigger that sets both a team and a label matches only events that carry both. -* **Within a filter, any value matches** - Values combine with OR. A **Labels** filter listing `bug` and `regression` matches an issue that carries either label. -* **An empty filter matches everything** - A filter you leave unset doesn't constrain matching, and a trigger with no filters starts work for every event of its type that the connection delivers. +* **Every filter must match.** A trigger that sets both a team and a label matches only events carrying both. +* **Within one filter, any value matches.** A **Labels** filter listing `bug` and `regression` matches an issue with either label. +* **A filter you leave empty matches everything.** A trigger with no filters at all starts work for every event of its type. One event can match more than one automation, and each match starts its own run. If a single action starts duplicate runs, narrow or remove one of the overlapping triggers. diff --git a/src/content/docs/factories/connect-your-factory.mdx b/src/content/docs/factories/connect-your-factory.mdx index 100eb419e..c6628b1c9 100644 --- a/src/content/docs/factories/connect-your-factory.mdx +++ b/src/content/docs/factories/connect-your-factory.mdx @@ -83,7 +83,7 @@ See the [triggers overview](/platform/triggers/) for how schedules and other tri * **Follow-ups continue the same work item** - Replying in the same Slack thread, GitHub issue or pull request, Linear issue, or Jira agent session adds to the existing work item instead of starting a new one. Repeated event deliveries from a provider don't create duplicate work either. * **One issue tracker per factory** - A factory can use [Linear](/factories/integrations/linear/) or [Jira](/factories/integrations/jira/), or no tracker at all, but not both at once. The setup wizard currently offers Linear; to use Jira, connect it after setup or in your [factory definition](/factories/factory-as-code/). -* **Filters route work; they don't restrict access** - Automation filters (repository, channel, team, project, label, author, or status) choose which requests start work. To limit what an integration can reach, change what you authorize for that provider instead. See [automation filters](/factories/automation-filters/) for the matching rules. -* **The factory hands off at the pull request** - It pushes branches and opens pull requests with the repository credentials you configure, and waits for a human to review and merge. Branch protection and required reviews apply as usual. +* **Filters route work; they don't restrict access** - Choosing which requests start work is separate from what a running agent can reach. See [automation filters](/factories/automation-filters/#filters-route-work-they-dont-restrict-access). +* **The factory hands off at the pull request** - It pushes branches and opens pull requests, then waits for a person. See [what humans decide](/factories/how-factories-work/#what-humans-decide). Next, customize which agents receive work and how it's routed with [factory definitions as code](/factories/factory-as-code/). diff --git a/src/content/docs/factories/factory-agents.mdx b/src/content/docs/factories/factory-agents.mdx index 9cfcbb537..bced0ab9b 100644 --- a/src/content/docs/factories/factory-agents.mdx +++ b/src/content/docs/factories/factory-agents.mdx @@ -5,7 +5,6 @@ description: >- the work, plus triage, spec, implement, and review agents. sidebar: label: "Factory agents" -topic: factories --- Every factory has a small team of agents, and each agent has a specific job. The foreman coordinates the work and holds one continuous conversation with the person who requested it; the other agents investigate, plan, build, and check the work. Together, they take a work item from the moment it reaches your factory to a finished pull request that's ready for a human to review. @@ -76,7 +75,7 @@ Factory setup doesn't choose models for you. To change the model a role uses, ed Each role can run on its own model and harness. Supported harnesses include the Warp Agent harness, Claude Code, and Codex, and any role can use any of them. A foreman running on Claude Code or Codex can still dispatch the factory's other agents, and the runs it starts are still tracked as its children. :::note -Third-party harnesses require a Build plan or higher. On the Free plan, every role runs on the Warp Agent harness. See [Warp pricing](https://www.warp.dev/pricing) for what each plan includes. +Third-party harnesses require a Build plan or higher; on the Free plan every role runs on the Warp Agent harness. See [harnesses](/platform/harnesses/#plan-requirements). ::: Default model IDs change over time, so choose based on what each role has to do well: diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx index b2d952a79..5359ee4db 100644 --- a/src/content/docs/factories/factory-as-code.mdx +++ b/src/content/docs/factories/factory-as-code.mdx @@ -5,7 +5,6 @@ description: >- automations, runners, and skills. sidebar: label: "Definitions as code" -topic: factories --- import { VARS } from '@data/vars'; diff --git a/src/content/docs/factories/factory-mcp.mdx b/src/content/docs/factories/factory-mcp.mdx index e0fb37a8d..94772690f 100644 --- a/src/content/docs/factories/factory-mcp.mdx +++ b/src/content/docs/factories/factory-mcp.mdx @@ -5,7 +5,6 @@ description: >- tasks locally, and hand results back. sidebar: label: "Factory MCP" -topic: factories --- Factory MCP is a hosted Model Context Protocol (MCP) server that connects coding agents to your Warp Factories. With it, the agent you already work with, in Warp or in any MCP-capable tool, can send work to a factory, pick up a factory task to continue locally, and hand the finished work back. diff --git a/src/content/docs/factories/infrastructure-and-security.mdx b/src/content/docs/factories/infrastructure-and-security.mdx index b65465d73..1477ecd57 100644 --- a/src/content/docs/factories/infrastructure-and-security.mdx +++ b/src/content/docs/factories/infrastructure-and-security.mdx @@ -38,7 +38,7 @@ Two configurations define where and how a factory's agents work: | **Environment** | What an agent works on: the workspace and runtime context | Repositories, setup commands, secrets, toolchain image, and provider configuration | | **Runner** | Where the work executes: the compute | Operating system, architecture, sandbox image, vCPUs, and memory | -You don't manage a factory's environment directly: each factory implicitly manages one based on the repositories configured in its [definition](/factories/factory-as-code/). Runners are the choice you make. When a run starts, Warp resolves its compute in a fixed order: the runner the run selects explicitly, then the environment's execution defaults, then the system default. See [environments](/platform/environments/) for the underlying workspace model and the [runner reference](/platform/runners/) for compute options and resolution behavior. +You don't manage a factory's environment directly — each factory keeps one in step with the repositories in its [definition](/factories/factory-as-code/). Runners are the choice you make. See [environments](/platform/environments/) for the underlying workspace model and the [runner reference](/platform/runners/) for compute options and how a run picks one. The **Runners** section of a factory's **Settings** page in the [factory dashboard](/factories/factory-dashboard/) shows each runner's operating system and architecture, setup commands, size, and whether it's the default. Where you edit runners depends on where the factory's source lives: diff --git a/src/content/docs/factories/integrations/github.mdx b/src/content/docs/factories/integrations/github.mdx index e97c533bd..b7a9880ef 100644 --- a/src/content/docs/factories/integrations/github.mdx +++ b/src/content/docs/factories/integrations/github.mdx @@ -5,7 +5,6 @@ description: >- events start factory work and results post back to GitHub. sidebar: label: "GitHub" -topic: factories --- import { VARS } from '@data/vars'; @@ -21,19 +20,16 @@ When you connect a factory to GitHub, repository activity starts work in your fa 1. In the {VARS.FACTORY_WEB_APP} at platform.warp.dev, click **+** next to **Factories** to open the setup wizard, then choose **I want to use repos from GitHub** under **Connect your code host**. 2. Under **Select your repos**, choose the repositories to provide code and context for the factory. -That's all the setup GitHub needs. Managed GitHub factories are created with two editable default automations, so the factory responds to GitHub activity without you configuring anything else. The first handles agent mentions and assignments (see [Mention the factory](#mention-the-factory)). The second runs when a pull request closes or merges: on a merge it finds the work items linked from the pull request and moves each one to its tracker's completed state, and on a close without a merge it does nothing. +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. 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/). ## Add a custom automation -The defaults cover mentions, assignments, and pull request completion. To start work from any other GitHub activity, such as a failed CI run or a review request, add your own automation: - -1. In the factory's [dashboard](/factories/factory-dashboard/), click **Automations**. Create an automation or edit a default one, choose the receiving agent, and add any **Additional instructions**. -2. Under **Triggers**, click **Add trigger**. -3. Choose **GitHub**, then choose an event. -4. Select a repository, then use **More filters** to narrow which activity matches. -5. Click **Save**. To confirm the automation works, trigger a matching event in GitHub, such as opening a test issue, and check that a work item starts in the factory dashboard. +The defaults cover mentions, assignments, and pull request completion. To start work from any other GitHub activity — a failed CI run or a review request, say — add an automation with a **GitHub** trigger for that event, then narrow it with the filters below. [Automation filters](/factories/automation-filters/#edit-filters-on-an-automation) covers the steps. ## Supported triggers @@ -49,11 +45,11 @@ The defaults cover mentions, assignments, and pull request completion. To start IssuesCreated, labeled, assigned, or agent mentioned Pull requestsOpened, marked ready, reopened, updated with commits, assigned, labeled, mentioned, closed, or merged ReviewsReview requested or review submitted -Code and CIPush, completed check suite or workflow run, or a re-requested Warp-owned check +Code and CIPush, a completed check suite or workflow run, or a re-run of a Warp check -Re-requesting a check triggers the factory only when the Warp GitHub App created that check. GitHub doesn't deliver re-request events for third-party CI checks. +Re-running a check starts work only for checks Warp itself created. GitHub doesn't send re-run events for other providers' checks, so those can't trigger a factory. ### Automation filters @@ -73,22 +69,24 @@ Every trigger names the repository it watches. The remaining filters appear only | **Workflows** | The GitHub Actions workflow, by name | Workflow run triggers | | **Conclusions** | The run's result: success, failure, cancelled, and so on | Check suite and workflow run triggers | -CI payloads don't carry issue or label data, so on check suite and workflow run triggers, **Labels** and **Authors** match against the pull request linked to the run. +On check suite and workflow run triggers, **Labels** and **Authors** match the pull request linked to the run rather than the run itself. Use filters to route work precisely. For example, send failed runs of a specific workflow to a CI-repair automation. ## Mention the factory -A factory doesn't get its own GitHub handle. Every factory listens through the same Warp agent account, **@warp-factory**, and the factory's `factory:` label decides which factory a mention reaches, where `` is the factory's [**Foreman name**](/factories/factory-as-code/#alias): +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) — 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. -1. Apply the factory's `factory:` label to the issue or pull request. Warp creates the label in each connected repository. -2. Assign **@warp-factory** to the issue or pull request, or mention **@warp-factory** in the body or in any new comment. +The factory picks up the request and replies in the same thread. -The default mentions-and-assignments automation starts a work item in the matching factory, and the factory replies in the same thread. The label is what routes the request. A mention without the factory's label doesn't match the default automation. +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. -Mentions count only in new content; edits to existing comments, mentions inside code blocks, and mentions from bots are ignored. +Only new content counts as a mention. Edits to existing comments, mentions inside code blocks, and mentions from bots are ignored. -The handle and label are default filter values, not fixed rules. Edit the automation's **Mentioned users or teams** filter to respond to other handles, such as your own `@org/team` slug, or remove the label filter to catch every mention in the factory's repositories. +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 @@ -96,22 +94,22 @@ 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 created by the factory carry a `factory:` label. Warp adds that label to every connected repository and removes it when you disconnect a repository or delete the factory, so you never create it by hand. Both passes are best-effort: if GitHub rejects one, a stale label can linger and needs deleting manually. +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. -Factory-created branches and pull requests follow the repository's normal rules: branch protection, required reviews, and merge requirements still apply. +Branches and pull requests the factory creates follow the repository's normal rules — branch protection, required reviews, and merge requirements all still apply. ## Permissions Runs authenticate with the GitHub App installation, not with the account of the person whose activity triggered them: -* **The app installation decides what agents can reach.** Agents get exactly the repositories and permissions the installation grants. Factory repositories and automation filters control when work starts, not what a running agent can reach. To change access, change the installation. +* **The app installation decides what agents can reach.** Agents get exactly the repositories and permissions the installation grants, so change the installation to change access — [automation filters](/factories/automation-filters/) only change when work starts. * **Anyone who can create matching activity can start work.** The event author doesn't need to be a Warp team member. Use author, label, and branch filters to control what starts runs. For the full credential model, see [Permissions and identity](/platform/integrations/github/#permissions-and-identity) on the GitHub integration page. ## Factory-definition pull request checks -If the factory's [definition is managed as code](/factories/factory-as-code/) in a GitHub repository, Warp reviews configuration changes like CI reviews code. When a pull request targets the production branch and changes files in the registered factory directory, a **warp/factory-config** check runs: it passes with a summary of the change, or fails with diagnostics on what to fix. Require the check in branch protection to block invalid definitions from merging. +If the factory's [definition is managed as code](/factories/factory-as-code/) in a GitHub repository, Warp reviews changes to it the way CI reviews code. Open a pull request that touches the definition files and a **warp/factory-config** check runs: it passes with a summary of what the change does, or fails with the specific fields to fix. Require the check in branch protection to stop an invalid definition from merging. These checks validate the factory's configuration files only. They don't create work items, and pull requests that don't touch the factory directory don't get the check. @@ -131,4 +129,4 @@ Check that the installation still covers the target repository and grants the re ### A factory-definition check doesn't appear -The check runs only for factories whose [definition is managed as code](/factories/factory-as-code/) in a GitHub repository. Confirm the pull request targets the definition's production branch, changes files under the registered factory directory, and that the GitHub App covers the repository. +The check runs only for factories whose [definition is managed as code](/factories/factory-as-code/) in a GitHub repository. Confirm the pull request targets the branch the factory runs from, that it changes files in the factory's definition directory, and that the GitHub App covers the repository. diff --git a/src/content/docs/factories/integrations/gitlab.mdx b/src/content/docs/factories/integrations/gitlab.mdx index feafc5252..c7699c240 100644 --- a/src/content/docs/factories/integrations/gitlab.mdx +++ b/src/content/docs/factories/integrations/gitlab.mdx @@ -5,7 +5,6 @@ description: >- factory work and results post back as comments and merge requests. sidebar: label: "GitLab" -topic: factories --- import { VARS } from '@data/vars'; @@ -17,25 +16,20 @@ When you connect a factory to GitLab, project activity starts work in your facto * **A top-level GitLab group you own** - Connecting GitLab links one top-level group to your Warp workspace, one-to-one. Creating the link requires the Owner role on the group and workspace admin permissions in Warp. * **A GitLab plan with service accounts and group webhooks** - Warp provisions service accounts in your group and installs a group webhook. Both are GitLab Premium and Ultimate features. On a plan without group webhooks, factory credentials still work, but GitLab cannot trigger runs. -## Service accounts and access +## Your factory's GitLab identity -Warp manages GitLab access through service accounts it creates in your connected group rather than a marketplace app: +Each factory gets its own GitLab service account — its bot. The bot is the factory's identity on GitLab: its username is the handle you mention, runs act as it, and the projects it belongs to are exactly the ones you select for the factory. Warp creates and retires these accounts for you. -* **One manager account per workspace** - Created when you connect the group and granted the Owner role on it. Warp uses it to provision factory accounts, mint their run credentials, and maintain the group webhook. Its provisioning token is valid for one year. -* **One bot account per factory** - Each factory gets its own service account, named from the factory's alias plus a `-warp-` suffix and a short unique ID (for example, `acme-support-warp-01k2x3y4z5`). The bot holds the Developer role on exactly the projects you select for the factory. It is the factory's identity on GitLab. Runs authenticate as the bot, and its username is the handle you mention. +## Connect GitLab to a factory -The connected group's webhook delivers merge request and comment events to Warp, and matching automations turn them into factory work. +When you create a factory, choose **I want to use repos from GitLab** as the code host, then: -## Connect GitLab to a factory +1. **Connect a top-level group.** Warp links it to your Warp workspace and sets up event delivery from it. A group already connected to your workspace is selected for you. +2. **Select the projects the factory works in.** Anything under the connected group is available, including projects in subgroups. + +That's the setup. A GitLab factory starts with one default automation, **gitlab-bot-mentions**, so mentioning the bot in a merge request comment starts work right away. To confirm it, do exactly that: comment on a merge request in one of the selected projects, mention the bot, and watch for a work item in the factory's [dashboard](/factories/factory-dashboard/). -1. In the {VARS.FACTORY_WEB_APP}, click **+** next to **Factories** to open the setup wizard. -2. Choose **I want to use repos from GitLab** under **Connect your code host**, then authorize with GitLab when prompted. -3. Under **Connect a GitLab group**, pick a top-level group you own and click **Next**. Warp creates the manager service account and installs the group webhook. A group that is already connected shows a **Connected** badge, and the selection is locked to it. -4. Under **Select your repos**, choose the projects to provide code and context for the factory. Projects anywhere under the connected group, including subgroups, are available. -5. In the factory's [dashboard](/factories/factory-dashboard/), click **Automations**. GitLab factories start with an editable default automation, **gitlab-bot-mentions**, that fires when the factory's bot is mentioned. -6. To route merge request events too, create an automation and click **Add trigger**. -7. Choose **GitLab**, then choose **Merge request**. -8. To confirm the connection works, comment on a merge request in a selected project and mention the factory's bot. A work item starts in the factory dashboard, and the factory replies in the same thread. +To start work from merge request events as well, add a **Merge request** trigger to an automation — see [automation filters](/factories/automation-filters/#edit-filters-on-an-automation). ## Supported triggers @@ -61,7 +55,7 @@ The connected group's webhook delivers merge request and comment events to Warp, | **Actions** | What happened to the merge request, such as opened, updated, or merged | Merge request | | **Base branch** | The branch the merge request targets | Merge request | -On the **Bot mentioned** trigger, the mention username is managed by Warp. It is always the factory's own bot, shown as read-only in the automation editor, and it cannot be set in a definition file. +The **Bot mentioned** trigger always listens for the factory's own bot. You can't point it at a different username. ## Mention the factory @@ -80,19 +74,19 @@ The factory acts on GitLab as its bot account: * **Replies in the thread it was mentioned in** - Its comments link back to the run session and the factory work item. New comments on the same merge request continue that work item instead of starting a new one. * **Pushes branches and opens draft merge requests** - Branches are named `factory/`, and merge requests open as drafts that the factory marks ready when the work is done. Commits and comments attribute to the bot's GitLab profile. -* **Labels what it touches** - Merge requests and issues the factory opens or adopts carry its `factory:` label. +* **Labels what it touches** - Merge requests and issues the factory opens or adopts carry its own label, named `factory:` followed by the factory's Foreman name. * **Posts review feedback as comments** - A review lands as a summary note plus inline discussions on the diff. When a later revision addresses a finding, the factory replies in that discussion and resolves it. -The factory never merges or approves a merge request. Those decisions stay with your team, and branch protection and approval rules apply to everything the bot does. +The factory never merges or approves a merge request, and your project's protection and approval rules apply to everything the bot does. ## Permissions Runs authenticate as the factory's bot account, not as the person whose activity triggered them: -* **The bot's project membership decides what runs can reach.** Each run gets a short-lived token scoped to the bot's Developer role on the factory's selected projects. Selecting projects for a factory or tightening automation filters changes when work starts, not what a running agent can access. To change access, change the factory's projects. +* **The bot's project membership decides what runs can reach.** A run can reach the projects the factory selected, with the bot's Developer role, and nothing else. To change what it can reach, change the factory's projects — [automation filters](/factories/automation-filters/) only change when work starts. * **Anyone who can create matching activity can start work.** The commenter doesn't need to be a Warp team member. Use project, action, and base-branch filters to control what starts runs. -Disconnecting GitLab from the workspace retires the manager and every factory bot it provisioned. +Disconnecting GitLab from your workspace retires every factory bot along with it. ## Definitions as code @@ -113,7 +107,7 @@ triggers: Triage newly opened merge requests and post an initial review. ``` -A `bot_mentioned` trigger takes only a `repos` filter. Leave `mentioned` out. Warp seeds it with the factory's bot username and rejects definitions that set it. +A `bot_mentioned` trigger takes only a `repos` filter — leave `mentioned` out, since the bot username isn't yours to set. A GitLab-backed factory can still be managed as code, but the definition itself lives either in Warp or in a GitHub repository — GitLab is not yet available as a definition host. See [where the definition lives](/factories/factory-as-code/#where-the-definition-lives). diff --git a/src/content/docs/factories/integrations/jira.mdx b/src/content/docs/factories/integrations/jira.mdx index 1ec29369d..2af1d1cd8 100644 --- a/src/content/docs/factories/integrations/jira.mdx +++ b/src/content/docs/factories/integrations/jira.mdx @@ -5,7 +5,6 @@ description: >- factory runs and return results in Jira. sidebar: label: Jira -topic: factories --- import { VARS } from '@data/vars'; @@ -20,17 +19,13 @@ Connect Jira Cloud to your factory so your team can start factory work without l ## Connect Jira and add an automation -1. Install the Warp app on your Jira site. In the Integrations page of the {VARS.WEB_APP}, find Jira and click **Set up**, then click **Get app** on the Atlassian installation page and install the app on your Jira Cloud site. +1. **Install the Warp app on your Jira site and connect it to your Warp workspace.** The [Jira integration setup](/platform/integrations/jira/#setup) walks through both. Once connected, every factory in the workspace can use it. (That page's `warp-agent` label flow starts standalone cloud agent runs; factories skip the label and use an automation instead.) -2. Connect the installation to your Warp workspace. In Jira, open **Manage apps** and open the Warp app's **Configure** page, then click **Connect to Warp** and sign in to Warp if prompted. The page shows **Connected to Warp** when the connection succeeds, and every factory in the workspace can then use it. +2. **Connect Jira to this factory.** A workspace connection makes Jira available to your factories, but each one opts in separately: in the factory's **Settings**, connect **Jira** and select the projects that should trigger it. - The [Jira integration setup](/platform/integrations/jira/#setup) covers installation in more detail. The `warp-agent` label flow on that page starts standalone cloud agent runs; factories skip the label and start runs through an automation instead. +3. **Point an automation at Jira.** In the factory's dashboard, open **Automations** and add a trigger for **Jira** > **Agent session created**. Use **Projects** and, optionally, **Keywords** to scope which sessions start a run, and choose the agent that handles them. -3. Connect Jira to your factory. Connecting the workspace in step 2 makes Jira available to every factory in it, but each factory still needs its own connection: in the factory's **Settings** tab, find **Jira** and click **Connect** (or **Install** if the workspace itself isn't connected yet). Select the Jira projects that should trigger this factory, then click **Enable**. This declares the `jira` integration for the factory. Without it, **Jira** in the automation editor's **Add trigger** menu stays a disabled "not connected" entry that links back to this step. - -4. Add a Jira trigger to an automation. In the factory's dashboard, open **Automations**, then open an automation (or create a new one). Click **Add trigger**, choose **Jira**, and select **Agent session created**. Set **Projects** and, optionally, **Keywords** to scope which sessions start a run, then set the automation's agent to the one that should handle matching requests. - - If you selected Jira projects when you created the factory, Warp already added an automation scoped to those projects; edit that automation instead of creating a second one. + If you picked Jira projects when you created the factory, that automation already exists — edit it rather than adding a second one. Prefer definitions as code? Declare the `jira` integration in the factory's `factory.yaml` (`integrations: [{type: jira}]`), then add a file under `automations/`, such as `automations/jira-assignment/automation.md`, with an `agent_session_created` trigger: @@ -51,7 +46,7 @@ Connect Jira Cloud to your factory so your team can start factory work without l With this automation, the agent named `foreman` handles sessions for work items in the `ENG` project whose assignment text contains `investigate` or `fix`. Commit and push the files to apply them; see [definitions as code](/factories/factory-as-code/) for the full syntax. -5. Save the automation, or commit and push the definition if you used definitions as code. Then test it: assign or mention **Warp** on a work item and include an instruction. Jira starts an agent session, and the run appears under the matching automation in your factory. +4. **Test it.** Assign or mention **Warp** on a work item and include an instruction. Jira starts an agent session, and the run appears under the matching automation in your factory. ## Filter which sessions start runs @@ -63,7 +58,7 @@ All Jira work reaches the factory through a single event, `agent_session_created A session must match every field you set; within a field, any listed value is a match. Omit a field to match everything. For the matching rules shared by every source, see [automation filters](/factories/automation-filters/). :::caution -Filters like `project_keys` decide whether *your* automation starts a run; they aren't an access boundary. A Jira event is evaluated against every team's automations in the connected workspace, so another team's automation with a broader or different filter can still start its own run on the same work item. Installing the Warp app doesn't scope its Jira access to specific projects either. +A Jira event is offered to every automation in the connected workspace, so another team's automation with a broader filter can start its own run on the same work item. Filters decide what *your* automation picks up, not who else can see the event — see [automation filters](/factories/automation-filters/#filters-route-work-they-dont-restrict-access). ::: ## What happens during a run @@ -79,7 +74,7 @@ When the run finishes, the result appears in the agent session. The agent doesn' ## Permissions * **A bound Jira user becomes the run's creator, not its agent** - [Connect your Jira account to Warp](/platform/integrations/jira/#connecting-your-jira-account-to-warp) so a session you start is attributed to you; an unconnected account gets a prompt to connect instead of a run starting. Either way, the run executes as the agent selected by the automation, not as that Jira user. -* **Jira access doesn't include code access** - Connecting Jira lets agents read and update Jira work items, nothing more. Agents get repository access from the factory itself, and pull requests they open go through your usual review and merge process. +* **Jira access doesn't include code access** - Connecting Jira lets agents read and update Jira work items, nothing more. Repository access comes from the factory itself. ## Troubleshooting diff --git a/src/content/docs/factories/integrations/linear.mdx b/src/content/docs/factories/integrations/linear.mdx index fd9533f80..d634fce56 100644 --- a/src/content/docs/factories/integrations/linear.mdx +++ b/src/content/docs/factories/integrations/linear.mdx @@ -5,19 +5,11 @@ description: >- progress flows back to the issue. sidebar: label: "Linear" -topic: factories --- -Connect Linear to your factory so your team can send it issues without leaving Linear. Assign an issue to the factory or tag it in a comment, and the factory picks up the issue with its full context. +Connect Linear to your factory so your team can send it issues without leaving Linear. Assign an issue to the factory or tag it in a comment, and the factory picks it up with the issue's full context, then keeps the issue updated as the work moves through [its stages](/factories/how-factories-work/). -From there, the factory routes the issue through its stages, triage through review, and keeps the Linear issue updated as work progresses, so your team can follow along without switching tools. If you're new to factories, see [how Warp Factories work](/factories/how-factories-work/) for the lifecycle. - -When the factory needs human input, respond in Linear or open the live factory run to inspect and steer the agent directly. - -Two parts work together: - -* **The Linear connection** - Grants Warp access to your Linear workspace. -* **Factory automations** - Decide which Linear events start work and which agent handles them. +When the factory needs an answer, reply in Linear, or open the live run to steer the agent directly. ## Prerequisites @@ -28,48 +20,26 @@ Two parts work together: For workspace-level installation, reconnection, and removal steps, see the [Linear integration setup guide](/platform/integrations/linear/). -## Connect Linear during factory setup - -When you create a factory, the setup flow includes a **Connect your issue trackers** step: - -1. On the **Linear** row, click **Connect**. -2. Complete Linear's OAuth flow for the workspace you want to connect. When you return, the **Linear** row shows as connected. -3. Under **Linear team**, select the Linear teams that should trigger your factory. - -When setup completes, Warp creates a default automation that routes new [agent sessions](#route-agent-sessions) from the selected teams to your factory. Issue and comment events don't start work until you [add triggers](#configure-linear-triggers) for them. - -## Connect Linear from factory settings +## Connect Linear -If you skipped Linear during setup, connect it from the factory's settings: +You connect Linear either while creating a factory, at the **Connect your issue trackers** step, or afterward from the factory's **Settings**. Either way you do the same two things: -1. In your factory, open **Settings** and go to the **Factory integrations** section. -2. On the **Linear** row, click **Connect**. If the workspace hasn't authorized Warp yet, complete Linear's OAuth flow first. -3. Under **Linear teams**, select the teams that should trigger your factory, then click **Enable**. +1. **Authorize Warp for your Linear workspace.** This is Linear's own OAuth flow, and it's only needed once per workspace. +2. **Choose which Linear teams trigger this factory.** -Both paths end in the same state: Linear is connected to your factory, and a default automation routes agent sessions from the selected teams. +Warp then adds a default automation that routes new [agent sessions](#route-agent-sessions) from those teams to your factory. Issue and comment activity doesn't start work until you [add triggers](#configure-linear-triggers) for it. ## Route agent sessions When someone mentions, assigns, or delegates the Warp app on an issue, Linear starts an agent session. The default automation created when you connected Linear routes new sessions from your selected teams to the factory, so assigning an issue or tagging the factory in a comment is enough to start work. If a session doesn't match any automation, the [Linear integration](/platform/integrations/linear/) handles it with its default behavior. -Agent sessions don't appear as a trigger in the [automation editor](#configure-linear-triggers). To change how sessions route, for example by creator or keyword, edit the `agent_session_created` event in the factory's [version-controlled definition](/factories/factory-as-code/). Replies in an existing session continue that run; they aren't separate triggers. +Replies in an existing session continue that run rather than starting a new one. To narrow which sessions reach the factory — by creator or keyword, say — edit the `agent_session_created` trigger in the factory's [definition files](/factories/factory-as-code/); session routing isn't editable from the automation editor. ## Configure Linear triggers -Agent sessions cover explicit requests. To also start work automatically from issue and comment activity, add triggers: +Agent sessions cover explicit requests. To start work automatically from issue and comment activity too, add an automation with a **Linear** trigger for one of these events: **Issue created**, **Issue labeled**, **Issue state changed**, **Issue assigned**, or **Comment created**. [Automation filters](/factories/automation-filters/#edit-filters-on-an-automation) covers the steps. -1. In your factory, open **Automations**, then click **New** to create an automation or select an existing one. -2. Click **Add trigger** > **Linear**, then choose an event: **Issue created**, **Issue labeled**, **Issue state changed**, **Issue assigned**, or **Comment created**. -3. Select teams and labels to filter on. Click **More filters** to also filter by project, workflow state, assignee, mentioned user, or, for comment events, a specific issue. -4. Choose the agent that receives the work, add any instructions, and save. - -Filters control when a trigger fires. An empty filter matches everything in the connected workspace, and every filter you add must match. For example, a trigger can require that an issue belongs to one team, enters a selected workflow state, and carries a release label. - -If **Linear** shows **Not connected** in the **Add trigger** menu, selecting it opens the factory's settings so you can [connect Linear](#connect-linear-from-factory-settings) first. - -:::caution -Team selections and filters only route events. They don't reduce what the connection is allowed to access; the OAuth flow sets the workspace and teams Warp can reach. -::: +Every Linear trigger filters on teams and labels, and **More filters** adds project, workflow state, assignee, mentioned user, and — for comment events — a specific issue. A trigger can require, say, that an issue belongs to one team, enters a chosen workflow state, and carries a release label. ## Supported events and outputs @@ -92,13 +62,11 @@ One comment can match two routes: a comment that creates an agent session can al ## What the factory can do in Linear -In an agent session, the factory posts its plan, actions, and results as it works. It can also attach a GitHub pull request to the issue, update the issue's workflow state or delegate, link back to the run, and acknowledge comments it acts on. - -The factory's own Linear activity never triggers automations, so its updates can't start a loop of new runs. +In an agent session, the factory posts its plan, actions, and results as it works. It can also attach a GitHub pull request to the issue, update the issue's workflow state or delegate, link back to the run, and acknowledge comments it acts on. Its own Linear activity never triggers automations, so a factory can't set itself off in a loop. Only agent sessions require a linked Warp account. Issue and comment events from unlinked users still start work, but Warp may not record who requested it. -The Linear connection doesn't grant repository access or merge permissions. Code-host credentials control branches and pull requests, and human review and merge requirements still come from your factory workflow and repository settings. +Connecting Linear doesn't grant repository access. Branches and pull requests use the factory's code-host credentials, and the pull request still waits for a person to review and merge. ## Troubleshooting diff --git a/src/content/docs/factories/integrations/slack.mdx b/src/content/docs/factories/integrations/slack.mdx index 695695efe..052c1482e 100644 --- a/src/content/docs/factories/integrations/slack.mdx +++ b/src/content/docs/factories/integrations/slack.mdx @@ -5,36 +5,24 @@ description: >- direct messages, and automations, and get results back in the same thread. sidebar: label: "Slack" -topic: factories --- -Connect a factory to Slack so your team can send it work without leaving their conversations. Each factory gets its own dedicated Slack app: mention the app in a channel or send it a direct message, and the factory picks up the request with the conversation as context, then posts progress and results back into the same thread. You can also set up automations that start work from Slack events without a mention. If you're new to factories, see [how Warp Factories work](/factories/how-factories-work/) for what a factory is and how it runs work. +Connect a factory to Slack so your team can send it work without leaving their conversations. Mention the factory in a channel or send it a direct message, and it picks up the request with the conversation as context, then posts progress and results back into the same thread. -## Prerequisites and authorization +Each factory appears in Slack as its own app, carrying the factory's name and avatar. A channel can host several factories, and you choose which one to mention. -You need permission to update the factory and install apps in the target Slack workspace. Workspace policy can require administrator approval. +## Prerequisites -Installing the app grants the Slack permissions shown on the authorization screen. [Filters on automations](/factories/automation-filters/) only control which events start work; they don't limit what the app can access. For workspace-level installation and removal behavior, see the [Slack platform integration](/platform/integrations/slack/). - -### How the Slack connection works - -Warp uses Slack's managed apps model: Warp's main Slack app acts as the manager. The first time you connect a factory, you authorize the manager once for your workspace. That authorization lets Warp create and install Slack apps on your behalf, but nothing is created until you connect a factory. - -Each time you click **Add to Slack**, Warp creates that factory's dedicated app, installs it, and manages it from then on: the app's name, icon, and configuration stay in sync with the factory. The manager's permissions apply only to apps it created. Depending on your workspace's app-approval settings, a Slack administrator may need to approve the manager authorization once, and each factory's app before it installs. +* **Permission to install Slack apps** - You need it in the target workspace, and workspace policy can require an administrator to approve the app before it installs. +* **Permission to update the factory** - Connecting Slack changes the factory's configuration. ## Connect the factory -If you select Slack while creating a factory, Warp installs the factory's Slack app automatically. If the installation can't complete (for example, because your workspace requires administrator approval), click **Add to Slack** to finish connecting. - -1. In factory setup, go to **Add your Factory to your team**. -2. In the **Slack** row, click **Add to Slack**. -3. Choose the target workspace and approve access. If Slack requires administrator approval, finish installation after approval. -4. Return to factory setup and confirm that **Slack** shows **Connected**. -5. Invite the factory's app to each channel where it will receive requests. Private channels require an invitation. +Select Slack while creating a factory and Warp installs its app for you. If the install can't finish on its own — usually because your workspace requires administrator approval — click **Add to Slack** in factory setup to complete it. -To try it out, mention the app in a channel or send it a direct message. The app reacts with the eyes emoji (👀) to show it accepted the request. +Then invite the app to each channel it should listen in. Private channels always need an invitation. -The app is the factory's persona in Slack: it carries the factory's name and avatar, and it stays in sync when you rename the factory. If your team runs several factories, each one appears in Slack as its own app, so a channel can host more than one factory and you choose which one to mention. +To check that it worked, mention the app in one of those channels. It reacts with 👀 to show it picked up the request. ## Start and continue work from Slack @@ -51,18 +39,11 @@ A plain reply in a thread continues work only if that thread already has a facto To start work with a mention or direct message, your Slack account must be linked to an active member of the factory's Warp team. If it isn't, the app prompts you to connect an account instead of starting work. -Automations don't run as a requester: they run as the factory agent selected under **Agents**. An automation's conversation and author filters only decide which events start work; they don't change what the Slack app is authorized to access or the credentials the work runs with. +Work started by an automation runs as the factory agent you chose for it, not as whoever triggered it. ## Configure factory automations for Slack -Use a factory automation to start work from Slack activity automatically, without anyone mentioning the app. For example, an automation can act on every message posted in a triage channel or on a specific emoji reaction. - -1. In the factory's dashboard, open **Automations**, then create or edit an automation. -2. Under **Triggers**, click **Add trigger** > **Slack**, then choose an event. -3. Select the conversations and people that the event must match. Click **More filters** to add the event's available content filters. -4. Choose the receiving agent under **Agents**, add any **Additional instructions**, then click **Save**. - -Slack triggers support these events: +Use a factory automation to start work from Slack activity automatically, without anyone mentioning the app — on every message in a triage channel, say, or on a specific emoji reaction. Add a **Slack** trigger to an automation and pick one of these events; [automation filters](/factories/automation-filters/#edit-filters-on-an-automation) covers the steps. - **App mentioned** - Filter by joined conversations, authors, and keywords. - **Direct message received** - Filter by direct-message conversations, authors, and keywords. @@ -80,24 +61,18 @@ The Slack thread where work started is also where you follow it: the factory pos For an overview of the factory's work items, open the app's **Home** tab in Slack. It groups them by the same stages as the factory dashboard's [Activity view](/factories/factory-dashboard/#track-work-items-on-activity) (Triage, Planning, Building, Reviewing, Completed, and Cancelled), offers stage and date filters, and links each work item back to its Slack thread, factory run, issue, or pull request when available. -A factory can create issues, branches, and pull requests, but your repository's review and merge rules still apply. Work that starts in Slack doesn't bypass required human review. +Work that starts in Slack still ends at a pull request for a person to review — see [how Warp Factories work](/factories/how-factories-work/). ## Troubleshooting and reconnection -- **The app doesn't acknowledge a request** - Confirm the **Slack** row in factory setup shows **Connected**, check that you mentioned that factory's app, and invite the app to the channel. +- **The app doesn't acknowledge a request** - Confirm Slack is connected for that factory, that you mentioned the right factory's app, and that the app is in the channel. - **A channel is missing from an automation** - Invite the app to that channel, then reload the **Conversations** picker. - **Installation is pending** - Ask a Slack workspace administrator to approve the app, then finish the installation. - **Two runs start for one mention** - Remove or narrow overlapping app-mention and channel-message triggers. -Removing the app from your Slack workspace stops new requests from Slack for that factory; to reconnect it, return to factory setup and click **Add to Slack** again. To route work into the factory from other tools, see [Connect your factory](/factories/connect-your-factory/). - -To remove the factory's app entirely, delete the factory from its settings page in the web app. Deleting the factory removes its Slack app from your workspace and its Slack connection. - -You can also remove the app from the Slack side: +To disconnect Slack, either delete the factory — which removes its Slack app along with it — or [remove the app from your Slack workspace](https://slack.com/help/articles/360003125231-Remove-apps-and-custom-integrations-from-your-workspace), which stops new Slack requests reaching that factory. To reconnect afterward, click **Add to Slack** in factory setup again. -1. In Slack, go to **Apps** in the sidebar and search for the factory's name. -2. Select the app, open the **About** tab, then click **Configuration**. This opens your workspace's app configuration page in the browser. -3. Scroll to the bottom, select **Remove App**, and confirm the removal. +To route work into the factory from other tools, see [Connect your factory](/factories/connect-your-factory/). ## Privacy diff --git a/src/content/docs/factories/measure-and-improve.mdx b/src/content/docs/factories/measure-and-improve.mdx index 2f3c4f3e6..fe752d650 100644 --- a/src/content/docs/factories/measure-and-improve.mdx +++ b/src/content/docs/factories/measure-and-improve.mdx @@ -5,7 +5,6 @@ description: >- agent configurations, and turn failures into follow-up work. sidebar: label: "Measure and improve" -topic: factories --- Warp Factories tracks what your factory produces and how well it performs, so you can spot a problem, test a fix, and decide whether to keep it. diff --git a/src/content/docs/platform/harnesses/index.mdx b/src/content/docs/platform/harnesses/index.mdx index 5cf128f24..f5756f81c 100644 --- a/src/content/docs/platform/harnesses/index.mdx +++ b/src/content/docs/platform/harnesses/index.mdx @@ -25,6 +25,10 @@ Third-party harnesses inherit the same {VARS.WARP_AUTOMATION_PLATFORM} features * **Skills and Rules** — Saved [Skills](/agents/capabilities/skills/) and [Rules](/agents/capabilities/rules/) apply across harnesses. * **Observability** — Every run produces a transcript and shareable session in the [{VARS.DASHBOARD}](/platform/managing-cloud-agents/). +## Plan requirements + +Third-party harnesses require a Build plan or higher. On the Free plan, cloud agent runs use Warp Agent, and choosing another harness returns an upgrade prompt. See [Warp pricing](https://www.warp.dev/pricing) for what each plan includes. + ## Billing Claude Code and Codex each call their provider directly using credentials you supply, and the provider bills your account for inference. Warp meters [compute credits](/support-and-community/plans-and-billing/credits/#compute-credits) for the run's sandbox and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the orchestration layer.