# Stitch > Stitch automates software development workflows based on user-defined triggers. Organizations can quickly customize their agents to run across harnesses and sandboxes, coordinated by triggers from external applications and configured using Agents as Code (AaC). Define agents and workflows in your repository's stitch-factory.yaml file. Use the exact filename stitch-factory.yaml at the repository root, with no leading dot. ## Core concepts - **Sandboxes:** The compute environments where agents work on your repository. Configure the provider, resources, timeout, and setup scripts. - **Secrets:** Named credentials stored outside your repository for harness and sandbox authentication. Reference secret names in stitch-factory.yaml, never credential values. - **Harnesses:** The coding-agent tools that run inside a sandbox. Configure the agent type, version, model, and authentication. - **Triggers:** Rules that start an agent run from an external event, using a chosen harness and sandbox. Filters select which events qualify; guards cap run counts and concurrency within a supported scope to bound automation and prevent loops. ## Getting Started Follow these steps in order. Inspect what already exists, resolve choices with the user, then write and validate configuration. Do not treat the starter example as the user's chosen workflow. ### 1. Connect and authorize. This must be done by the user. - [Sign in](https://app.usestitch.ai/login): Log in to the Stitch application. - [Connect your repository](https://app.usestitch.ai/repositories): Connect the repository you want to automate. - Authorize your coding agent to use the CLI: run `stitch auth login`, complete the browser approval, and run `stitch auth whoami` to confirm the active organization. Use `stitch --help` to discover commands; do not invent commands for creating or applying factories. ### 2. Get the initial configuration and supported options - Inspect the target repository's instructions, agent definitions, and skills. If stitch-factory.yaml already exists, use it as the starting point and preserve unrelated configuration. If it does not exist, fetch the [starter factory configuration](https://app.usestitch.ai/examples/autonomous-delivery.yaml) as a reference, then create `stitch-factory.yaml` at the repository root only after confirming the choices below. If the example cannot be fetched, report that limitation; do not claim to have read it. - The starter demonstrates triage, implementation, and a bounded review-and-fix workflow. Do not copy its harnesses, sandboxes, models, authentication methods, provider identifiers, or workflow as defaults. Do not assume its `build` and `review` agents or `code-review` skill exist. Adapt the configuration to the user's decisions and repository; new triggers must start disabled. - Before drafting configuration, read the [factory configuration schema](https://app.usestitch.ai/api/schema/factory.json) to discover available harnesses, sandbox providers, authentication methods, triggers, and supported fields. Base recommendations on the current schema, not the sample or assumed availability. If the schema cannot be fetched, report the blocker rather than guessing. Use `stitch validate` to check cross-field rules and server requirements that JSON Schema cannot express. ### 3. Resolve only missing choices Use the user's request, existing configuration, and repository facts to avoid questions already answered. Ask only about missing choices that block a correct, safe configuration, using the question tool if available; otherwise ask in chat. Group related questions and offer a schema-supported recommendation instead of making the user choose every field. Summarize the proposed workflow, harnesses, sandboxes, and limits for one confirmation before writing YAML; make proposed defaults explicit. ### 4. Set up authentication and external prerequisites - Reuse the confirmed harness and sandbox choices; do not ask for them again. Explain the required setup and ask only for missing account or project identifiers and secret names. Do not build or provision resources on the user's behalf without confirmation. - Identify secrets required by the confirmed harness and sandbox authentication choices. Run `stitch secrets list` and reuse existing secret names when appropriate. For missing secrets, explain which credential is needed and, with the user's permission, add it through `stitch secrets add `. Have the user enter the value in the CLI's hidden prompt; if the agent cannot provide a private interactive terminal, ask the user to run the command themselves. Do not request credentials through the question tool or chat, and never put secret values in YAML, command arguments, or logs. Check the secret names again before full validation; do not overwrite existing secrets without permission. - For every trigger, list the external resources, integration connections, and permissions it needs. Configuration references do not create those resources. Ask the user to create missing external resources, such as GitHub labels, and to complete any required integration or permission setup. Give exact names, the target repository or account, and instructions or a command they can run. Verify the prerequisites after the user completes setup. Do not enable affected triggers until those prerequisites are verified; if you cannot inspect them, report the blocker. - Inspect GitHub using `gh` against the explicit target repository. Run `gh label list --repo --limit 1000 --json name` and check every configured label against the actual results, including labels added by agents later in the workflow. Reuse exact existing names. For missing labels, ask the user to create them with `gh label create --repo `, then check again. Do not silently create or substitute labels, or apply labels to existing issues during setup. ### 5. Write bounded triggers - Ensure trigger handoffs are coherent: agent prompts must instruct upstream agents to perform the actions that emit the required downstream events, and downstream filters must accept those events. - Configure precise event types, actions, filters, and valid guard scopes. For label-driven implementation, use `issues`, `actions: [labeled]`, explicit labels, and `labelScope: changed`. Decide `ignoreBots` deliberately: downstream steps must accept the upstream agent's events, while filters and guards prevent self-triggering loops. Ignore draft pull requests where appropriate. - Bound automation with `max_occurrences` and `max_concurrent` guards using scopes supported by each event. In the example, implementation runs once per issue; review and each fix trigger run at most twice per pull request, with concurrency limited to one per trigger. Human change-request reviews use `pull_request_review`, `actions: [submitted]`, and `reviewStates: [changes_requested]`. The review agent submits one `COMMENT` review through `gh api` with all actionable inline findings, verifies submission, then adds `work_needed`, because GitHub rejects change-request self-reviews. A second fix trigger uses `pull_request`, `actions: [labeled]`, `labels: [work_needed]`, and `labelScope: changed`. Its worker removes the label before pushing once all actionable findings are addressed, or keeps it when blocked. Avoid per-comment triggers for this loop. ### 6. Validate and ask for activation approval - Validate locally with `stitch validate --dry-run`, then run `stitch validate --repository ` using the connected repository ID from the application, not its GitHub name. Use `--ref ` when validating against agent definitions on a specific ref. Fix diagnostics and repeat until both checks pass. Validation does not apply configuration, start runs, create external resources, or test provider credentials by executing them. - Show the user the final configuration, event chain, permissions, labels, secrets required, and run limits. Keep triggers disabled until the user approves activation. Commit, push, or enable automation only with approval, then verify the applied configuration in the application before declaring setup complete. ## CLI - Install globally with npm: `npm install -g @usestitch/cli`, then run `stitch --help`. Requires Node.js 24 or later. - Run without installing globally: - Bun: `bunx @usestitch/cli --help`. - NPM: `npx @usestitch/cli --help`. ## Configuration resources - [Factory configuration schema](https://app.usestitch.ai/api/schema/factory.json): JSON Schema for the repository's stitch-factory.yaml configuration.