Skip to main content
The Factory setup wizard is a form-based way to stand up a Software Factory. Instead of describing what you want to Smith in chat, you work through a sequence of screens, and the wizard creates the workspace, credentials, runtime environment, and agents the Factory needs. Each screen states one fact the next depends on, so the steps run in order and each passes its result forward. You can leave the wizard and come back: your progress is saved as a setup attempt, and the wizard resumes from the answers it already holds. For the conversational alternative, see Software Factory commissioning. To have a coding agent such as Claude Code or Codex set up the Factory from your terminal with the Guild CLI, point it at the coding agent setup guide. To run the same setup yourself from the terminal, use guild factory init.

​
Open the wizard

Once you start, the wizard moves to a URL for your setup attempt. Bookmark it to return to that attempt directly.

​
Resuming an attempt

When you return to the wizard with a pending attempt, an arrival notice shows how long ago you started the attempt and which step you left off at. From the notice, you can resume where you stopped or discard the attempt and begin again.
  • Resume — continue from the saved step with the answers the wizard already holds.
  • Start over — discard the attempt and return to the first step. The wizard opens a confirmation dialog before it discards your progress.

​
Steps

1

Connect

After you sign in, choose the account and workspace, connect GitHub, and select the repository the Factory needs.
2

LLM Keys

Eligible accounts skip this step because Guild tokens are included. Otherwise, add the model credential the Factory calls.
3

Environment

The Factory scans your repository and writes a setup script to build it.
4

Issues

Where issues live — usually already covered by the Connect step. This is the final step: confirming it creates the Factory and requests the install.
5

Live

Add the trigger label to an issue and the Factory gets to work.

​
Connect

The Connect step sets up the account, workspace, and repository in one screen. Pick the account that owns the workspace, name the workspace, and connect the repository.
Eligible accounts receive included Guild tokens and skip the LLM Keys step. Otherwise, you add a model credential after Connect.
A workspace is where the Factory’s containers run. It comes before the LLM Keys step because that step can scope a model key to this workspace. The key itself is always stored on the account; a workspace-level model policy points the workspace at it.
Naming the workspace is a one-shot — a workspace cannot be renamed after it is created. Choose the name before you continue.
Choose an existing GitHub credential or connect through the GitHub App or OAuth. Then select the repository the Factory reads issues from and opens pull requests against.

​
Environment

The environment step turns the connected repository into a runtime environment the Factory’s agents can run in. The wizard scans the repository, proposes a setup script, saves it as a runtime environment, and then builds that environment to confirm it works. The scan reports its progress as it goes, so you can follow which part of the repository it is working through. The first test run starts automatically after the wizard saves the proposed script. If the run fails, review and edit the script, then select Run again.

​
When the test run fails

A failed run reports what it found: You can also open the session or the full container log from the same place. The build runs in the background, so a reload rejoins it rather than restarting it. Continue becomes available only after the verify run passes. A failed test keeps you on the step until you edit the script and Run again succeeds. If the scan fails or produces no script, select Try again.

​
Live

The Factory starts working when you add a trigger label to an issue. Labels drive the pipeline’s stages — planning, implementation, and review — and the Factory moves an issue through to a branch, a commit, a pull request, and a review. A Jira Factory needs two labels. Add a routing label (guild-factory-<workspace-id>) to route the issue to the Factory, then add the action label (for example, guild-auto) to start it. You can add both labels at once.
The action label alone does not trigger a Jira Factory. The issue also needs the routing label, or the Factory never picks it up.

​
Start from the CLI

You can also start Factory work from the command line with guild factory start, which accepts either a GitHub or a Jira issue. Guild validates the issue and adds the configured labels to start the pipeline. See guild factory start in the CLI command reference. For a Jira issue, Guild validates the site, project, and connection before it adds the configured labels, so pass the full HTTPS browse URL on the configured site and project, not a bare issue key:
Last modified on October 15, 2026