diff --git a/.agents/templates/feature-doc.md b/.agents/templates/feature-doc.md index 11d1e8a23..b7a61ccaf 100644 --- a/.agents/templates/feature-doc.md +++ b/.agents/templates/feature-doc.md @@ -24,7 +24,8 @@ Remove this callout if not needed.] ## Key features [Bulleted list. Bold term + dash + description for each. -Focus on what each capability means for the user.] +Focus on what each capability means for the user. +If one capability is a genuine differentiator (e.g., an agent- or API-driven alternative to the default UI flow), give it real visual weight here or in its own callout near the top of the relevant section — don't bury it as a footnote after the primary flow is already documented.] * **Feature A** - What it does and why it matters to the user. * **Feature B** - What it does and why it matters to the user. @@ -38,6 +39,7 @@ IMPORTANT: Do NOT include step-by-step procedures in this section. Keep the conceptual and procedural sections clearly separated. State platform, plan, preview, or interactive-only limits next to the behavior they constrain. Do not invent internal tool names or implementation details the reader cannot act on. +Do not cite exact counts of tools, steps, or subcomponents (e.g., "ten tools") if they could change — describe the capability instead; a stale number is worse than no number. Do NOT embed full error messages here — put failures in Troubleshooting at the end.] [SCREENSHOTS: If this feature has a distinctive visual surface (statusline, tab bar, side pane, multi-control layout), place a screenshot immediately after the paragraph that introduces that surface. Use descriptive alt text. Skip screenshots for purely textual CLI behavior.] diff --git a/AGENTS.md b/AGENTS.md index b22336adb..86dfd21ba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,6 +13,7 @@ This guide establishes standards for writing Warp documentation. It covers voice - **Direct and action-oriented**: Lead with what users can accomplish, not just what features exist - **User-focused**: Use second person ("you can", "allows you to") rather than passive voice - **Confident without jargon**: Explain technical concepts clearly without oversimplifying +- **Avoid copy that reads as AI-generated**: Watch for over-explained cause-and-effect, excessive hedging, or the same rhetorical pattern repeated across sections. Read a paragraph aloud — if it doesn't sound like something a person would say to a colleague, rewrite it plainly. ### Language guidelines - Use consistent terminology throughout (see [Terminology standards](#terminology-standards) and the full glossary in `.agents/references/terminology.md`) @@ -411,8 +412,13 @@ These rules apply regardless of content type: - **Provide inline context for first references**: Assume the reader arrived directly at this page, not from a parent page. When a prerequisite, concept, or tool is mentioned for the first time, include: what the thing is (1 short clause), where to get or create it, and a link to the full reference. - ✅ "**A Warp API key** - Authenticate API requests with a key from **Settings** > **Platform** in the Warp app. See the API Keys reference for details." - ❌ "**An API key** - Create one in **Settings** > **Platform**." (what kind of key? Settings where?) -- **Include practical examples**: Show real-world scenarios, not just toy examples. Concrete examples help the reader understand when and why to use a feature. +- **Include practical examples**: Show real-world scenarios, not just toy examples. Concrete examples help the reader understand when and why to use a feature. For enterprise or infrastructure-heavy features, prefer a complete example (a full config file, a linked sample repository) over a fragment — abstract features are hardest to trust without something concrete to point at. - **Cross-reference related pages**: Link to related features, next steps, and deeper references so the reader can continue learning. +- **Sequence basics before jargon**: Explain what something is in plain language before introducing internal-sounding framing, deep lifecycle terminology, or advanced configuration. A reader who doesn't know the concept yet should never hit unexplained jargon in the first few paragraphs. Save advanced or self-referential concepts (e.g., a system that improves itself) for after the reader understands the basic flow. +- **Avoid appendix-style content**: Don't add a bullet list or table whose only job is to restate content already covered elsewhere on the page, such as an exhaustive index of tabs or settings that duplicates the dedicated sections below it. Weave supplementary details into the section they relate to instead of bolting them onto the end under a generic heading like "Good to know." +- **Don't over-specify counts or internals that will drift**: Describe a capability rather than naming an exact count of tools, steps, or subcomponents behind it (e.g., "a small set of tools" instead of "ten tools"). Precise counts go stale the moment the implementation changes, and a stale number is worse than no number. +- **Feature real differentiators structurally**: If a capability is a genuine advantage over the default path (an agent- or API-driven alternative to a UI flow, for example), give it real visual weight — a clear callout near the top of the relevant section, not a footnote after the primary steps are already done. Where something sits on the page communicates how important it is. +- **Verify claims against the live product, not just prior drafts**: Terminology, UI labels, and calculated values drift between rounds of review. Confirm names, labels, and metric definitions against the actual app, API, or codebase before publishing — especially for pages describing metrics or anything computed. ### Conceptual @@ -461,6 +467,7 @@ These rules apply regardless of content type: - Include expected outcomes after key steps so the reader can confirm they're on track. - Test all instructions for accuracy. - Provide troubleshooting for common failure points. +- **Explain the default before the override.** When documenting configurable infrastructure or advanced settings, state the default behavior and the common case first, then cover manual overrides. Don't lead with the full matrix of options before establishing what "just works" out of the box. **Existing examples**: `reference/cli/api-keys.mdx`, `platform/integrations/slack.mdx` diff --git a/src/assets/factories/quickstart-connect-organization.png b/src/assets/factories/quickstart-connect-organization.png new file mode 100644 index 000000000..734ffc0ed Binary files /dev/null and b/src/assets/factories/quickstart-connect-organization.png differ diff --git a/src/assets/factories/quickstart-name-factory.png b/src/assets/factories/quickstart-name-factory.png new file mode 100644 index 000000000..39df71d0e Binary files /dev/null and b/src/assets/factories/quickstart-name-factory.png differ diff --git a/src/assets/factories/quickstart-open-setup-wizard.png b/src/assets/factories/quickstart-open-setup-wizard.png new file mode 100644 index 000000000..134f266a4 Binary files /dev/null and b/src/assets/factories/quickstart-open-setup-wizard.png differ diff --git a/src/assets/factories/quickstart-pick-agents.png b/src/assets/factories/quickstart-pick-agents.png new file mode 100644 index 000000000..50bd325aa Binary files /dev/null and b/src/assets/factories/quickstart-pick-agents.png differ diff --git a/src/assets/factories/quickstart-select-repos.png b/src/assets/factories/quickstart-select-repos.png new file mode 100644 index 000000000..95d0f8c68 Binary files /dev/null and b/src/assets/factories/quickstart-select-repos.png differ diff --git a/src/content/docs/enterprise/team-management/admin-panel.mdx b/src/content/docs/enterprise/team-management/admin-panel.mdx index 0e250dec8..896571486 100644 --- a/src/content/docs/enterprise/team-management/admin-panel.mdx +++ b/src/content/docs/enterprise/team-management/admin-panel.mdx @@ -269,12 +269,12 @@ Controls how screenshots and video recordings captured with [Computer Use](/agen **Enabled GitHub Orgs** -The **Enabled GitHub Orgs** setting associates your Warp team with one or more GitHub App installations. That association does two things: it lets cloud agents initiated with an [agent API key](/reference/cli/api-keys/) clone repositories and open pull requests using the Oz by Warp GitHub App, and it tells Warp which team owns runs started from the [GitHub integration](/platform/integrations/github/) when someone mentions `@warp-agent` in those repositories. +The **Enabled GitHub Orgs** setting associates your Warp team with one or more GitHub App installations. That association does two things: it lets cloud agents initiated with an [agent API key](/reference/cli/api-keys/) clone repositories and open pull requests using the Warp Factories GitHub App, and it tells Warp which team owns runs started from the [GitHub integration](/platform/integrations/github/) when someone mentions `@warp-agent` in those repositories. To configure: 1. Navigate to the **Platform** section of the Admin Panel. -2. Under **Enabled GitHub Orgs**, review the list of GitHub organizations where the Oz by Warp GitHub App is installed. +2. Under **Enabled GitHub Orgs**, review the list of GitHub organizations where the Warp Factories GitHub App is installed. 3. Select which organizations your team should have access to.
@@ -282,7 +282,7 @@ To configure:
Enabled GitHub Orgs setting in the Admin Panel.
-The organizations and repository access shown here reflect the Oz by Warp GitHub App installation scope, which is configured in [GitHub settings](https://github.com/settings/installations). To change which repositories the app can access, edit the installation directly in GitHub. +The organizations and repository access shown here reflect the Warp Factories GitHub App installation scope, which is configured in [GitHub settings](https://github.com/settings/installations). To change which repositories the app can access, edit the installation directly in GitHub. :::note This setting controls which GitHub App installation agent API key runs authenticate with, and which GitHub organizations can start [GitHub integration](/platform/integrations/github/) runs for this team. Runs from an `@warp-agent` mention also authenticate with the installation's GitHub App token, so their repository access comes from the app installation rather than the person who wrote the mention. Runs triggered from a personal API key, Slack, Linear, or the Warp app continue to use that user's own GitHub authorization. For more details, see [Team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization). diff --git a/src/content/docs/factories/connect-your-factory.mdx b/src/content/docs/factories/connect-your-factory.mdx index 38178a948..f7cd67e78 100644 --- a/src/content/docs/factories/connect-your-factory.mdx +++ b/src/content/docs/factories/connect-your-factory.mdx @@ -11,7 +11,7 @@ Connect your factory to the tools where your team already discusses, tracks, and ## Choose a source -Pick the sources that match where work starts for your team. You can connect more than one. +Pick the sources that match where work starts for your team. You can connect more than one, though a factory can use Linear or 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/). | Source | Best for | Where follow-ups continue | | --- | --- | --- | @@ -27,7 +27,7 @@ Pick the sources that match where work starts for your team. You can connect mor 1. Pick the factory you want to connect. If you don't have one yet, follow the [Warp Factories quickstart](/factories/quickstart/). 2. Connect the source: install the provider integration, set up the [Factory MCP](/factories/factory-mcp/), or create a schedule. Each integration guide below walks through authorization; grant only the access the factory needs. -3. Tell the factory how to respond. Provider connections come with default automations that decide which events start work and which agent handles them; review their [filters](/factories/automation-filters/) and run settings. Schedules and direct runs skip this step. +3. Tell the factory how to respond. Provider connections come with default automations that decide which events start work and which agent handles them. Review their [filters](/factories/automation-filters/) and run settings. Filters route work, not access: what a running agent can reach depends on its own configuration, not the filters that started it. Schedules and direct runs skip this step. 4. Send a test request, such as mentioning the factory in Slack or assigning it an issue, and confirm it picks up the work and replies at the source. ## How work reaches your factory @@ -44,7 +44,7 @@ flowchart LR An event from a connected tool starts the automation whose filters match it, such as a specific repository, channel, or label. Schedules start their automation on a timer, and direct requests go straight to the factory. -Every request then lands with the foreman agent, the factory's orchestrator. The foreman turns the request into a work item, determines which stage the work needs next, and dispatches a specialized agent for each stage: triage to scope the request, spec when the design needs agreement, implementation to write the code, and review to check it. Between stages it relays questions and progress back to the source, and it pauses wherever a decision belongs to a human, such as approving a spec or merging a pull request. See [how Warp Factories work](/factories/how-factories-work/) for the full lifecycle. +Every request then lands with the foreman agent, the factory's orchestrator. The foreman turns the request into a work item, determines which stage the work needs next, and dispatches a specialized agent for each stage: triage to scope the request, spec when the design needs agreement, implementation to write the code, and review to check it. Between stages it relays questions and progress back to the source, and it pauses wherever a decision belongs to a human, such as approving a spec or [merging a pull request](/factories/how-factories-work/#where-your-team-stays-in-charge). A reply in the same thread, issue, or pull request adds to that work item instead of starting a new one, and repeated event deliveries from a provider don't create duplicates. See [how Warp Factories work](/factories/how-factories-work/) for the full lifecycle. ## Review the default automations @@ -79,11 +79,4 @@ Not every task starts in an external tool: See the [triggers overview](/platform/triggers/) for how schedules and other triggers work across the platform. -## Good to know - -* **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** - 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 [where your team stays in charge](/factories/how-factories-work/#where-your-team-stays-in-charge). - 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 2a9a00f4e..ea6b44645 100644 --- a/src/content/docs/factories/factory-agents.mdx +++ b/src/content/docs/factories/factory-agents.mdx @@ -7,6 +7,10 @@ sidebar: label: "Factory agents" --- +:::note +Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. +::: + Every factory has a **foreman**, the one agent you talk to from whichever tool a request starts in. Around it sit four default agents, one for each part of the software development lifecycle: triage scopes the request, spec writes the plan, implement writes the code, and review checks it. Together they take a work item from the moment it reaches your factory to a pull request ready for a person to review. ## The default agents diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx index bb5aef589..0a0b9f339 100644 --- a/src/content/docs/factories/factory-as-code.mdx +++ b/src/content/docs/factories/factory-as-code.mdx @@ -382,6 +382,19 @@ platform: dockerImage: ubuntu:22.04 ``` +### Routing to a self-hosted worker + +To route this factory's work to a [managed self-hosted worker](/factories/infrastructure-and-security/#choose-an-execution-host) instead of Warp-hosted compute, set `workerHost` on `agentDefaults` (or override it per agent or automation) to the worker's ID: + +```yaml title="factory.yaml" +agentDefaults: + model: auto + runner: linux-build + workerHost: SELF_HOSTED_WORKER_ID +``` + +Pair `workerHost` with a runner whose `platform` matches the worker's operating system and architecture. See [choose an execution host](/factories/infrastructure-and-security/#choose-an-execution-host) for the full setup, including how to deploy and connect the worker. + ## Pull request checks for GitHub-backed factories When your definition lives in GitHub, Warp validates every change before it takes effect: diff --git a/src/content/docs/factories/factory-dashboard.mdx b/src/content/docs/factories/factory-dashboard.mdx index 0579e7d5d..92be3b9c9 100644 --- a/src/content/docs/factories/factory-dashboard.mdx +++ b/src/content/docs/factories/factory-dashboard.mdx @@ -13,24 +13,21 @@ The factory dashboard is the web app for operating a single factory. Use it to t "Factory dashboard" names the whole surface. **Dashboard**, in bold, is one page inside it: the metrics page you land on when you open a factory. ::: -## Pages at a glance +## Getting oriented -Select a factory in the sidebar to open its pages. **Runs**, **MCPs and apps**, **Secrets**, and **Integrations** sit above the factory list and cover your whole team, not a single factory. +Select a factory in the sidebar to open its pages. **Runs**, **MCPs and apps**, **Secrets**, and **Integrations** sit above the factory list and cover your whole team, not a single factory; everything else on this page is scoped to the factory you select. -| Page | What it shows | What you do there | -| --- | --- | --- | -| **Dashboard** | The factory's metrics: autonomy, PR cycle time, cost, and run volume | Compare periods and find work worth investigating | -| **Activity** | Work items grouped by stage | Search, filter, open, and stop work items | -| **Agents** | The factory's agents | Create and edit agents | -| **Automations** | Triggers that start runs | Create, edit, and delete automations | -| **Runs** | The factory's individual agent runs | Start, stop, and score runs | -| **Scorers** | Scorer definitions and results | Define rubrics and review classifications | -| **Self-improvement** | Pull requests filed to fix Scorer-detected failures | Review fix PRs and open the runs behind them | -| **Benchmarks** | Benchmark suites and their runs | Compare harness, model, and runner configurations | -| **Factory definition** | The factory's definition files | Browse and edit a Warp-managed definition | -| **Settings** | Configuration the factory owns | Change identity, repos, runners, and the integrations the factory can access | +A factory opens on its **Dashboard** page, covered next. **Factory definition** appears only on Warp-managed factories, since a factory whose definition lives in your own repository is edited there instead. -A factory opens on its **Dashboard** page. **Factory definition** appears only on Warp-managed factories, since a factory whose definition lives in your own repository is edited there instead. +## Read metrics on the Dashboard page + +**Dashboard** is the factory's landing page. It summarizes the factory over a date range you choose: + +* **Autonomy** - The share of the factory's merged PRs that needed no human input beyond an approving review and the merge itself. A PR counts as autonomous only if no person added commits, requested changes, or otherwise edited it before merge. +* **PR cycle time** - The median time the factory's merged PRs took from run kickoff through PR, first review, and merge, with a median for each stage. +* **Cost per PR** - The median cost of PRs opened in the range. Treat it as a lower-bound estimate: it can miss some run usage and does not match billing. See [Measure and improve a factory](/factories/measure-and-improve/) for its limitations. + +The page also charts opened versus merged PRs and a breakdown of runs, and the **Cost per PR** card expands to list the most expensive PRs in the range. When Scorers are set up, Scorer cards summarize recent classification results. ## Track work items on Activity @@ -54,16 +51,6 @@ Click **New** on a factory's **Runs** page to send a prompt to the factory's for Run pages don't include a chat input, but you can still steer a run: **View session** opens its [shared agent session](/platform/viewing-cloud-agent-runs/), where you follow the agent in real time and send follow-up instructions while the run's sandbox is active. After it shuts down, the same button opens the conversation transcript. ::: -## Read metrics on the Dashboard page - -**Dashboard** is the factory's landing page. It summarizes the factory over a date range you choose: - -* **Autonomy** - The share of the factory's merged PRs that needed no human input beyond an approving review and the merge itself. -* **PR cycle time** - The median time the factory's merged PRs took from run kickoff through PR, first review, and merge, with a median for each stage. -* **Cost per PR** - The median cost of PRs opened in the range. Treat it as a lower-bound estimate: it can miss some run usage and does not match billing. See [Measure and improve a factory](/factories/measure-and-improve/) for its limitations. - -The page also charts opened versus merged PRs and a breakdown of runs, and the **Cost per PR** card expands to list the most expensive PRs in the range. When Scorers are set up, Scorer cards summarize recent classification results. - ## Manage agents and automations **Agents** lists the factory's agents. Create agents and edit their instructions, model or harness, runner, host, secrets, and MCP servers. **Automations** defines the triggers that start runs: a schedule (including custom cron expressions) or a GitHub, Linear, Slack, or Jira event. diff --git a/src/content/docs/factories/how-factories-work.mdx b/src/content/docs/factories/how-factories-work.mdx index 94c03c724..b59ebf041 100644 --- a/src/content/docs/factories/how-factories-work.mdx +++ b/src/content/docs/factories/how-factories-work.mdx @@ -7,6 +7,10 @@ sidebar: label: "How Factories work" --- +:::note +Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. +::: + A factory is a team of cloud agents that ships software the way your team does: a request comes in, moves through the stages it needs, and comes back as a pull request for a person to review. You talk to one agent — the **foreman** — from whichever tool a request starts in, and it dispatches the factory's other agents, each owning one part of the software development lifecycle. A **work item** is one unit of that engineering work, such as an issue, support request, pull request, or Factory MCP task. It keeps its identity from intake to handoff, however many agents contribute to it along the way. diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index a7de7b785..61b056c7f 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -8,12 +8,12 @@ sidebar: --- import { VARS } from '@data/vars'; -Warp Factories lets engineering teams define and operate **software factories**: cloud workflows where specialized agents move engineering work from intake to a reviewed pull request. The factory does the repetitive work; your team stays in the loop at the points that matter, approving specs when needed and merging every pull request. - :::note Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. ::: +Warp Factories lets engineering teams define and operate **software factories**: cloud workflows where specialized agents move engineering work from intake to a reviewed pull request. The factory does the repetitive work; your team stays in the loop at the points that matter, approving specs when needed and merging every pull request. + ## What is a software factory? A software factory automates the software development lifecycle. It takes a **work item**, such as an issue, ticket, or triggered task, and moves it through specialized agents that triage it, write a specification when one is needed, implement the change, and review the result. diff --git a/src/content/docs/factories/integrations/github.mdx b/src/content/docs/factories/integrations/github.mdx index e94961723..8c36d78ba 100644 --- a/src/content/docs/factories/integrations/github.mdx +++ b/src/content/docs/factories/integrations/github.mdx @@ -17,7 +17,7 @@ When you connect a factory to GitHub, repository activity starts work in your fa ## Connect GitHub to a factory -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**. +1. In the {VARS.FACTORY_WEB_APP}, 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. A new factory arrives with two automations already switched on, so it responds to GitHub activity right away: diff --git a/src/content/docs/factories/integrations/gitlab.mdx b/src/content/docs/factories/integrations/gitlab.mdx index 6a98e194a..9f6029cf7 100644 --- a/src/content/docs/factories/integrations/gitlab.mdx +++ b/src/content/docs/factories/integrations/gitlab.mdx @@ -1,7 +1,7 @@ --- -title: Connect GitLab to your factory +title: Connect a factory to GitLab description: >- - Connect GitLab to your factory so merge request events and bot mentions start + Connect a factory to GitLab so merge request events and bot mentions start factory work and results post back as comments and merge requests. sidebar: label: "GitLab" @@ -14,22 +14,27 @@ When you connect a factory to GitLab, project activity starts work in your facto * **GitLab.com** - The integration supports GitLab.com only, not self-managed GitLab instances. To use a self-managed instance with standalone cloud agents instead, see the [GitLab access token setup](/platform/integrations/gitlab/). * **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 paid GitLab plan (Premium or Ultimate)** - Warp provisions [service accounts](https://docs.gitlab.com/user/profile/service_accounts/) in your group and installs a [group webhook](https://docs.gitlab.com/user/project/integrations/webhooks/#group-webhooks). Group webhooks are available only on Premium and Ultimate plans. On the Free tier, GitLab can't deliver the webhook events that trigger runs: factory credentials still work, but nothing starts work from GitLab. +* **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. -## Your factory's GitLab identity +## Service accounts and access -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. +Warp manages GitLab access through service accounts it creates in your connected group rather than a marketplace app: -## Connect GitLab to a factory - -When you create a factory, choose **I want to use repos from GitLab** as the code host, then: +* **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. -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. +The connected group's webhook delivers merge request and comment events to Warp, and matching automations turn them into factory work. -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/). +## Connect GitLab to a factory -To start work from merge request events as well, add a **Merge request** trigger to an automation; [automation filters](/factories/automation-filters/#edit-filters-on-an-automation) covers the steps. +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. ## Supported triggers @@ -55,7 +60,7 @@ To start work from merge request events as well, add a **Merge request** trigger | **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 | -The **Bot mentioned** trigger always listens for the factory's own bot. You can't point it at a different username. +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. ## Mention the factory @@ -77,16 +82,16 @@ The factory acts on GitLab as its bot account: * **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**](/factories/factory-dashboard/#change-factory-settings). * **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, and your project's protection and approval rules apply to everything the bot does. +The factory never merges or approves a merge request; those decisions stay with your team. Branch 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.** 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. +* **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. * **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 your workspace retires every factory bot along with it. +Disconnecting GitLab from the workspace retires the manager and every factory bot it provisioned. ## Definitions as code @@ -107,9 +112,7 @@ triggers: Triage newly opened merge requests and post an initial review. ``` -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). +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. {/* OPEN QUESTION for tech review (PR #549): confirm GitLab is actually supported as a definition host today. main@79f77e55 states GitLab is "not yet available as a definition host" -- this contradicts the claim below. Verify before merging. */}Factory definitions hosted in GitLab repositories sync the same way GitHub-hosted ones do. ## Troubleshooting @@ -123,7 +126,7 @@ Confirm an enabled automation includes the **Merge request** trigger and check i ### Nothing starts work even though GitLab is connected -Your GitLab plan may not include [group webhooks](https://docs.gitlab.com/user/project/integrations/webhooks/#group-webhooks), which are a GitLab Premium and Ultimate feature (see [Prerequisites](#prerequisites)). Upgrade your GitLab plan to let GitLab trigger runs. +Your GitLab plan may not include group webhooks (see [Prerequisites](#prerequisites)). Upgrade your GitLab plan to let GitLab trigger runs. ### The bot can't push a branch or open a merge request @@ -133,4 +136,4 @@ Confirm the target project is one of the factory's selected projects and the ope Only top-level groups you own appear, and a group already connected to another Warp workspace can't be connected again. If you don't own the group, ask an owner to establish the connection in Warp. -For the other ways to route work into a factory, see [Connect your factory](/factories/connect-your-factory/). +For the other ways to route work into a factory, see [connecting your factory](/factories/connect-your-factory/). diff --git a/src/content/docs/factories/measure-and-improve.mdx b/src/content/docs/factories/measure-and-improve.mdx index 357b31ec0..cd9408a94 100644 --- a/src/content/docs/factories/measure-and-improve.mdx +++ b/src/content/docs/factories/measure-and-improve.mdx @@ -25,7 +25,7 @@ The **Dashboard** page shows activity, cost, autonomy, and evaluation results: | **Total runs** | All agent runs, with breakdowns by agent type, status, source, model, and more. | | **PRs opened** | Pull requests created from factory work. | | **PRs merged** | Pull requests that merged. | -| **Autonomy** | The share of the factory's merged PRs that needed no human input beyond an approving review and the merge itself. | +| **Autonomy** | The share of the factory's merged PRs that needed no human input beyond an approving review and the merge itself. A PR counts as autonomous only if no person added commits, requested changes, or otherwise edited it before merge. | | **PR cycle time** | The median time the factory's merged PRs took from run kickoff through PR, first review, and merge, with a median for each stage. | | **Cost per PR** | An estimate of credits spent per pull request. | | **Most expensive PRs** | The highest-cost pull requests. | diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index 9220124fa..4ec95f93c 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -8,24 +8,28 @@ sidebar: --- import { VARS } from '@data/vars'; -A factory is a team of cloud agents that turns your team's requests into pull requests. You talk to one agent, the **foreman**, from whichever tool the request starts in, such as Slack, an issue tracker, or a code host. The foreman dispatches the factory's other agents, each owning one part of the software development lifecycle. People stay in the loop at the points that matter: approving specs when needed and merging pull requests. +:::note +Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. +::: + +A factory is a group of cloud agents that turns incoming requests into pull requests. You talk to one agent, the **foreman**. It picks up the request from wherever it starts, such as Slack, an issue tracker, or a code host, then dispatches the factory's other agents, each owning one part of the software development lifecycle. People stay in the loop at the points that matter: approving specs when needed and merging pull requests. In this quickstart, you will create a factory and take one small work item from prompt to pull request in about 10 minutes. ## What you'll decide -Warp walks you through factory setup; your job is to decide four things: +Warp walks you through factory setup. Along the way, you decide: -* **Which code the factory works on** - The code host and the set of repositories. -* **What it's called** - The factory's name, and the alias your team @-mentions to reach it. -* **Which agents it runs** - The agents the foreman can dispatch. -* **Where work comes from** - Optionally, a chat tool and an issue tracker. +* The code host and repositories the factory works on. +* The factory's name and its foreman's @-mention alias. +* Which default agents the foreman can dispatch. +* Whether to connect a chat tool and an issue tracker, or add them later. -Every one of these is editable afterward, so pick something reasonable and keep moving. +You can change any of these after setup, so a best guess is fine for now. ## Prerequisites -* **Warp Factories access** - Warp Factories is in Early Access. [Request access](https://www.warp.dev/factories/request-access) if your team doesn't have it yet. +* **Warp Factories access** - Warp Factories is in Early Access. [Request access](https://www.warp.dev/factories/request-access) for your team. * **A Warp team with credits** - A factory belongs to a [Warp team](/knowledge-and-collaboration/teams/). Factory agents consume the team's [credits](/support-and-community/plans-and-billing/platform-credits/). * **Repository access** - You authorize a code host during setup and choose which repositories the factory can reach. If your organization restricts app installations, ask an owner to approve the connection. See the [GitHub](/factories/integrations/github/) and [GitLab](/factories/integrations/gitlab/) integration guides. @@ -33,40 +37,51 @@ Every one of these is editable afterward, so pick something reasonable and keep _~5 minutes_ -Sign in to the {VARS.FACTORY_WEB_APP} at platform.warp.dev and start a new factory. Setup asks you for the following. - -You can also skip the wizard: ask an agent connected to the [Factory MCP](/factories/factory-mcp/) to create the factory with its `create_factory` tool, giving it the team, the repositories, and a name. That covers the first two steps below; choose the agents and connect your tools afterward in the factory's dashboard. +:::note +Already using an agent connected to [Factory MCP](/factories/factory-mcp/)? Ask it to run `create_factory` with the team, repositories, and factory name to create the factory directly, skipping the wizard below. Choose agents and connect your tools afterward in the factory's dashboard. +::: -### Connect a code host and choose repositories +Otherwise, Warp walks you through a setup wizard: -Authorize GitHub or GitLab, then select the repositories the factory works in. +1. Sign in to the {VARS.FACTORY_WEB_APP}. Next to **Factories**, click **+**. -Start with one or two. Every agent in the factory shares this repo set, so a focused set keeps their context tight, and you can add more later. +
+ ![The Factories section of the sidebar, with the + button used to start a new factory highlighted.](../../../assets/factories/quickstart-open-setup-wizard.png) +
Click + next to Factories to open the setup wizard.
+
-### Name your factory +2. Click **I want to use repos from GitHub** or **I want to use repos from GitLab**, then choose the organization or group you want to connect. -Name the factory, and give it an [alias](/factories/factory-as-code/#alias): the handle your team @-mentions to reach it from connected tools like Slack and Linear, so keep it short and recognizable. In setup, the alias is the **Foreman name** field, and Warp derives it from the factory name if you don't set one. +
+ ![The Connect a GitHub organization screen, with an already-connected organization shown as an option.](../../../assets/factories/quickstart-connect-organization.png) +
Choose the organization or group whose repositories the factory will use. GitLab shows an equivalent screen for groups.
+
-### Design your factory +3. On **Select your repos**, search for and select the repositories the factory works in, then click **Add repos**. Start with one or two. Every agent in the factory shares this repo set, so a focused set keeps their context tight, and you can add more later. -Every factory has a **foreman**: the one agent you talk to, no matter where the request starts. Around it, the factory is composed of four default agents, one for each part of the software development lifecycle, and this step is where you choose which of them your factory runs: +
+ ![The Select your repos screen, searching for repositories by name.](../../../assets/factories/quickstart-select-repos.png) +
Search for and select the repositories the factory works in.
+
-| Agent | What it does | -| --- | --- | -| **Triage** | Accepts work from issue trackers and establishes scope | -| **Spec** | Iterates with your team to produce a spec | -| **Code** | Implements the change and opens the pull request | -| **Review** | Inspects the result and reports findings | +4. Name the factory. Warp derives a matching [**Foreman name**](/factories/factory-as-code/#alias) from it, the handle your team @-mentions to reach the factory from connected tools like Slack and Linear. Keep it short and recognizable, or set your own. -All four start enabled and a factory needs at least one, so this step is about turning off what you don't want yet. Leave **Code** on so this quickstart can end in a pull request. You can add your own agents and automations later. +
+ ![The Give your factory some personality screen, with Factory name and Foreman name fields filled in.](../../../assets/factories/quickstart-name-factory.png) +
Name the factory and, optionally, add a description and avatar.
+
-See [factory agents](/factories/factory-agents/) for what each agent does in depth; the **Code** toggle is that page's Implement agent. +5. Optionally, connect a chat tool so teammates can hand work to the factory from Slack, or skip it and add it later from [connect your factory](/factories/connect-your-factory/). +6. Toggle the subagents the foreman can dispatch: **Triage**, **Spec**, **Code**, and **Review**. All four start enabled, and at least one is required. Leave **Code** on so this quickstart can end in a pull request. See [factory agents](/factories/factory-agents/) for what each does. -### Optionally connect Slack and an issue tracker +
+ ![The Pick your factory agents screen, with the Foreman and all four default subagents shown as enabled.](../../../assets/factories/quickstart-pick-agents.png) +
Toggle which default agents the foreman can dispatch.
+
-Setup offers to connect a chat tool and an issue tracker, so teammates can hand work to the factory from where they already work. Skip both if you want to finish quickly; [connect your factory](/factories/connect-your-factory/) covers adding them later. +7. Optionally, connect an issue tracker so teammates can hand work to the factory from Linear or Jira, or skip it and add one later from [connect your factory](/factories/connect-your-factory/). -Warp then creates the factory and opens its [dashboard](/factories/factory-dashboard/). +Warp creates the factory and opens its [dashboard](/factories/factory-dashboard/). ## Send your first work item diff --git a/src/content/docs/platform/agents.mdx b/src/content/docs/platform/agents.mdx index e8e9c21fe..f0bd0cf38 100644 --- a/src/content/docs/platform/agents.mdx +++ b/src/content/docs/platform/agents.mdx @@ -58,7 +58,7 @@ When a team is over its plan limit (for example, after downgrading), the extra a ## Where cloud agents appear in the product * **Agents page** - The Agents page in the [{VARS.WEB_APP}](/platform/oz-web-app/) is where teams view, create, edit, and delete cloud agents. -* **Agent picker** - Forms that start a new run or schedule include an **Agent** dropdown. **Quick run** is the default: runs execute as the calling user, and pull requests are authored by that person. Picking a cloud agent runs as that agent instead, so with [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) configured, pull requests are authored by the **Oz by Warp** GitHub App. Choose a cloud agent for any schedule that opens pull requests. See [Run identity and pull request authorship](/platform/triggers/scheduled-agents-quickstart/#run-identity-and-pull-request-authorship). +* **Agent picker** - Forms that start a new run or schedule include an **Agent** dropdown. **Quick run** is the default: runs execute as the calling user, and pull requests are authored by that person. Picking a cloud agent runs as that agent instead, so with [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) configured, pull requests are authored by the **Warp Factories** GitHub App. Choose a cloud agent for any schedule that opens pull requests. See [Run identity and pull request authorship](/platform/triggers/scheduled-agents-quickstart/#run-identity-and-pull-request-authorship). * **Run filters and detail** - The Runs view lets you filter by cloud agent, and individual run detail pages show which agent executed the run. * **Admin Panel** - Billing usage in the [Admin Panel](/knowledge-and-collaboration/admin-panel/) attributes credits consumed by cloud agent runs to the team rather than to a person. diff --git a/src/content/docs/platform/integrations/github-actions.mdx b/src/content/docs/platform/integrations/github-actions.mdx index ac85fbfb5..f519e47ad 100644 --- a/src/content/docs/platform/integrations/github-actions.mdx +++ b/src/content/docs/platform/integrations/github-actions.mdx @@ -14,7 +14,7 @@ Run agents directly in your GitHub Actions workflows using `oz-agent-action`. Th ::: :::note -GitHub Actions is different from the [GitHub integration](/platform/integrations/github/). GitHub Actions runs agents inside workflows you define in your repository, and you control the trigger, permissions, and prompt in YAML. The GitHub integration starts agents when someone mentions `@warp-agent` on an issue, pull request, or review comment, using the Oz by Warp GitHub App with no workflow file. +GitHub Actions is different from the [GitHub integration](/platform/integrations/github/). GitHub Actions runs agents inside workflows you define in your repository, and you control the trigger, permissions, and prompt in YAML. The GitHub integration starts agents when someone mentions `@warp-agent` on an issue, pull request, or review comment, using the Warp Factories GitHub App with no workflow file. ::: If you're comparing GitHub Actions with schedules, Slack, Linear, the GitHub integration, the {VARS.WARP_AGENT_CLI}, or API-triggered runs, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). @@ -113,7 +113,7 @@ The `oz-agent-action` supports several automation patterns commonly used in CI. * **Use case**: Add "@oz-agent fix this typo" or similar comments to a PR or Issue. :::note -The [GitHub integration](/platform/integrations/github/) responds to `@warp-agent` mentions without a workflow file. Use this Actions pattern when you want the run to happen inside your CI pipeline with workflow-scoped permissions; use the GitHub integration when you want mention-triggered runs on every repository the Oz by Warp GitHub App can access. +The [GitHub integration](/platform/integrations/github/) responds to `@warp-agent` mentions without a workflow file. Use this Actions pattern when you want the run to happen inside your CI pipeline with workflow-scoped permissions; use the GitHub integration when you want mention-triggered runs on every repository the Warp Factories GitHub App can access. ::: What it does: diff --git a/src/content/docs/platform/integrations/github.mdx b/src/content/docs/platform/integrations/github.mdx index 05c6050b4..6c0231acf 100644 --- a/src/content/docs/platform/integrations/github.mdx +++ b/src/content/docs/platform/integrations/github.mdx @@ -10,7 +10,7 @@ import { VARS } from '@data/vars'; The GitHub integration lets your team start cloud agents from GitHub itself. Mention **@warp-agent** in an issue comment, a pull request review comment, or the body of a new pull request, and Warp starts a cloud agent that reads the surrounding context, works the task in your codebase, and posts its progress and results back into the same thread. -The integration is powered by the **Oz by Warp** GitHub App. Once a team admin installs the app and enables the GitHub organization, every teammate who has connected their GitHub account can trigger agents from GitHub without leaving a review or an issue. +The integration is powered by the **Warp Factories** GitHub App. Once a team admin installs the app and enables the GitHub organization, every teammate who has connected their GitHub account can trigger agents from GitHub without leaving a review or an issue. :::note This page covers the native GitHub App integration. It is distinct from two other GitHub surfaces: @@ -31,7 +31,7 @@ This page covers the native GitHub App integration. It is distinct from two othe ## How it works -When you mention `@warp-agent`, GitHub sends the event to Warp through the Oz by Warp GitHub App installation. Warp then: +When you mention `@warp-agent`, GitHub sends the event to Warp through the Warp Factories GitHub App installation. Warp then: 1. Confirms the comment or pull request body contains the `@warp-agent` mention and that the author is a person rather than a bot. 2. Maps the GitHub App installation to a Warp team using the organizations enabled in the Admin Panel. @@ -66,7 +66,7 @@ When a run for that thread is already in flight, a new mention is delivered to t * **Team membership** - The GitHub integration requires a [Warp team](/knowledge-and-collaboration/teams/). Configuration is team-scoped, and runs are owned by the team associated with the GitHub App installation. * **Plan and credits** - Your team must have cloud agents enabled and credits available. On Enterprise plans, runs draw from a team credit pool per your contract. See [Access, billing, and identity](/platform/team-access-billing-and-identity/). -* **Oz by Warp GitHub App** - A GitHub organization owner installs the [Oz by Warp](https://github.com/apps/oz-by-warp) GitHub App on the organization or account that owns the repositories, granting it access to all repositories or a selected set. The installation's repository access is what agents act with, so scope it deliberately. +* **Warp Factories GitHub App** - A GitHub organization owner installs the [Warp Factories](https://github.com/apps/warp-factories) GitHub App on the organization or account that owns the repositories, granting it access to all repositories or a selected set. The installation's repository access is what agents act with, so scope it deliberately. * **An enabled GitHub organization** - A Warp team admin adds the organization under **Enabled GitHub Orgs** in the Admin Panel so the installation maps to your Warp team. * **A connected GitHub account** - Each teammate connects their GitHub account to Warp once, so Warp can identify who triggered the run and which team to bill. The connection identifies the requester; it doesn't determine what the agent can reach on GitHub. @@ -78,11 +78,11 @@ Complete steps 1 through 3 once per team. Step 4 is per teammate. Install the app so GitHub can deliver issue and pull request events to Warp, and so agents can read repository context and post comments. -A user with admin permissions on the GitHub organization installs the [Oz by Warp](https://github.com/apps/oz-by-warp) GitHub App and grants it access to **all repositories** or **selected repositories**. Each installation covers a single GitHub organization or personal account, so install the app separately for every organization your team works in. +A user with admin permissions on the GitHub organization installs the [Warp Factories](https://github.com/apps/warp-factories) GitHub App and grants it access to **all repositories** or **selected repositories**. Each installation covers a single GitHub organization or personal account, so install the app separately for every organization your team works in.
-![Oz by Warp GitHub App installation page showing repository access options](../../../../assets/agent-platform/oz-github-app-installation.png) -
Installing the Oz by Warp GitHub App.
+![Warp Factories GitHub App installation page showing repository access options](../../../../assets/agent-platform/oz-github-app-installation.png) +
Installing the Warp Factories GitHub App.
The agent can only act on repositories included in this installation. @@ -111,7 +111,7 @@ Configure the integration so every GitHub-triggered run uses the environment and The repository that triggered the event is always cloned for the run, so an environment is optional. Configure one when runs need additional repositories, a specific Docker image, or setup commands. Pick a GitHub environment whose repositories the same installation covers, since the run authenticates with that installation's token. :::note -Unlike Slack and Linear, the GitHub integration isn't created with `oz integration create`. It appears once the Oz by Warp GitHub App installation is associated with your team in the Admin Panel. +Unlike Slack and Linear, the GitHub integration isn't created with `oz integration create`. It appears once the Warp Factories GitHub App installation is associated with your team in the Admin Panel. ::: ### 4. Connect your GitHub account @@ -144,7 +144,7 @@ Every GitHub-triggered run is a cloud agent run: GitHub-triggered runs separate **what the agent can do on GitHub** from **who the run belongs to**. -**Access comes from the GitHub App installation.** A run started by an `@warp-agent` mention authenticates with a token minted for the Oz by Warp GitHub App installation that delivered the event, not with the mentioning user's GitHub authorization. Cloning, branches, commits, pull requests, and the status comments all use that installation token, so on GitHub the work is attributed to the Oz by Warp GitHub App rather than to the person who wrote the mention. The boundary on what the agent can reach is the installation's repository selection, optionally narrowed further by the repository access a Warp admin grants the team in the Admin Panel. Adjust the installation in your [GitHub settings](https://github.com/settings/installations). +**Access comes from the GitHub App installation.** A run started by an `@warp-agent` mention authenticates with a token minted for the Warp Factories GitHub App installation that delivered the event, not with the mentioning user's GitHub authorization. Cloning, branches, commits, pull requests, and the status comments all use that installation token, so on GitHub the work is attributed to the Warp Factories GitHub App rather than to the person who wrote the mention. The boundary on what the agent can reach is the installation's repository selection, optionally narrowed further by the repository access a Warp admin grants the team in the Admin Panel. Adjust the installation in your [GitHub settings](https://github.com/settings/installations). **Identity comes from the account connection.** Warp matches the GitHub account that posted the mention to the Warp account that connected it, not by email address. That binding decides who the run is attributed to in Warp, which team owns it, and whose credits pay for it. The person must be a member of the Warp team that enabled the organization. @@ -161,7 +161,7 @@ For fully automated workflows that run without a triggering user, such as schedu * **One run per thread at a time.** While a run for an issue, pull request, or review thread is active, further mentions become follow-ups to that run. * **The installation must map to a Warp team.** Repositories in an organization that no Warp team has enabled can't start runs. * **Installations are scoped to one organization each.** Install the app separately for every GitHub organization whose repositories your team works in. -* **Everything on GitHub is done by the app.** Comments, commits, branches, and pull requests come from Oz by Warp rather than the person who mentioned the agent, so the run can't reach anything the installation can't reach, and it isn't narrowed to what that person can reach either. +* **Everything on GitHub is done by the app.** Comments, commits, branches, and pull requests come from Warp Factories rather than the person who mentioned the agent, so the run can't reach anything the installation can't reach, and it isn't narrowed to what that person can reach either. * **The configured environment must be a GitHub environment.** A GitHub-triggered run rejects an environment built for another provider, such as GitLab or Bitbucket, and asks you to configure a GitHub environment instead. * **Environment repositories outside the installation stay out of reach.** The installation token only covers the repositories the app is installed on, so a repository in the environment that the installation doesn't cover isn't available to the agent. @@ -172,7 +172,7 @@ For fully automated workflows that run without a triggering user, such as schedu The event never reached Warp, or it was filtered out. Check in this order: 1. The comment body contains `@warp-agent`, spelled exactly, rather than only the issue or pull request title. -2. The Oz by Warp GitHub App is installed on the organization and has access to that repository. +2. The Warp Factories GitHub App is installed on the organization and has access to that repository. 3. The mention was posted by a person. Bot-authored comments are ignored. 4. The comment is new. Editing an existing comment to add the mention doesn't start a run. @@ -198,13 +198,13 @@ Use the error code in the thread's status comment to narrow the fix. Common erro ### The agent finished but opened no pull request -Confirm the Oz by Warp GitHub App installation covers the repository and still grants write access to it. Because the run acts with the installation's token, removing a repository from the installation, or narrowing the app's permissions, stops the agent from pushing branches or opening pull requests there. +Confirm the Warp Factories GitHub App installation covers the repository and still grants write access to it. Because the run acts with the installation's token, removing a repository from the installation, or narrowing the app's permissions, stops the agent from pushing branches or opening pull requests there. ## Removing or changing the integration -* **Change repository access** - Edit the Oz by Warp installation in your [GitHub settings](https://github.com/settings/installations). +* **Change repository access** - Edit the Warp Factories installation in your [GitHub settings](https://github.com/settings/installations). * **Stop runs for an organization** - A Warp team admin removes the organization from **Enabled GitHub Orgs** in the Admin Panel. Mentions in its repositories stop starting runs. -* **Remove the integration entirely** - Uninstall the Oz by Warp GitHub App from the GitHub organization. GitHub stops delivering events to Warp for every repository in that installation. +* **Remove the integration entirely** - Uninstall the Warp Factories GitHub App from the GitHub organization. GitHub stops delivering events to Warp for every repository in that installation. ## Related resources diff --git a/src/content/docs/platform/integrations/gitlab.mdx b/src/content/docs/platform/integrations/gitlab.mdx index d885a7abb..36ca120ba 100644 --- a/src/content/docs/platform/integrations/gitlab.mdx +++ b/src/content/docs/platform/integrations/gitlab.mdx @@ -8,6 +8,7 @@ description: >- --- import { VARS } from '@data/vars'; +{/* OPEN QUESTION for tech review (PR #549): confirm whether a native OAuth-based GitLab.com integration actually exists today. Our branch's prior copy claimed GitLab has no native integration (token-only); main@79f77e55 (below) claims native GitLab.com support exists. Verify against the product before merging. */} Cloud agents work natively with repositories hosted on GitLab.com. Connect your GitLab account when you create an environment in the {VARS.WEB_APP}, select the projects agents need, and Warp handles the rest at runtime: repositories are cloned automatically, your GitLab credentials are injected into the run, the `glab` CLI is authenticated, and agents can push branches and open merge requests on your behalf. Merge requests the agent opens are reported as run outputs. For self-managed GitLab instances, native connection isn't available yet. Instead, grant agents access using a personal access token and Warp-managed secrets, as described in [Self-managed GitLab instances](#self-managed-gitlab-instances). diff --git a/src/content/docs/platform/integrations/index.mdx b/src/content/docs/platform/integrations/index.mdx index 8a70e308c..bd981d9e3 100644 --- a/src/content/docs/platform/integrations/index.mdx +++ b/src/content/docs/platform/integrations/index.mdx @@ -17,7 +17,7 @@ Warp integrations let your team trigger agents directly from the terminal, or fr Integrations are one way to start a cloud agent. For the full set, including schedules, the {VARS.WARP_AGENT_CLI}, and the API, see [Triggers](/platform/triggers/). If you're deciding which one to use, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). :::note -Warp has two distinct GitHub surfaces. The [GitHub integration](/platform/integrations/github/) starts agents when someone mentions `@warp-agent` on an issue, pull request, or review comment, using the Oz by Warp GitHub App. [GitHub Actions](/platform/integrations/github-actions/) runs agents inside workflows you define in your own CI pipeline. +Warp has two distinct GitHub surfaces. The [GitHub integration](/platform/integrations/github/) starts agents when someone mentions `@warp-agent` on an issue, pull request, or review comment, using the Warp Factories GitHub App. [GitHub Actions](/platform/integrations/github-actions/) runs agents inside workflows you define in your own CI pipeline. ::: Integrations run on the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) (formerly Oz), which handles the trigger, the [environment](/platform/environments/) the agent executes in, and the record of each run. diff --git a/src/content/docs/platform/oz-web-app.mdx b/src/content/docs/platform/oz-web-app.mdx index 50d1f16f0..b40860d23 100644 --- a/src/content/docs/platform/oz-web-app.mdx +++ b/src/content/docs/platform/oz-web-app.mdx @@ -237,7 +237,7 @@ The **Integrations** page (`/integrations`) lets you configure first-party integ Click an integration to start the guided setup flow. You'll authorize Warp to connect with the external service, select an environment, and configure any integration-specific settings. -The GitHub row works differently. Instead of an authorization flow started here, it reflects the Oz by Warp GitHub App installation that a team admin enables in the Admin Panel. Once the installation is associated with your team, use the row to choose the environment, model, agent, prompt, and secrets that GitHub-triggered runs use. +The GitHub row works differently. Instead of an authorization flow started here, it reflects the Warp Factories GitHub App installation that a team admin enables in the Admin Panel. Once the installation is associated with your team, use the row to choose the environment, model, agent, prompt, and secrets that GitHub-triggered runs use. :::note For detailed integration setup instructions, see [Slack](/platform/integrations/slack/), [Linear](/platform/integrations/linear/), and [GitHub](/platform/integrations/github/). diff --git a/src/content/docs/platform/team-access-billing-and-identity.mdx b/src/content/docs/platform/team-access-billing-and-identity.mdx index aa09bcda0..1a98c73c7 100644 --- a/src/content/docs/platform/team-access-billing-and-identity.mdx +++ b/src/content/docs/platform/team-access-billing-and-identity.mdx @@ -102,25 +102,25 @@ Warp needs a reliable way to know which person a cloud agent run is acting for, * Each teammate must authorize GitHub before an agent can write PRs or push branches on their behalf * For Slack-triggered, Linear-triggered, and locally triggered runs, agents operate using the GitHub permissions of the triggering user -This ensures runs are scoped to what the user is allowed to see and modify, and that ownership of PRs remains clear across teams and repositories. The two exceptions are agent API key runs with [team GitHub authorization](#team-github-authorization) and runs started from an `@warp-agent` mention, which both authenticate as the Oz by Warp GitHub App installation. +This ensures runs are scoped to what the user is allowed to see and modify, and that ownership of PRs remains clear across teams and repositories. The two exceptions are agent API key runs with [team GitHub authorization](#team-github-authorization) and runs started from an `@warp-agent` mention, which both authenticate as the Warp Factories GitHub App installation. --- ## Team GitHub authorization -By default, cloud agents authenticate with GitHub using the personal token of the user who triggered the run. Team GitHub authorization gives you an alternative: authenticate with the **Oz by Warp** GitHub App instead, so agents can clone repositories and open pull requests without relying on any individual's token. +By default, cloud agents authenticate with GitHub using the personal token of the user who triggered the run. Team GitHub authorization gives you an alternative: authenticate with the **Warp Factories** GitHub App instead, so agents can clone repositories and open pull requests without relying on any individual's token. This is useful for fully automated workflows that use an [agent API key](/reference/cli/api-keys/), like CI/CD pipelines, scheduled agents, and SDK-triggered runs, where you want code changes attributed to the GitHub App rather than a specific person. ### How it works -When an agent task is initiated with an agent API key, there is no individual user to authenticate on behalf of. Instead, Warp uses tokens issued by the **Oz by Warp** GitHub App installation to authenticate directly with GitHub. +When an agent task is initiated with an agent API key, there is no individual user to authenticate on behalf of. Instead, Warp uses tokens issued by the **Warp Factories** GitHub App installation to authenticate directly with GitHub. The GitHub App token gives the agent access to the repositories included in the app installation — it can clone repos, create branches, push commits, and open pull requests. During installation, you choose whether the app can access **all repositories** or only **selected repositories** in your GitHub organization, and this controls what agent API key runs can access. ### Setting up team GitHub authorization -1. **Install the Oz by Warp GitHub App.** A user with admin permissions on the GitHub organization installs the [Oz by Warp](https://github.com/apps/oz-by-warp) GitHub App. During installation, grant the app access to **all repositories** or **selected repositories** in your org. +1. **Install the Warp Factories GitHub App.** A user with admin permissions on the GitHub organization installs the [Warp Factories](https://github.com/apps/warp-factories) GitHub App. During installation, grant the app access to **all repositories** or **selected repositories** in your org. :::note There are two places you may encounter this installation flow: @@ -131,8 +131,8 @@ There are two places you may encounter this installation flow: :::
- ![Oz by Warp GitHub App installation page showing repository access options](../../../assets/agent-platform/oz-github-app-installation.png) -
Installing the Oz by Warp GitHub App.
+ ![Warp Factories GitHub App installation page showing repository access options](../../../assets/agent-platform/oz-github-app-installation.png) +
Installing the Warp Factories GitHub App.
2. **Enable the GitHub org for your Warp team.** A Warp team admin opens the Admin Panel in the Warp app (**Settings** > **Admin Panel** > **Platform**) and adds the GitHub organization under **Enabled GitHub Orgs**. This associates the GitHub App installation with your Warp team. @@ -142,7 +142,7 @@ There are two places you may encounter this installation flow:
Enabled GitHub Orgs setting in the Admin Panel.
-3. **Use an agent API key.** Tasks initiated with an agent API key on the team now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed. On GitHub, commits and pull requests are opened by the Oz by Warp GitHub App rather than any individual user; in the {VARS.DASHBOARD}, the run is attributed to the bound [cloud agent](/platform/agents/). +3. **Use an agent API key.** Tasks initiated with an agent API key on the team now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed. On GitHub, commits and pull requests are opened by the Warp Factories GitHub App rather than any individual user; in the {VARS.DASHBOARD}, the run is attributed to the bound [cloud agent](/platform/agents/). ### How this relates to environments @@ -151,14 +151,14 @@ An [environment](/platform/environments/) is a template for a cloud agent's sand The environment configuration and the **Enabled GitHub Orgs** setting in the Admin Panel serve different purposes: * **Environment repo list** - "This agent needs repos A, B, and C." -* **Enabled GitHub Orgs** - "This team can use the Oz by Warp GitHub App to access repos in this GitHub organization." +* **Enabled GitHub Orgs** - "This team can use the Warp Factories GitHub App to access repos in this GitHub organization." ### Personal tokens vs. GitHub App tokens Team GitHub authorization is complementary to the existing personal token flow: * **User-triggered runs** (personal API key, Slack, Linear, Warp app) - The agent authenticates using the triggering user's personal token. PRs and commits are attributed to that user. -* **Agent API key runs with GitHub App authorization** - The agent authenticates as the GitHub App installation. On GitHub, PRs and commits are attributed to the Oz by Warp GitHub App rather than any individual user. In the {VARS.DASHBOARD}, the run is attributed to the bound [cloud agent](/platform/agents/), which controls run filtering and audit attribution on the Warp side. +* **Agent API key runs with GitHub App authorization** - The agent authenticates as the GitHub App installation. On GitHub, PRs and commits are attributed to the Warp Factories GitHub App rather than any individual user. In the {VARS.DASHBOARD}, the run is attributed to the bound [cloud agent](/platform/agents/), which controls run filtering and audit attribution on the Warp side. * **[GitHub integration](/platform/integrations/github/) runs** (an `@warp-agent` mention on an issue or pull request) - The agent authenticates as the installation that delivered the event, so its repository access and its GitHub attribution match the agent API key flow. In the {VARS.DASHBOARD} the run is still attributed to the teammate who wrote the mention, and their team is billed. These flows can coexist on the same team. Personal tokens are still used for user-triggered runs from a personal API key, Slack, Linear, and the Warp app, and the GitHub App installation token is used for agent API key runs and for GitHub integration runs. @@ -230,7 +230,7 @@ How credits are consumed depends on how the agent run is triggered and authentic * On Build, Max, and Business plans, Warp bills the team owner: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted. With auto-reload on, usage can trigger a reload on the owner's add-on credit pool subject to the team-wide monthly spend cap. * On Enterprise plans, these runs draw from the team-scoped credit pool, per your Enterprise contract terms. * Ideal for CI/CD pipelines, scheduled tasks, and other automated workflows. -* For workflows that require code changes (opening pull requests, pushing branches, or writing to a repository), configure [team GitHub authorization](#team-github-authorization) so the agent can authenticate with the Oz by Warp GitHub App. Alternatively, use a [personal API key](/reference/cli/api-keys/) to authenticate as an individual user. +* For workflows that require code changes (opening pull requests, pushing branches, or writing to a repository), configure [team GitHub authorization](#team-github-authorization) so the agent can authenticate with the Warp Factories GitHub App. Alternatively, use a [personal API key](/reference/cli/api-keys/) to authenticate as an individual user. For more details on creating and using API keys, see [API Keys](/reference/cli/api-keys/). diff --git a/src/content/docs/platform/triggers/scheduled-agents-quickstart.mdx b/src/content/docs/platform/triggers/scheduled-agents-quickstart.mdx index cdb5081ab..9ef9ae73e 100644 --- a/src/content/docs/platform/triggers/scheduled-agents-quickstart.mdx +++ b/src/content/docs/platform/triggers/scheduled-agents-quickstart.mdx @@ -40,7 +40,7 @@ Watch this short demo of creating and testing a scheduled agent: The **Agent** setting controls the identity behind every run, which determines how the agent authenticates to GitHub: * **Quick run** (default) - Runs execute as the user who created the schedule, using that person's GitHub credentials. Pull requests the agent opens are authored by that person. -* **Cloud agent** - Runs execute as the [cloud agent](/platform/agents/) you select. With [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) configured, the agent authenticates as the **Oz by Warp** GitHub App, so pull requests are authored by the app instead of an individual. +* **Cloud agent** - Runs execute as the [cloud agent](/platform/agents/) you select. With [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) configured, the agent authenticates as the **Warp Factories** GitHub App, so pull requests are authored by the app instead of an individual. Choose a cloud agent for any schedule that opens pull requests. Pull requests authored by the app are clearly attributable to automation, and anyone on the team can review and approve them — including the person who created the schedule, who cannot approve a pull request authored by their own account. diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx index c93911586..d5adbf4e1 100644 --- a/src/content/docs/reference/cli/api-keys.mdx +++ b/src/content/docs/reference/cli/api-keys.mdx @@ -64,7 +64,7 @@ The key type determines who the run is attributed to, which credit pool is bille * Run as a cloud agent on your team. * On Build, Max, and Business plans, bill the team owner: the owner's plan-included credits, then the owner's add-on credits. With auto-reload on, usage can trigger a reload on the owner's pool, subject to the team-wide monthly spend cap. On Enterprise plans, use the team-scoped credit pool. -* Use the **Oz by Warp** GitHub App when [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) is configured. Without team GitHub authorization, agent keys are still useful for tasks that don't need to write to GitHub, such as analysis, monitoring, or triage. +* Use the **Warp Factories** GitHub App when [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) is configured. Without team GitHub authorization, agent keys are still useful for tasks that don't need to write to GitHub, such as analysis, monitoring, or triage. For the full credit waterfall, see [Access, billing, and identity permissions](/platform/team-access-billing-and-identity/) and [add-on credits](/support-and-community/plans-and-billing/add-on-credits/). @@ -158,6 +158,6 @@ oz api-key expire "ci-pipeline" --force * **Use personal keys for runs that should act as you.** When code changes should be attributed to your GitHub account, a personal key is the right choice. Use agent keys for automation that isn't tied to a specific user. * **Use environment variables.** Avoid passing API keys directly in commands where they may be logged or visible in shell history. * **Set appropriate expiration.** Use shorter expiration times for development and testing; consider longer durations for stable production workflows. -* **Configure team GitHub authorization for agents that write to GitHub.** Personal keys authenticate as you with your GitHub permissions. Agent keys authenticate via the [Oz by Warp GitHub App](/platform/team-access-billing-and-identity/#team-github-authorization) when team GitHub authorization is configured in the Admin Panel. +* **Configure team GitHub authorization for agents that write to GitHub.** Personal keys authenticate as you with your GitHub permissions. Agent keys authenticate via the [Warp Factories GitHub App](/platform/team-access-billing-and-identity/#team-github-authorization) when team GitHub authorization is configured in the Admin Panel. * **Rotate keys periodically.** Create new keys and retire old ones on a regular schedule to limit exposure from compromised credentials. * **Store securely.** Use secret managers (like 1Password CLI, HashiCorp Vault, or cloud provider secret services) rather than plain text files. diff --git a/src/content/docs/reference/cli/integration-setup.mdx b/src/content/docs/reference/cli/integration-setup.mdx index 1cef7f8c6..29ee0fc1f 100644 --- a/src/content/docs/reference/cli/integration-setup.mdx +++ b/src/content/docs/reference/cli/integration-setup.mdx @@ -191,7 +191,7 @@ You typically only need to handle this once per team, unless your repo access ch #### Team-level GitHub authorization -For automated workflows that use an [agent API key](/reference/cli/api-keys/) (CI/CD pipelines, scheduled agents, SDK-triggered runs), you can configure team GitHub authorization so the agent authenticates with the Oz by Warp GitHub App instead of an individual's personal token. +For automated workflows that use an [agent API key](/reference/cli/api-keys/) (CI/CD pipelines, scheduled agents, SDK-triggered runs), you can configure team GitHub authorization so the agent authenticates with the Warp Factories GitHub App instead of an individual's personal token. This requires a Warp team admin to enable the GitHub organization in the Admin Panel (**Settings** > **Admin Panel** > **Platform**). Once configured, tasks initiated with an agent API key can clone repos and open pull requests using the GitHub App installation token. @@ -230,7 +230,7 @@ The CLI then: 3. Generates an **integration ID** you can later list or delete. :::note -The [GitHub integration](/platform/integrations/github/), which starts agents from `@warp-agent` mentions on issues and pull requests, isn't created with `oz integration create`. It's set up by installing the Oz by Warp GitHub App and enabling the GitHub organization in the Admin Panel. +The [GitHub integration](/platform/integrations/github/), which starts agents from `@warp-agent` mentions on issues and pull requests, isn't created with `oz integration create`. It's set up by installing the Warp Factories GitHub App and enabling the GitHub organization in the Admin Panel. ::: **Additional `integration create` flags:** diff --git a/src/sidebar.ts b/src/sidebar.ts index d25119f0a..d029c5fbe 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -462,9 +462,10 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ ], }, { - // Relabeled from 'Oz' for the 8/18 launch (HYC's IA doc, pending final - // ZL naming sign-off -- see .agents/references/terminology.md). Reorganized - // from 10 subsections into HYC's 6-group IA; all page slugs unchanged. + // Relabeled from 'Oz' to 'Automation Platform' for the 8/18 launch (HYC's + // IA doc; naming confirmed -- see .agents/references/terminology.md). + // Reorganized from 10 subsections into HYC's 6-group IA; all page slugs + // unchanged. id: 'platform', label: 'Automation Platform', // The tab lands on the platform overview rather than /platform/, which