# CLI

URL: https://docs.usestitch.ai/docs/factory/cli



```sh
npm install -g @usestitch/cli
stitch --help
```

Requires Node.js 24+. `FACTORY_URL` overrides the server origin; HTTPS is required except
on localhost. Results and errors are JSON. Help is text. Treat non-zero exits as failure.

## Commands [#commands]

| Command                                                                                      | Purpose                                |
| -------------------------------------------------------------------------------------------- | -------------------------------------- |
| `stitch auth login`                                                                          | Browser-approved device login          |
| `stitch auth whoami`                                                                         | Check active identity and organization |
| `stitch auth logout`                                                                         | Revoke CLI session                     |
| `stitch repositories list`                                                                   | List connected repositories            |
| `stitch secrets list`                                                                        | List secret metadata, not values       |
| `stitch secrets add <name>`                                                                  | Add a value through a hidden prompt    |
| `stitch validate [file] --dry-run`                                                           | Offline schema and cross-field checks  |
| `stitch validate [file] --repository <id> [--ref <ref>]`                                     | Full read-only validation              |
| `stitch webhooks list`                                                                       | List factory endpoints                 |
| `stitch webhooks get <factory-id>`                                                           | Inspect an endpoint                    |
| `stitch webhooks deliveries <factory-id>`                                                    | Inspect delivery results               |
| `stitch webhooks send <factory-id> --event <name> --idempotency-key <id> --data-file <file>` | Send an event                          |

Use each command's `--help` for further options. `webhooks key` and `webhooks rotate`
return credentials; run privately and do not log output.

## Validation contract [#validation-contract]

Default file: `stitch-factory.yaml`. Do not combine `--dry-run` with `--repository` or `--ref`.
Full validation needs login, a connected repository ID, and referenced secrets.
Inspect `ok`, `valid`, and `errors`; errors include codes, JSON paths, and available hints.
`valid: null` means validation could not complete, not that the file is valid.
Validation does not apply changes or test credentials. Deployment occurs through the default branch.

## Schema [#schema]

[Factory JSON Schema](/schema/factory.json). JSON Schema does not encode every custom
refinement; always run `stitch validate` before pushing.


# Factory

URL: https://docs.usestitch.ai/docs/factory



Store `stitch-factory.yaml` at the repository root, with no leading dot.
Stitch reconciles it from the connected repository's default branch.
Use local `key` values to link each trigger to a harness and sandbox.

## Schema [#schema]

[Factory JSON Schema](/schema/factory.json) · [Environment schema](/schema/environment.json)

| Field                            | Contract                                                                |
| -------------------------------- | ----------------------------------------------------------------------- |
| `schemaVersion`                  | `1`                                                                     |
| `name`, `description`            | Factory name and optional description                                   |
| `execution.environmentVariables` | Inline values or managed secret references; required array              |
| `harnesses`                      | At least one harness; unique `key`                                      |
| `sandboxes`                      | At least one sandbox; unique `key`                                      |
| `triggers`                       | At least one trigger; unique `key`; existing harness/sandbox references |

Keys match `^[a-z][a-z0-9_-]{0,63}$`. Unknown fields are rejected.
Environment bindings have a `key`, `source`, and `targets` (`setup`, `harness`, or both).
Use `value` for `source: inline`; use `secretName` for `source: managed`.

```yaml
execution:
  environmentVariables:
    - key: SERVICE_TOKEN
      source: managed
      secretName: SERVICE_TOKEN
      targets: [harness]
```

## Apply changes [#apply-changes]

Validate offline, validate against the connected repository, then push approved changes
to the default branch. Inspect the application for sync errors.
`enabled: false` keeps a trigger inactive. Validation alone never starts a run.

* [Supported repositories](/docs/factory/repositories)
* [CLI](/docs/factory/cli)


# Supported repositories

URL: https://docs.usestitch.ai/docs/factory/repositories



GitHub is the supported repository provider. Custom webhooks add external events;
they do not add another repository provider.

## Connect [#connect]

Install the Stitch GitHub App for the target repositories from the application.
Select the intended organization. Run `stitch repositories list` and confirm `active: true`.
Stitch reads configuration from each repository's default branch.

## Repository output [#repository-output]

The CLI returns a `repositories` array. Use `id` for full validation, `fullName` to match
the checkout's owner/repo, `defaultBranch` for deployment, and `active` to verify access.
Do not assume login grants access to a repository.

