Skip to content

Factories > Configure your factory

Coordinating changes across multiple repositories

Coordinate changes across repositories with Warp Factories, linked pull requests, and a merge order controlled by a person.

Open in ChatGPT ↗
Ask ChatGPT about this page
Open in Claude ↗
Ask Claude about this page
Copied!

Use Warp Factories to coordinate work across repositories and deliver linked pull requests for a person to merge in a documented order. Cross-repository changes are not atomic: each repository has its own branch and pull request.

Start with the Blueprint from factory setup and add the related repositories. Use 01-single-repo-quickstart for repository and runner settings, not as a replacement for that workflow. Replace the illustrative acme/api-service and acme/webapp repositories with yours.

The factory’s repositories list selects the checkouts for every run. A change touching two repositories produces two pull requests. To keep them compatible between merges, change the provider first in ways deployed consumers tolerate. A person merges in that order and reverts in reverse.

The example repositories share an API contract, so the provider changes first and additively. The same shape covers a frontend and backend in separate repositories, a library and the services that pin it, or a schema repository and its consumers. For what to verify inside each service, see setting up a factory for microservices.

PartRecommendation
TriggerA maintainer applies factory-ready to an issue in any of the factory’s repositories
RepositoriesEvery repository a coordinated change can touch, named by role in the foreman’s instructions
WorkersForeman decides the order, implement opens one pull request per repository, review checks that the pair agrees
RunnerOne Linux image with every repository’s toolchain
OutputLinked pull requests titled [1/2] and [2/2], each stating the merge order, plus a foreman comment with both links
  • A factory connected to GitHub with access to every repository.
  • A Blueprint with workers assigned to planning, implementation, and independent review.
  • Documented bootstrap and test commands for every repository, plus a compatibility check such as a contract check.
  • Branch protection and required reviews on every repository for human-controlled merging.

List every repository a coordinated change can touch. This selects the checkouts; code-host permissions control whether the worker can push.

  1. Add each repository to the factory:

    • Warp-managed factory: Open the factory’s Settings in the factory dashboard and update the repository selection under “Repos”.
    • GitHub-backed factory: Update repositories in the existing factory.yaml using the fragment below. Retain its Blueprint and other settings.

    For repositories on different code hosts, specify each repository’s codeForge. See codeForges.

    factory.yaml
    schemaVersion: v1alpha1
    name: related-services
    alias: Services
    repositories:
    - owner: acme
    name: api-service
    - owner: acme
    name: webapp
    agentDefaults:
    model: auto
    runner: linux-services
  2. Confirm the GitHub App installation grants access to every repository. The worker can push only to repositories covered by the installation. See GitHub permissions.

    Every run checks out the factory’s repositories under /workspace.

  3. Create the factory-ready label in each repository. GitHub labels are configured separately for each repository.

  4. Configure the intake automation to match all of the factory’s repositories and the factory-ready label:

    automations/issue-labeled/automation.md
    ---
    triggers:
    - provider: github
    event: issue_labeled
    filter:
    repos: [acme/api-service, acme/webapp]
    labels: [factory-ready]
    ---
    A maintainer labeled an issue `factory-ready` in one of the two related
    repositories. Read the issue, decide which repositories change and in which
    order, and drive the change to one pull request per repository. Post your
    decision, progress, and the final merge order as comments on the issue.
  5. Configure the runner with an image containing every repository’s toolchain and a dependency prefetch command for each repository.

    See the example runner in setting up a factory for microservices.

