diff --git a/src/content/docs/factories/code-forges/other-code-forges.mdx b/src/content/docs/factories/code-forges/other-code-forges.mdx new file mode 100644 index 000000000..1f0d203b1 --- /dev/null +++ b/src/content/docs/factories/code-forges/other-code-forges.mdx @@ -0,0 +1,81 @@ +--- +title: Connecting other code forges to your factory +description: >- + Connect a factory to a repository from another code forge using Agent Secrets + and setup commands on the default runner. +sidebar: + label: "Other code forges" +--- +import { VARS } from '@data/vars'; + +Connect your factory to a repository on Bitbucket, Azure DevOps, self-managed GitLab, or another code forge without first-class factory support. You can create the factory with no connected repository, then clone the repository from its default runner. + +:::caution +This setup gives factory agents repository access. It does not add provider-specific events or automations for the code forge. +::: + +## Prerequisites + +* **Factory access** - Permission to create the factory, add Agent Secrets, and edit its default runner. +* **Repository access** - An HTTPS clone URL and a token that can read the repository. + +For provider-specific token and clone formats, see [Bitbucket repository access](/platform/integrations/bitbucket/), [Azure DevOps repository access](/platform/integrations/azure-devops/), or [self-managed GitLab repository access](/platform/integrations/gitlab/#self-managed-gitlab-instances). + +## Create the factory without a repository + +To prepare a repository from the default runner, create the factory without a code-host connection. + +1. In the {VARS.FACTORY_WEB_APP}, click **+** next to **Factories**. +2. Under **Connect your code host**, select **No repo**. +3. Complete the remaining setup choices to create the factory. + +The factory opens in its dashboard without a connected repository. + +## Grant the clone credential + +Store the repository token as an Agent Secret so the default runner can use it without placing the token in a command or definition file. + +1. From the {VARS.FACTORY_WEB_APP}, click **Secrets**. +2. Create an Agent Secret named `CODE_FORGE_TOKEN`. +3. Enter the repository access token as the secret value, then grant `CODE_FORGE_TOKEN` to the factory agents that use the default runner. + +The secret is available to those agents and their runner setup commands as the `CODE_FORGE_TOKEN` environment variable. + +## Clone the repository from the default runner + +Runner setup commands prepare each agent workspace before factory work starts. + +1. From the factory dashboard, click **Settings** and scroll down to the "Runners" section. +2. Next to the default runner, click the edit button. In the "Setup commands" section, click **+** and add an authenticated `git clone` command that reads `$CODE_FORGE_TOKEN`. +3. Add any other project setup commands the repository needs, such as dependency installation, builds, or code generation. + +Use your code forge's documented clone format. For example, Bitbucket Cloud requires the `x-bitbucket-api-token-auth` username, while other hosts use a different username or authorization header. + +Setup commands run each time the runner prepares a workspace. Make the commands safe to run repeatedly. + +## Test repository access + +Start a direct factory run before you connect another work source. + +1. In the factory dashboard, open **Runs** and click **New**. +2. Send a read-only request such as: + + ```text title="Test repository access" + In the repository root, list the top-level files and report the current + branch. Do not change any files. + ``` + +3. Confirm that the run reports files from the cloned repository. + +If the run cannot clone the repository, confirm that the Agent Secret is granted to the agent, the token has repository read access, and the clone command uses the token environment variable correctly. + +## Starting work + +This code forge cannot start factory work from its own repository events. Start work from a connected service such as [Slack](/factories/integrations/slack/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/), through a [custom webhook](/factories/webhooks/), or with a direct factory run. + +## Related pages + +* [Connect GitHub to your factory](/factories/integrations/github/) - Use GitHub's first-class code-forge connection. +* [Connect GitLab to your factory](/factories/integrations/gitlab/) - Use GitLab.com's first-class code-forge connection. +* [Connect your factory](/factories/connect-your-factory/) - Add the sources that start work after the repository is available. +* [Cloud agent secrets](/platform/secrets/) - Store and scope credentials for cloud agents. diff --git a/src/content/docs/factories/connect-your-factory.mdx b/src/content/docs/factories/connect-your-factory.mdx index 78cea5336..ec829d6d1 100644 --- a/src/content/docs/factories/connect-your-factory.mdx +++ b/src/content/docs/factories/connect-your-factory.mdx @@ -11,6 +11,8 @@ Connect your factory to the tools where your team already discusses, tracks, and Each source feeds into this factory's repositories. If the work belongs to a different product surface, [start a new factory](/factories/#sizing-a-factory) for it instead. +GitHub and GitLab.com connect both repositories and provider-specific work sources. To use another code forge for repository access, [connect another code forge to your factory](/factories/code-forges/other-code-forges/). That fallback does not receive provider-specific events or automations. + ## Choose a source Pick the sources that match where work starts for your team. You can connect multiple sources, but not both Linear and Jira at the same time. The setup wizard currently offers Linear; to use Jira, connect it after setup or in your [factory definition](/factories/factory-as-code/). diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index a39d5081a..4f7927a53 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -50,7 +50,7 @@ Warp Factories is designed for engineering teams with repeatable work that exten * **Coordinated specialist agents** - A team of [factory agents](/factories/factory-agents/) handles each work item. A coordinating foreman routes it through the triage, spec, implement, and review agents, skipping stages that don't apply. You can add custom agents and automations to handle work the defaults don't cover. * **Definitions as code** - [Version-controlled definition files](/factories/factory-as-code/) describe your repositories, agents, automations, runners, [skills](/factories/factory-skills/), and MCP servers, so factory changes get the same review, history, and rollback as code changes. -* **Integrations and the Factory MCP** - Work flows in from [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Linear](/factories/integrations/linear/), and [Jira](/factories/integrations/jira/), plus [custom webhooks](/factories/webhooks/), direct runs, and schedules. The [Factory MCP](/factories/factory-mcp/) connects coding agents and other MCP clients. +* **Code forges and work sources** - Connect [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), or [another code forge](/factories/code-forges/other-code-forges/) to the repository your factory works in. Route work from [Slack](/factories/integrations/slack/), [Linear](/factories/integrations/linear/), [Jira](/factories/integrations/jira/), [custom webhooks](/factories/webhooks/), direct runs, or schedules. The [Factory MCP](/factories/factory-mcp/) connects coding agents and other MCP clients. * **Model and harness choice** - Each agent can use a different model and [supported harness](/platform/harnesses/), including the Warp Agent, Claude Code, and Codex. * **Measurement and self-improvement** - The [factory dashboard](/factories/factory-dashboard/) shows work-item status, runs, automations, costs, and benchmarks. [Scorers](/factories/measure-and-improve/scorers/) classify completed runs, [Benchmarks](/factories/benchmarks/) compare fixed tasks across configurations, and [Self-improvement](/factories/measure-and-improve/self-improvement/) turns repeated failures into follow-up work the factory proposes for review. * **Infrastructure control** - Run on Warp-hosted infrastructure, or self-host execution on an eligible Enterprise plan. Teams can also connect supported inference providers, scope secrets, and (if eligible) store transcripts, artifacts, and run attachments in their own S3 or GCS buckets. See [infrastructure and security](/factories/infrastructure-and-security/) for the available controls. diff --git a/src/content/docs/factories/integrations/gitlab.mdx b/src/content/docs/factories/integrations/gitlab.mdx index bb97b345c..de285ec09 100644 --- a/src/content/docs/factories/integrations/gitlab.mdx +++ b/src/content/docs/factories/integrations/gitlab.mdx @@ -12,7 +12,7 @@ When you connect a factory to GitLab, project activity starts work in your facto ## Prerequisites -* **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/). +* **GitLab.com** - The integration supports GitLab.com only, not self-managed GitLab instances. To use a self-managed instance with a factory, see [connecting other code forges](/factories/code-forges/other-code-forges/). For standalone cloud agents, 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 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. diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index b27d2a317..923df95f6 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -52,12 +52,16 @@ Warp walks you through a setup wizard: 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. + :::note + To use a repository hosted on another code forge, select **No repo**, finish creating the factory, then [configure repository access from the default runner](/factories/code-forges/other-code-forges/). + ::: +
![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.
-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. +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. This step applies to GitHub and GitLab connections. :::note Group repositories by product surface, not by team or task. For example, group all the repos behind one application. See [sizing a factory](/factories/#sizing-a-factory) before adding a repository another factory already covers. diff --git a/src/sidebar.ts b/src/sidebar.ts index e2dd86f1f..33b98d236 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -418,9 +418,22 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'factories/infrastructure-and-security', label: 'Infrastructure & security' }, ], }, + { + label: 'Code forges', + items: [ + // Keep these established URLs while grouping repository connections + // separately from the services that route work into a factory. + { slug: 'factories/integrations/github', label: 'GitHub' }, + { slug: 'factories/integrations/gitlab', label: 'GitLab' }, + { slug: 'factories/code-forges/other-code-forges', label: 'Other code forges' }, + ], + }, { // 'Integrations' per HYC (8/17), replacing 'Work intake'. // + // Code forges have their own group above because repository access is + // distinct from a service that starts or routes factory work. + // // The per-service pages are listed directly rather than in a nested // Integrations subgroup, which would have rendered as // Integrations > Integrations > Slack. @@ -432,8 +445,6 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ items: [ { slug: 'factories/connect-your-factory', label: 'Connect your factory' }, { slug: 'factories/integrations/slack', label: 'Slack' }, - { slug: 'factories/integrations/github', label: 'GitHub' }, - { slug: 'factories/integrations/gitlab', label: 'GitLab' }, { slug: 'factories/integrations/linear', label: 'Linear' }, { slug: 'factories/integrations/jira', label: 'Jira' }, // Custom webhooks connect any JSON-posting system, so they sit