```sh
stitch repositories list
stitch validate --repository <id>
```

## Schema [#schema]

Repositories are connected in the application, not declared in YAML.
[Factory schema](/schema/factory.json) defines the configuration read from each repository.
If app installation access is removed, resolve access before validating or pushing.


# Getting Started

URL: https://docs.usestitch.ai/docs/getting-started



Follow these steps in order. Start from the current example; do not design a new workflow first.

## 1. Connect and authenticate [#1-connect-and-authenticate]

Ask the user to [sign in](https://app.usestitch.ai/login), select the intended organization,
and [connect the repository](https://app.usestitch.ai/repositories).

```sh
npm install -g @usestitch/cli
stitch auth login
stitch auth whoami
stitch repositories list
git rev-parse --show-toplevel
git remote -v
```

Node.js 24+ is required. Alternatively use `bunx @usestitch/cli` or `npx @usestitch/cli`.
For another deployment, set `FACTORY_URL` to its HTTPS origin.
Give the user the login result's `verificationUrl` and `userCode`; wait for `authenticated`.
`whoami` must return the intended non-null `organizationId`.
Match the checkout's GitHub owner/repo to an entry with `active: true`.
Save its `id` and `defaultBranch`. Stop if access or the checkout cannot be verified.

## 2. Download the current example [#2-download-the-current-example]

At the verified repository root, read repository instructions and download the
[current starter](/examples/autonomous-delivery.yaml) to `stitch-factory.yaml`.
Preserve it byte-for-byte during this step. Stop if the download fails.
Ask before replacing an existing file. Do not reconstruct the example from memory.

## 3. Explain and agree on changes [#3-explain-and-agree-on-changes]

Read the downloaded file. It triages issues, implements bug/enhancement/chore labels,
reviews newly opened non-draft pull requests for over-engineering, and fixes feedback
from `work_needed` labels or human change-request reviews. It does not review every push.
Explain its run limits, OpenCode harnesses, BYOK Vercel sandboxes, and disabled triggers.

Inspect available repository skills and read relevant instructions. Suggest only skills
you found and explain where they help. Ask whether to keep or change the workflow.
Make only agreed changes; do not redesign it first.

Check the required `build`/`review` agents, `code-review` skill, and GitHub labels.
The starter does not create them. Ask how to resolve missing dependencies.
Replace the Vercel team/project placeholders. Keep triggers disabled until prerequisites
are ready and activation is approved.

## 4. Add secrets privately [#4-add-secrets-privately]

```sh
stitch secrets list
stitch secrets add OPENCODE_API_KEY
stitch secrets add VERCEL_TOKEN
stitch secrets list
```

For the unchanged starter, these are the OpenCode API key and Vercel access token.
If authentication changed, use the names now referenced in the file.
Ask the user to enter values in the CLI's hidden prompt in their private terminal.
Reuse existing secrets; ask before replacing them. Confirm all names exist in the active organization.

## 5. Validate [#5-validate]

```sh
stitch validate --dry-run
stitch validate --repository <connected-repository-id>
```

Resolve missing dependencies and placeholders first. Fix reported errors with agreement.
Validation does not apply configuration or test provider credentials.

## 6. Approve and push [#6-approve-and-push]

Show the final changes. Ask for permission to commit and push, and separately to activate.
If approved, enable only the intended triggers and validate again. Commit only agreed files.
Stitch reads the default branch: another branch must be merged before configuration applies.
Verify the applied state in the [application](https://app.usestitch.ai/repositories),
or report verification as pending. There is no CLI `apply` or startup command.

## Schema [#schema]

[Factory JSON Schema](/schema/factory.json). See [CLI validation](/docs/factory/cli).


# General

URL: https://docs.usestitch.ai/docs



Stitch reads `stitch-factory.yaml` from a connected repository's default branch.
A factory binds **triggers** (when), **harnesses** (agent), and **sandboxes** (compute).

## Start here [#start-here]

* [Getting Started](/docs/getting-started): connect a repository and validate the starter.
* [Factory](/docs/factory): configuration contract and CLI.
* [Resources](/docs/resources): harnesses, sandboxes, and managed secrets.
* [Triggers](/docs/triggers): events, filters, and admission guards.

## Agent interface [#agent-interface]

| Resource                                     | Purpose                                        |
| -------------------------------------------- | ---------------------------------------------- |
| [/llms.txt](/llms.txt)                       | Page index                                     |
| [/llms-full.txt](/llms-full.txt)             | All documentation as Markdown                  |
| `/docs/<page>.md`                            | One page as Markdown; root is `/docs/index.md` |
| [/schema/factory.json](/schema/factory.json) | Hosted factory input schema                    |

Every page has a **Copy Markdown** action. Schema links describe input shapes;
`stitch validate` also checks cross-field rules and repository references.

## Safety contract [#safety-contract]

Ask before replacing files, changing workflows, adding secrets, enabling triggers, or pushing.
Never put credentials in chat, YAML, command arguments, or logs.
Validation is read-only. A push to an unmerged branch does not apply configuration.


# Supported harnesses

URL: https://docs.usestitch.ai/docs/resources/harnesses



## Supported types [#supported-types]

| `type`        | Runtime     |
| ------------- | ----------- |
| `opencode`    | OpenCode    |
| `claude_code` | Claude Code |
| `codex`       | Codex       |
| `antigravity` | Antigravity |

Choose a supported `version`, model, and model-compatible authentication method from the schema.
Set each trigger's `agentId` to an agent available to that runtime and repository.

## Schema [#schema]

[Harnesses JSON Schema](/schema/harnesses.json): the factory's `harnesses` array.
Authentication entries use `method` and `secretName`. Model/auth compatibility also needs CLI validation.

```yaml
harnesses:
  - key: coding-agent
    name: Coding agent
    type: opencode
    version: 1.18.30
    model: openai/gpt-5.4
    auth:
      - method: openai_api_key
        secretName: OPENAI_API_KEY
```

Secret names must exist in the active organization. Do not invent models, versions, or auth methods.
Use the schema and `stitch validate` to check the selected combination.


# Resources

URL: https://docs.usestitch.ai/docs/resources



* [Harnesses](/docs/resources/harnesses): agent runtime, model, and authentication.
* [Sandboxes](/docs/resources/sandboxes): compute and setup.
* [Secrets](/docs/resources/secrets): organization-scoped credentials.

Harnesses and sandboxes live in the factory file. Triggers refer to their local `key`.
Secrets live in the active organization; configuration uses names, never values.

## Schemas [#schemas]

[Harnesses](/schema/harnesses.json) · [Sandboxes](/schema/sandboxes.json) ·
[Environment bindings](/schema/environment.json) · [Managed secret input](/schema/secrets.json)


# Supported sandboxes

URL: https://docs.usestitch.ai/docs/resources/sandboxes



## Availability [#availability]

| Provider                            | Status                                    |
| ----------------------------------- | ----------------------------------------- |
| `vercel` with `auth.mode: byok`     | Available for hosted runs                 |
| `vercel` with `auth.mode: platform` | Disabled                                  |
| `docker`                            | Local-only; rejected by hosted validation |
| `aws-fargate`                       | Disabled                                  |

## Schema [#schema]

[Hosted sandboxes JSON Schema](/schema/sandboxes.json): the factory's `sandboxes` array.
Only available hosted options appear in this schema.

```yaml
sandboxes:
  - key: workspace
    name: Workspace
    provider: vercel
    auth:
      mode: byok
      teamId: REPLACE_WITH_YOUR_TEAM_ID
      projectId: REPLACE_WITH_YOUR_PROJECT_ID
      tokenSecretName: VERCEL_TOKEN
    resources:
      vcpus: 4
    timeoutMs: 1800000
```

Replace identifiers before full validation. Store the access token as a managed secret.
Optional setup scripts and timeouts must satisfy the schema and cross-field validation.


# Secrets

URL: https://docs.usestitch.ai/docs/resources/secrets



Managed secrets belong to the active organization. Harness auth, sandbox auth, and
environment bindings reference secret names.

```sh
stitch secrets list
stitch secrets add OPENAI_API_KEY
```

The user must enter the value in their private terminal's hidden prompt.
Never request values in chat, print them, put them in YAML, or pass them as command arguments.
Ask before replacing or deleting existing secrets.

## Schema [#schema]

[Managed secret input](/schema/secrets.json) · [Environment bindings](/schema/environment.json)

Names contain letters, numbers, underscores, or hyphens (1–64 characters).
Values are non-empty and at most 8192 characters. Descriptions are optional.
The input schema describes creation, not a safe output format; never include its `value` in agent logs.

```yaml
execution:
  environmentVariables:
    - key: SERVICE_TOKEN
      source: managed
      secretName: SERVICE_TOKEN
      targets: [harness]
```

Use `targets: [setup]` for setup only, or `[setup, harness]` for both.
Confirm names with `stitch secrets list` before full validation.


# Check runs

URL: https://docs.usestitch.ai/docs/triggers/github/check_run



## Schema [#schema]

[Check run JSON Schema](/schema/github-check_run.json)

`eventType: check_run`. Actions: `completed`, `rerequested`.

```yaml
key: fix-check
name: Fix failed check
provider: github
eventType: check_run
actions: [completed]
harness: coding-agent
sandbox: workspace
agentId: build
initialPrompt: Inspect the failed check and fix the cause.
conclusions: [failure]
enabled: false
```

## Filters [#filters]

Supported: `conclusions`, `checkNames`, `checkApps`, `ignoreBots`, `actorLogins`.
`completed` requires conclusions. A conclusions filter accepts only completed actions;
put `rerequested` in a separate trigger.
Conclusions: `success`, `failure`, `neutral`, `cancelled`, `timed_out`, `action_required`,
`stale`, `skipped`, `startup_failure`.
Branch and PR label filters are unsupported.
See [shared matching rules](/docs/triggers/github#filters).

## Guards [#guards]

Scopes: `repository`, `commit`, `event`; `delivery` for `deduplicate`.
`subject` is unsupported even when a check is associated with a PR.
See [guard types](/docs/triggers#guards).


# GitHub triggers

URL: https://docs.usestitch.ai/docs/triggers/github



Connect the repository through the Stitch GitHub App. Set `provider: github`.
Select one `eventType` and one or more supported `actions` per trigger.

## Event types [#event-types]

| Event                                                                            | Use                               |
| -------------------------------------------------------------------------------- | --------------------------------- |
| [issues](/docs/triggers/github/issues)                                           | Issue lifecycle and labels        |
| [pull_request](/docs/triggers/github/pull_request)                               | PR lifecycle and updates          |
| [issue_comment](/docs/triggers/github/issue_comment)                             | Issue or PR conversation comments |
| [pull_request_review](/docs/triggers/github/pull_request_review)                 | Review submissions and state      |
| [pull_request_review_comment](/docs/triggers/github/pull_request_review_comment) | Inline review comments            |
| [pull_request_review_thread](/docs/triggers/github/pull_request_review_thread)   | Resolve or reopen review threads  |
| [push](/docs/triggers/github/push)                                               | Repository pushes                 |
| [check_run](/docs/triggers/github/check_run)                                     | Check completion or rerequest     |
| [workflow_run](/docs/triggers/github/workflow_run)                               | Workflow completion or request    |
| [release](/docs/triggers/github/release)                                         | Release creation or publication   |

## Schema [#schema]

[Triggers schema](/schema/triggers.json). Each event page links its own input schema.
Examples on event pages are entries in `triggers`, not complete factory files.
Create the referenced harness and sandbox first. JSON Schema describes field shapes;
`stitch validate` enforces event/filter compatibility.

## Filters [#filters]

Filter lists generally allow at most 50 entries. `actions` needs 1–20 unique entries.
Supported filters vary by event; do not copy an unsupported field from another page.

| Field                              | Matching                                                                       |
| ---------------------------------- | ------------------------------------------------------------------------------ |
| `labels`                           | Repository label names resolved during full validation                         |
| `labelOperator`                    | `has_any` (default), `has_all`, `has_none`, `is_empty`                         |
| `labelScope`                       | `current` (default) or `changed`                                               |
| `branches`                         | Any available branch; patterns support `*`, `**`, `?`                          |
| `sourceBranches`, `targetBranches` | PR head/base branches; same patterns                                           |
| `pathPrefixes`                     | Repository-relative file/directory prefixes; no wildcards or `.`/`..` segments |
| `commentKeywords`                  | Case-insensitive substring match; any selected keyword                         |
| `mentionedLogins`                  | Case-insensitive match against mentioned GitHub logins                         |
| `commands`                         | Exact first word after leading whitespace, such as `/review`                   |
| `actorLogins`                      | Case-insensitive event sender login match                                      |
| `authorAssociations`               | GitHub association values, such as `OWNER`, `MEMBER`, `COLLABORATOR`           |
| `ignoreBots`                       | Exclude bot senders; defaults to `false`                                       |
| `ignoreDrafts`                     | Exclude draft PRs; defaults to `false`                                         |

Changed-label scope accepts only labeled/unlabeled actions and needs labels.
`is_empty` forbids a labels list; `has_all`/`has_none` require one.
Changed-label `has_all` cannot select multiple labels.
Comment matching requires selectors or `matchAllComments: true`, never both.

## Guards [#guards]

Use the scopes on each event page plus `delivery` for `deduplicate`.
Check guard type restrictions in [Triggers](/docs/triggers#guards).
Subject/commit scopes are invalid when the event does not support those identities.


# Issue / PR comments

URL: https://docs.usestitch.ai/docs/triggers/github/issue_comment



## Schema [#schema]

[Issue comment JSON Schema](/schema/github-issue_comment.json)

`eventType: issue_comment`. Actions: `created`, `edited`.

```yaml
key: comment-command
name: Handle review command
provider: github
eventType: issue_comment
actions: [created]
harness: coding-agent
sandbox: workspace
agentId: build
initialPrompt: Handle the requested review.
commands: [/review]
commentScopes: [pull_request]
enabled: false
```

## Filters [#filters]

Supported: `labels`, `labelOperator`, `labelScope`, `commentKeywords`, `matchAllComments`,
`mentionedLogins`, `commands`, `commentScopes`, `branches`, `sourceBranches`,
`targetBranches`, `ignoreDrafts`, `ignoreBots`, `actorLogins`, `authorAssociations`.
`commentScopes` defaults to `[issue, pull_request]`.
PR branch/draft filters require `commentScopes: [pull_request]`.
Select keywords, mentions, or commands, or set `matchAllComments: true`; do not combine both modes.
See [shared matching rules](/docs/triggers/github#filters).

## Guards [#guards]

Scopes: `repository`, `subject`, `event`; `delivery` for `deduplicate`.
`subject` identifies the issue or PR conversation. `commit` is unsupported, even for PR comments.
See [guard types](/docs/triggers#guards).


# Issues

URL: https://docs.usestitch.ai/docs/triggers/github/issues



## Schema [#schema]

[Issues JSON Schema](/schema/github-issues.json)

`eventType: issues`. Actions: `opened`, `edited`, `closed`, `reopened`, `labeled`, `unlabeled`.

```yaml
key: triage
name: Triage issue
provider: github
eventType: issues
actions: [opened]
harness: coding-agent
sandbox: workspace
agentId: build
initialPrompt: Triage this issue and report the result.
enabled: false
```

## Filters [#filters]

Supported: `labels`, `labelOperator`, `labelScope`, `ignoreBots`, `actorLogins`.
For `labeled` with `has_any`/`has_all`, supply labels. Use `labelScope: changed` to
match the label in the event instead of all current issue labels.
See [shared matching rules](/docs/triggers/github#filters).

## Guards [#guards]

Scopes: `repository`, `subject`, `event`; `delivery` for `deduplicate`.
Use `subject` to cap admissions for one issue. `commit` is unsupported.
See [guard types](/docs/triggers#guards).


# Pull requests

URL: https://docs.usestitch.ai/docs/triggers/github/pull_request



## Schema [#schema]

[Pull request JSON Schema](/schema/github-pull_request.json)

`eventType: pull_request`. Actions: `opened`, `edited`, `closed`, `reopened`,
`synchronize`, `labeled`, `unlabeled`, `ready_for_review`.

```yaml
key: review-pr
name: Review PR
provider: github
eventType: pull_request
actions: [opened, synchronize]
harness: coding-agent
sandbox: workspace
agentId: review
initialPrompt: Review the pull request for actionable defects.
ignoreDrafts: true
ignoreBots: true
enabled: false
```

## Filters [#filters]

Supported: `labels`, `labelOperator`, `labelScope`, `branches`, `sourceBranches`,
`targetBranches`, `pathPrefixes`, `merged`, `ignoreBots`, `ignoreDrafts`, `actorLogins`.
`merged` requires only `closed` actions. Split other actions into a separate trigger.
`labeled` with `has_any`/`has_all` requires labels.
See [shared matching rules](/docs/triggers/github#filters).

## Guards [#guards]

Scopes: `repository`, `subject`, `commit`, `event`; `delivery` for `deduplicate`.
Use `subject` for a per-PR cap or `commit` for a per-revision cap.
See [guard types](/docs/triggers#guards).


# Pull request reviews

URL: https://docs.usestitch.ai/docs/triggers/github/pull_request_review



## Schema [#schema]

[PR review JSON Schema](/schema/github-pull_request_review.json)

`eventType: pull_request_review`. Actions: `submitted`, `edited`, `dismissed`.

```yaml
key: requested-changes
name: Address requested changes
provider: github
eventType: pull_request_review
actions: [submitted]
harness: coding-agent
sandbox: workspace
agentId: build
initialPrompt: Address the actionable review feedback.
reviewStates: [changes_requested]
ignoreBots: true
enabled: false
```

## Filters [#filters]

Supported: `labels`, `labelOperator`, `labelScope`, `mentionedLogins`, `branches`,
`sourceBranches`, `targetBranches`, `reviewStates`, `ignoreBots`, `ignoreDrafts`, `actorLogins`.
Review states: `approved`, `changes_requested`, `commented`, `dismissed`.
Keyword and slash-command filters are not supported for this event.
See [shared matching rules](/docs/triggers/github#filters).

## Guards [#guards]

Scopes: `repository`, `subject`, `commit`, `event`; `delivery` for `deduplicate`.
Use `subject` for the PR or `commit` for its revision.
See [guard types](/docs/triggers#guards).


# Pull request review comments

URL: https://docs.usestitch.ai/docs/triggers/github/pull_request_review_comment



## Schema [#schema]

[Review comment JSON Schema](/schema/github-pull_request_review_comment.json)

`eventType: pull_request_review_comment`. Actions: `created`, `edited`.

```yaml
key: inline-command
name: Address inline command
provider: github
eventType: pull_request_review_comment
actions: [created]
harness: coding-agent
sandbox: workspace
agentId: build
initialPrompt: Address the requested inline change.
commands: [/fix]
enabled: false
```

## Filters [#filters]

Supported: `labels`, `labelOperator`, `labelScope`, `commentKeywords`, `matchAllComments`,
`mentionedLogins`, `commands`, `branches`, `sourceBranches`, `targetBranches`,
`ignoreBots`, `ignoreDrafts`, `actorLogins`, `authorAssociations`.
Select keywords, mentions, or commands, or set `matchAllComments: true`; not both.
These are inline comments, not the PR's conversation comments.
See [shared matching rules](/docs/triggers/github#filters).

## Guards [#guards]

Scopes: `repository`, `subject`, `commit`, `event`; `delivery` for `deduplicate`.
`subject` identifies the PR; use `event` to limit a specific comment identity.
See [guard types](/docs/triggers#guards).


# Pull request review threads

URL: https://docs.usestitch.ai/docs/triggers/github/pull_request_review_thread



## Schema [#schema]

[Review thread JSON Schema](/schema/github-pull_request_review_thread.json)

`eventType: pull_request_review_thread`. Actions: `resolved`, `unresolved`.

```yaml
key: reopen-thread
name: Address reopened thread
provider: github
eventType: pull_request_review_thread
actions: [unresolved]
harness: coding-agent
sandbox: workspace
agentId: build
initialPrompt: Inspect and address the reopened review thread.
matchAllComments: true
enabled: false
```

## Filters [#filters]

Supported: `labels`, `labelOperator`, `labelScope`, `commentKeywords`, `matchAllComments`,
`commands`, `branches`, `sourceBranches`, `targetBranches`, `ignoreBots`, `ignoreDrafts`, `actorLogins`.
Select keywords or commands, or set `matchAllComments: true`; not both.
Mention and author-association filters are unsupported.
See [shared matching rules](/docs/triggers/github#filters).

## Guards [#guards]

Scopes: `repository`, `subject`, `commit`, `event`; `delivery` for `deduplicate`.
`subject` identifies the PR; `event` distinguishes the thread event identity.
See [guard types](/docs/triggers#guards).


# Pushes

URL: https://docs.usestitch.ai/docs/triggers/github/push



## Schema [#schema]

[Push JSON Schema](/schema/github-push.json)

`eventType: push`. Action: `pushed` (Stitch's normalized action).

```yaml
key: verify-push
name: Verify main push
provider: github
eventType: push
actions: [pushed]
harness: coding-agent
sandbox: workspace
agentId: build
initialPrompt: Verify the pushed changes.
branches: [main]
pushBranchesOnly: true
enabled: false
```

## Filters [#filters]

Supported: `branches`, `pathPrefixes`, `pushBranchesOnly`, `ignoreBots`, `actorLogins`.
`pushBranchesOnly` restricts pushes to branch updates. No PR source/target branch scopes.
Paths are relative prefixes, not glob patterns.
See [shared matching rules](/docs/triggers/github#filters).

## Guards [#guards]

Scopes: `repository`, `commit`, `event`; `delivery` for `deduplicate`.
There is no issue/PR `subject`. Missing commit identity causes commit-scoped admission to be skipped.
See [guard types](/docs/triggers#guards).


# Releases

URL: https://docs.usestitch.ai/docs/triggers/github/release



## Schema [#schema]

[Release JSON Schema](/schema/github-release.json)

`eventType: release`. Actions: `published`, `created`, `prereleased`.

```yaml
key: release-notes
name: Inspect published release
provider: github
eventType: release
actions: [published]
harness: coding-agent
sandbox: workspace
agentId: build
initialPrompt: Inspect the release and summarize follow-up work.
releaseKinds: [stable]
releaseTags: [v*]
enabled: false
```

## Filters [#filters]

Supported: `releaseTags`, `releaseKinds`, `ignoreBots`, `actorLogins`.
Tags support `*`, `**`, `?`. Kinds: `stable`, `prerelease`, `draft`.
Branch, label, and path filters are unsupported.
See [shared matching rules](/docs/triggers/github#filters).

## Guards [#guards]

Scopes: `repository`, `event`; `delivery` for `deduplicate`.
Neither `subject` nor `commit` is supported. Use `event` for a release identity cap.
See [guard types](/docs/triggers#guards).


# Workflow runs

URL: https://docs.usestitch.ai/docs/triggers/github/workflow_run



## Schema [#schema]

[Workflow run JSON Schema](/schema/github-workflow_run.json)

`eventType: workflow_run`. Actions: `completed`, `requested`.

```yaml
key: fix-workflow
name: Fix failed workflow
provider: github
eventType: workflow_run
actions: [completed]
harness: coding-agent
sandbox: workspace
agentId: build
initialPrompt: Inspect the failed workflow and fix the cause.
conclusions: [failure]
workflows: [.github/workflows/ci.yml]
enabled: false
```

## Filters [#filters]

Supported: `branches`, `conclusions`, `workflows`, `ignoreBots`, `actorLogins`.
Workflow selectors are paths such as `.github/workflows/ci.yml` or `.yaml`, not display names.
`completed` requires conclusions. A conclusions filter accepts only completed actions;
put `requested` in a separate trigger.
Conclusions: `success`, `failure`, `neutral`, `cancelled`, `timed_out`, `action_required`,
`stale`, `skipped`, `startup_failure`.
See [shared matching rules](/docs/triggers/github#filters).

## Guards [#guards]

Scopes: `repository`, `commit`, `event`; `delivery` for `deduplicate`.
PR `subject` and source/target branch scopes are unsupported.
See [guard types](/docs/triggers#guards).


# Triggers

URL: https://docs.usestitch.ai/docs/triggers



An enabled trigger binds one harness, one sandbox, an `agentId`, and an `initialPrompt`.
GitHub or webhook events can start runs only after filters and admission guards pass.

## Schema [#schema]

[Triggers JSON Schema](/schema/triggers.json) · [Guard JSON Schema](/schema/guards.json)

| Field                | Contract                                                           |
| -------------------- | ------------------------------------------------------------------ |
| `key`, `name`        | Unique local key and display name                                  |
| `provider`           | `github` or `webhook`                                              |
| `harness`, `sandbox` | Existing local declaration keys                                    |
| `agentId`            | Non-empty kebab-case runtime agent ID                              |
| `initialPrompt`      | Non-empty instruction; at most 64 KiB                              |
| `enabled`            | Defaults to `true`; explicitly disable during setup                |
| `guards`             | At most 10; each guard type appears at most once; defaults to `[]` |

## Filters [#filters]

Filters inspect the incoming event, not prior runs. All configured filter conditions must pass.
For GitHub, select `eventType` and `actions`, then use only the fields supported by that event.
For webhooks, select `events` and a nested `payloadFilter`.
Unsupported combinations fail validation. Empty filters generally add no restriction,
but comment events need a comment selector or `matchAllComments`.

## Guards [#guards]

Guards inspect prior admissions or active runs. They are evaluated with run reservation.
They are not content filters, and they do not change the agent prompt.

| `type`            | Effect                              | Parameters                                          |
| ----------------- | ----------------------------------- | --------------------------------------------------- |
| `max_occurrences` | Limit admissions                    | `limit` 1–100 (default 3); optional `windowSeconds` |
| `cooldown`        | Require a gap between admissions    | Required positive `seconds`                         |
| `max_concurrent`  | Limit active runs                   | Required `limit` 1–100                              |
| `deduplicate`     | Skip previously admitted identities | Optional `windowSeconds`                            |

All guards accept `enabled` (default `true`) and a `scope`.
Time windows are positive integer seconds, at most 31536000.
Without a window, occurrence/deduplication guards consider all matching admission history.

| Scope        | Identity                                            |
| ------------ | --------------------------------------------------- |
| `repository` | Repository, within this trigger's admission history |
| `subject`    | Issue or pull request                               |
| `commit`     | Commit SHA                                          |
| `event`      | Event type, action, and event ID                    |
| `delivery`   | Delivery ID; `deduplicate` only                     |

`deduplicate` supports delivery/subject/commit/event, not repository.
Other guard types support repository/subject/commit/event, not delivery.
The event must also supply the selected identity. A missing identity skips admission;
it does not silently broaden the guard scope.

```yaml
guards:
  - type: max_concurrent
    scope: repository
    limit: 1
  - type: deduplicate
    scope: delivery
```

* [GitHub triggers](/docs/triggers/github)
* [Webhook triggers](/docs/triggers/webhook)


# Webhook triggers

URL: https://docs.usestitch.ai/docs/triggers/webhook



Set `provider: webhook`. A webhook still runs against a connected repository.
Inspect its endpoint with `stitch webhooks get <factory-id>`.

## Schema [#schema]

[Webhook trigger JSON Schema](/schema/webhook.json) · [Factory schema](/schema/factory.json)

```yaml
key: external-bug
name: Handle external bug
provider: webhook
harness: coding-agent
sandbox: workspace
agentId: build
initialPrompt: Investigate the incoming bug report.
events: [ticket.created]
payloadFilter:
  priority: [high, urgent]
guards:
  - type: deduplicate
    scope: delivery
enabled: false
```

Send a JSON object with `meta` and `data`. `meta.id` and `meta.event` are required
non-empty strings (at most 128 characters). Reuse the same ID on retries.
`data` must be a JSON object.

```json
{
  "meta": { "id": "ticket-123-created", "event": "ticket.created" },
  "data": { "priority": "high", "title": "Checkout fails" }
}
```

```sh
stitch webhooks send <factory-id> --event ticket.created --idempotency-key ticket-123-created --data-file payload.json
```

For this command, `payload.json` contains only the `data` object; the CLI builds `meta`.
For direct HTTP delivery, send the full envelope to the returned endpoint and keep
its webhook credential private. Key rotation invalidates the old key immediately.

## Filters [#filters]

`events` allows at most 32 names; an empty list accepts any event name.
`payloadFilter` matches `data`, not `meta`. Nested fields are combined with AND.
Each value list is an OR match. Supported operators are `in`, `not_in`, and `exists`.

```yaml
payloadFilter:
  ticket:
    priority:
      in: [high, urgent]
    archived:
      not_in: [true]
    assignee:
      exists: true
```

Lists contain 1–32 scalar values (string, number, boolean, or null).
`exists` checks field presence, including null. `not_in` also passes for missing fields
unless `exists: true` is set. Nested array objects match if any element matches.
Filters are limited to 64 leaf rules and depth 10.
The JSON Schema exposes a payload object; full validation also checks the recursive filter grammar.

## Guards [#guards]

Use `repository` for `max_occurrences`, `cooldown`, and `max_concurrent`.
Use `delivery` for `deduplicate`. Subject, commit, and event scopes are rejected.
Stable `meta.id` plus delivery deduplication prevents repeated admission on retries.
See [guard types and limits](/docs/triggers#guards).