In factory.yaml, configure the Blueprint stages below. Pass the ordered repository list and linked PRs between stages, and return review findings to implementation. Keep shared compatibility policy in a skill.

  1. Define repository roles and compatibility rules in a shared skill. Require the planning stage to use it:

    • Identify the provider and its consumers.
    • Change the provider first, using backward-compatible additions. Do not add required request fields. In this example, acme/api-service adds response fields and endpoints that the deployed acme/webapp can safely ignore until its change merges.
    • For a breaking change or a repository outside the factory, comment with what is needed instead and stop.

    A single-repository change needs no cross-repository merge order.

  2. In the planning stage’s prompt, require the worker to announce the plan before implementation:

    • Comment on the issue with the repositories to change, the merge order, and the reason for that order.
    • Pass the issue, ordered repository list, and compatibility rule to the implement worker.
  3. In the implementation stage’s prompt, require the worker to:

    • Open one pull request per changed repository.
    • Use the same branch name in each repository, such as factory/118-order-status.
    • Prefix the titles with [1/2] and [2/2] to show merge order. Omit the prefix for a single-repository change.
    • Include Summary, Compatibility, and Verification sections. Add Linked PR only for a paired change.
  4. Require verification that supports the merge order:

    • Provider: Run its checks and confirm the contract diff contains only additions.
    • Consumer: Run its checks against the provider’s branch and probe current main. Regenerate the client from the vendored schema after the probe and rerun positive checks before publishing. For a pair, a probe failure caused by the new contract explains why the consumer merges second. Consumer-only work must pass against the current provider.

    Follow the contract-check sequence, including restoring the generated client after the probe.

  5. In the review stage’s prompt, limit review to whether the pull requests agree and are safe to merge in the documented order. Require findings as stage outputs, not comments on the pull requests. The foreman uses them to request revisions or hand off the work.

  6. Apply and validate the factory definition:

    • Warp-managed factory: Save the edits in the factory dashboard.
    • GitHub-backed factory: Merge the edits into the production branch.

    Confirm validation succeeds before testing. See where the definition lives.

  1. Require the implement worker to link the pull requests in both directions:
    • Link the issue and the other pull request in each description.
    • State whether each pull request merges before or after the other.
    • Link to the provider when opening the consumer’s pull request, then update the provider’s description with the return link.
  2. Require a Compatibility section describing behavior between merges. In this example, the API serves the new field and the deployed web app ignores it until its own change merges.
  3. Instruct the foreman to check both links before handing off the change, then post an issue comment with both pull request links, the merge order, and the compatibility note.

The factory never merges. A person merges in the order the foreman posted, and the repositories’ own branch protection enforces who can do that.

  1. Merge the provider’s pull request, [1/2].
  2. Confirm the merge is complete. If merging triggers deployment, wait for deployment to finish.
  3. Merge the consumer’s pull request, [2/2].

To revert the change, reverse the order: revert the consumer first, then the provider.

  1. Apply factory-ready to an issue requiring an additive change in both repositories, such as adding an optional response field and displaying it in the consumer. Check for:
    • Verification commands run in both checkouts.
    • Pull requests titled with [1/2] and [2/2], linking each other and the issue.
    • The consumer’s check result against the provider’s current main, recorded in the consumer’s description.
    • Passing checks after the consumer client is regenerated from its vendored schema.
    • A foreman comment on the issue with both pull request links and the merge order.
  2. Apply factory-ready to an issue that changes only one repository. Check for one pull request with no title prefix or cross-repository merge order.
  3. Apply factory-ready to an issue requiring a breaking change, such as renaming a field in every response. Check that the foreman comments with what is needed instead and creates no branch.
  4. Apply factory-ready to an issue in a repository outside the factory. Check that no run starts.
  1. Replace the uppercase placeholders in the following prompt with your information.
  2. Paste the completed prompt into a conversation with your factory’s foreman (New Chat in the factory dashboard) or a coding agent connected through Factory MCP.
Prompt
Read https://docs.warp.dev/factories/guides/multi-repository-factory.md and adapt
https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/01-single-repo-quickstart
for repository and runner settings in my existing Blueprint factory.
The repository others depend on is OWNER/PROVIDER; its consumers are
CONSUMER_LIST. Replace acme/api-service and acme/webapp everywhere they
appear (factory.yaml, the automation, the runner, and stage procedures),
replace the bootstrap, test, and contract-check commands with
the ones each repository really uses, and pick a runner image that carries
every toolchain. Keep the rules: the provider changes first and only
with backward-compatible additions, never new required request fields.
Open one pull request per changed repository. For a pair, link both ways
and state the merge order in each description. Put planning, implementation,
review, and handoff in the Blueprint, with shared compatibility policy in a
skill. Pass ordered repositories and linked PRs between stages, and return
findings to the same implementation conversation. Require independent review
of contract consistency and leave merging to a human.
For consumer checks, regenerate from the vendored schema and rerun positive
checks after probing the provider's current default branch. One-repository
work needs no companion PR; consumer-only work must pass against the current
provider. Validate the definition before you open a pull request, never
merge, and list what
I still have to do myself: connecting GitHub, creating the factory-ready
label in each repository, and registering the definition.
  • A two-repository change produces only one pull request: The second repository may lack GitHub App access, or the foreman may have scoped the task to one repository. Check installation access, the foreman’s issue comment, and the run on the factory’s Runs page.
  • The pull requests do not link each other: The first description may not have been updated after the second pull request opened. Require the implement worker to add the return link and the foreman to check both descriptions before handoff.
  • Production breaks after the consumer merges first: The consumer may require a contract the deployed provider does not serve yet. Revert the consumer, then follow the documented merge order. Branch protection controls who can merge, not cross-repository order, so keep that order in each description and the final issue comment.
  • One change starts two runs: The same change may have been labeled in two issues, or automation filters may overlap. Use one issue per change and nonoverlapping filters. See one action starts two runs.