Factories > Configure your factory
Setting up a factory for microservices
Group related microservices in Warp Factories, provide each service's toolchain, and verify provider and consumer contracts together.
Use Warp Factories to group services that share a contract and an owner. Workers verify changes against contract files in the repositories rather than a live deployment.
Start with the Blueprint from factory setup and add the related repositories. The 01-single-repo-quickstart example supplies repository and runner settings. The examples below use a Go API and a Node web app sharing openapi.yaml; replace their names, paths, and commands with yours.
How a microservices factory is organized
Section titled “How a microservices factory is organized”Group services in one factory when they share an API, schema, or event contract, regularly need coordinated changes, and are reviewed by the same team. Use separate factories for services that change independently or have different owners, even if they communicate in production. See factory boundaries for guidance.
This example allows only additive contract changes. For breaking changes, such as removing, renaming, or changing a field’s type, the foreman explains what is needed instead and stops.
Runs start with repository checkouts, not deployed services. Verify changes using contract files and fixtures. If a test needs a dependency such as a database, start it in the sandbox with the repository’s documented command. Warp-hosted Linux runners support Docker containers.
A change spanning services produces one pull request per repository. A person controls the merge order. See coordinating changes across multiple repositories.
| Part | Recommendation |
|---|---|
| Trigger | A maintainer applies factory-ready to an issue in any of the factory’s repositories |
| Repositories | The services that share a contract and an owner; the foreman’s instructions name the provider |
| Workers | Foreman, implement, and review; review only checks that the services agree |
| Runner | One Linux image that carries every service’s toolchain, with a per-service dependency prefetch |
| Output | One pull request per changed service with its checks and contract-check results |
Prerequisites
Section titled “Prerequisites”- A factory connected to GitHub with access to every service repository.
- A Blueprint with workers assigned to planning, implementation, and independent review.
- A provider contract file, such as
openapi.yaml, and contract checks in each repository. The provider checks its handlers against the contract. Each consumer regenerates its client and type-checks all call sites. - Documented bootstrap and test commands for every service.
Group related services
Section titled “Group related services”-
Update the existing
factory.yamlwith the provider and its consumers, retaining its Blueprint. This fragment has one of each. Add consumers that share the contract and reviewers.factory.yaml schemaVersion: v1alpha1name: related-servicesalias: Servicesrepositories:- owner: acmename: api-service- owner: acmename: webappagentDefaults:model: autorunner: linux-services -
Define each repository’s role in a shared skill. Require the Blueprint’s planning stage to use it:
- Identify the contract provider and its consumers.
- Identify which services a request affects, order changes from provider to consumer, and decline work outside the factory.
-
Create the
factory-readylabel in every service repository. GitHub labels are configured separately for each repository. -
Configure the intake automation to match those repositories and the
factory-readylabel:Intake trigger triggers:- provider: githubevent: issue_labeledfilter:repos: [acme/api-service, acme/webapp]labels: [factory-ready]
Provide runtime context
Section titled “Provide runtime context”-
Choose one runner image with every service’s toolchain. Options include:
warpdotdev/dev-go:1.23, used below, with Go and Node.warpdotdev/dev-full:latest, with every language in Warp’s prebuilt dev images.- Another public image with the required toolchains.
-
Add one dependency prefetch command per repository to the runner’s
setupCommands. Each command starts in/workspace, so change to the repository’s directory before fetching dependencies.runners/linux-services.yaml description: >-One runner with Go and Node for the API and web app checkouts.setupCommands:- '(cd /workspace/api-service && go mod download) || echo "Warning: api-service prefetch skipped" >&2'- '(cd /workspace/webapp && npm ci) || echo "Warning: webapp prefetch skipped" >&2'instanceShape:vcpus: 4memoryGb: 8platform:os: linuxarch: x86_64linux:dockerImage: warpdotdev/dev-go:1.23 -
Document each service’s commands in a shared skill under
skills/. Require implementation and review to use it. Include:- Bootstrap command.
- Normal checks.
- Contract check.
- Contract file path.
See factory skills for the shared skill format.
-
Configure any access the service needs beyond its checkout:
- MCP servers for logs or error tracking when handling incidents.
- Factory secrets for private package registries.
Skills describe how to use resources. Access comes from the worker’s configuration.
Verify against contracts and dependencies
Section titled “Verify against contracts and dependencies”In factory.yaml, configure the Blueprint stages below. Pass the ordered repositories and compatibility decision from planning to implementation, then pass contract diffs and check results to review. Return findings to implementation; send incompatible changes to a human decision before any branch is created.
-
In the planning stage’s
prompt, require the compatibility policy from the shared skill:- Change the provider first.
- Allow only backward-compatible additions. Do not remove, rename, or change the types of existing fields or endpoints, or add required request fields.
- For a breaking change, comment with an alternative, such as a versioned endpoint or coordinated deployment, and stop without creating a branch.
Check that the deployed consumer tolerates the additions.
-
In the implementation stage’s
prompt, require the provider’s checks:- Run bootstrap, retrying any failed dependency prefetch before testing. Report a blocker if bootstrap still fails.
- Update the contract file before the handlers and their tests.
- Run the normal checks and contract check.
- Confirm that the contract diff contains only additions.
For example, run
go build ./... && go test ./..., your repository’s contract check, andgit diff origin/main -- openapi.yamlafter fetching the default branch. Substitute its name if it isn’tmain. -
Require consumer verification against both versions of the provider’s contract:
- For a paired change, copy the provider branch’s schema over the consumer’s vendored copy. For consumer-only work, keep the vendored schema unchanged.
- Run
npm run contract-checkto regenerate the client and type-check its callers, thennpm run lint && npm test. - Probe the provider’s current
mainschema using your contract check’s schema-path option, or replace its input file. Record the result separately. - After the probe, restore the vendored schema as input, regenerate the client, and rerun the normal checks. These checks must pass, and the final generated client must match the vendored schema, not the probe.
- For a pair, a probe failure caused by the new contract explains why the consumer merges second. For consumer-only work, the probe must pass; an unreleased dependency goes back to the foreman as a scope mismatch.
-
In the review stage’s
prompt, require its assigned worker to confirm that:- For a pair, the provider’s contract and consumer’s vendored copy are identical, and the consumer uses the added fields with matching names and types.
- A provider change leaves the contract unchanged or additive.
- A consumer change records passing checks after regeneration from its vendored schema, including after the
mainprobe. - A one-service change remains compatible with the unchanged service.
Leave other judgments to a person.
-
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.
Test the factory
Section titled “Test the factory”- Apply
factory-readyto an issue that changes only one service. Check for one pull request with that service’s check results and no merge-order requirements. - Apply
factory-readyto an issue that adds an optional field to the provider’s contract and displays it in the consumer. Check for two pull requests:- Provider: An additive contract diff and the provider’s check results.
- Consumer: A passing contract check against the provider’s branch, the probe result against current
main, and passing checks after regeneration from the vendored schema. A probe failure caused by the new field explains why the consumer merges second.
- Apply
factory-readyto an issue that renames a field in every response. Check that the foreman explains why the breaking change is out of scope and creates no branch.
Set it up with a prompt
Section titled “Set it up with a prompt”- Replace the uppercase placeholders in the following prompt with your information.
- 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.
Read https://docs.warp.dev/factories/guides/microservices-factory.md and adapthttps://github.com/warpdotdev/warp-factory-examples/tree/main/examples/01-single-repo-quickstartfor repository and runner settings in my existing Blueprint factory.The provider repository is OWNER/PROVIDER and its contract file isCONTRACT_PATH. The consumerrepositories are CONSUMER_LIST. Replace acme/api-service and acme/webappeverywhere they appear, replace the bootstrap, test, and contract-checkcommands and the schema paths with the ones each repository really uses,and pick a runner image that carries every toolchain. Keep the rules: theprovider changes first with backward-compatible additions only, never newrequired request fields. Every service runs its ownchecks and contract check, the consumer also checks against theprovider's current default branch. After that probe, regenerate from thevendored schema and rerun positive checks before publishing. Consumer-onlywork must pass against the current provider without a companion PR.Put planning, implementation, review, and handoff procedures in the Blueprint.Pass the ordered repositories, contract diffs, and check results between stages.Return review findings to the same implementation conversation and PRs.The reviewer checks contract consistency and that final verification.Validate the definition before you open a pull request, nevermerge, and list anything I still have to do myself: connecting GitHub,creating the factory-ready label in each repository, adding a contractcheck where one is missing, and registering the definition.Troubleshooting
Section titled “Troubleshooting”- A service’s bootstrap fails: The image may lack its toolchain, or the command may run in the wrong directory. Use an image with every service’s toolchain and start each setup command with
cd /workspace/REPOSITORY_NAME. - The consumer’s contract check fails against the provider’s
main: For a paired change, a failure caused by the new contract explains why the consumer merges second. Regenerate from the vendored schema and rerun positive checks before publishing. Unrelated failures need a fix; consumer-only work must pass againstmain. - The worker tries to verify against a live service: Runs start with repository checkouts, not deployed services. Point verification at contract files and fixtures, and document how to start test dependencies inside the sandbox.
- The foreman accepts a breaking change as additive: The compatibility instructions or contract-diff check may be incomplete. Explicitly prohibit removals, renames, type changes, and new required request fields, and require the provider’s contract diff in verification.
Guide navigation
Section titled “Guide navigation”- Previous stage: Factory boundaries
- Next stage: Testing and tuning your factory
- All stages: Factory guides
Related pages
Section titled “Related pages”- Coordinating changes across multiple repositories - Linked pull requests and the merge order a person controls
- MCP servers for factory agents - Give workers logs, error tracking, and other service context
- Runners for Warp Factories - Images, setup commands, and what a Warp-hosted sandbox can run