# FactoryTrigger

Something that starts a Software Factory workflow: a GitHub webhook event, a finding, an issue label, a kanban card move, a firewall sighting.

Something that starts a Software Factory workflow: a GitHub webhook event, a finding, an issue label, a kanban card move, a firewall sighting, or a person pressing Run. A trigger is a trigger node in the workflow's graph whose id is metadata.name (at most 40 characters), so applying one saves and publishes a new version of the workflow, the same as adding the trigger in the workflow builder; the workflow must be published and must not hold an unpublished draft. A trigger node the workflow already has under that id is adopted. A schedule is a FactorySchedule. Conditions are typed fields: the console takes no expression for a trigger. A trigger is on while its workflow is on. Removing the document removes the node and publishes the workflow again.

| | |
|---|---|
| `apiVersion` | `vulnetix.com/v1` |
| `kind` | `FactoryTrigger` |
| Group | [Factory](/platform-iac/kinds/catalogue.md#factory) |
| Status | **Served.** The [config engine](/platform-iac/reference/engine.md) plans and applies it. |
| Objects per tenant | many, keyed by `metadata.name` |
| Token and role | An owner, or a service account with the developer role (its ApiKey), or an Authentik access token for either. A member is refused with HTTP 403. See [Credentials for automation](/platform-iac/reference/config-api.md#credentials-for-automation). |
| Applied after | [`FactoryWorkflow`](/platform-iac/kinds/factory-workflow.md) (deleted before them) |
| Terraform resource | [`vulnetix_factory_trigger`](/platform-iac/terraform/resources.md#vulnetix_factory_trigger), imported by name (see [Terraform and OpenTofu](#terraform-and-opentofu)) |
| CLI | [`vulnetix config apply`](/platform-iac/cli/apply.md), CLI v3.168.0 and later. |
| Pinned schema | [`v1.19.1/FactoryTrigger.schema.json`](https://github.com/Vulnesis/config-schemas/releases/download/v1.19.1/FactoryTrigger.schema.json) |
| Newest schema | [`latest/FactoryTrigger.schema.json`](https://github.com/Vulnesis/config-schemas/releases/latest/download/FactoryTrigger.schema.json) |
| First released in | [`v1.6.0`](https://github.com/Vulnesis/config-schemas/releases/tag/v1.6.0) |
| Print the built-in copy | `vulnetix config schema FactoryTrigger` |

## Minimal

Only the fields the kind requires. From `examples/FactoryTrigger/minimal.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/FactoryTrigger.schema.json
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: run-now
spec:
  workflow: security-patch-train
  type: manual
  startAt: [scan]
```

**HCL** (resource `vulnetix_factory_trigger`)

```hcl
# Only the arguments the kind requires. From config-schemas examples/FactoryTrigger/minimal.yaml.

resource "vulnetix_factory_trigger" "run_now" {
  name     = "run-now"
  start_at = ["scan"]
  type     = "manual"
  workflow = "security-patch-train"
}
```

Every field that has a schema default, set to that default: [`terraform/factory_trigger.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/factory_trigger.tf) and [`yaml/FactoryTrigger.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/FactoryTrigger.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/FactoryTrigger.schema.json
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: run-now
spec:
  workflow: security-patch-train
  type: manual
  startAt: [scan]
EOF
```

## Advanced

Every field the kind supports, with a `when` expression where it takes one. From `examples/FactoryTrigger/advanced.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/FactoryTrigger.schema.json
# Each trigger type, and each webhook condition with an event it applies to.
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: pr-opened
  labels:
    team: appsec
spec:
  workflow: security-patch-train
  type: webhook
  title: Pull request opened or updated
  startAt: [scan]
  priority: 2
  overlap: cancel_previous
  event: pull_request
  debounceSeconds: 60
  maxRunsPerHour: 30
  conditions:
    actions: [opened, synchronize, reopened]
    baseBranch: ["@default", release/*]
    headBranch: [feature/**]
    labels:
      any: [security]
      all: [ready]
    authorType: user
    authors:
      allow: [alice, bob]
      deny: [dependabot*]
    draft: exclude
    origin: same_repo
    subject: pr
    properties:
      team: [payments]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: push-default-branch
spec:
  workflow: security-patch-train
  type: webhook
  startAt: [scan]
  event: push
  ref: default
  conditions:
    baseBranch: ["@default"]
    paths: [package.json, "**/go.mod"]
    pathsIgnore: [docs/**]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: ci-failed
spec:
  workflow: security-patch-train
  type: webhook
  startAt: [scan]
  event: check_run.completed
  conditions:
    conclusion: [failure, timed_out]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: dependabot-critical
spec:
  workflow: security-patch-train
  type: webhook
  startAt: [scan]
  event: dependabot_alert.created
  conditions:
    severity: [critical, high]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: production-deploy
spec:
  workflow: security-patch-train
  type: webhook
  startAt: [scan]
  event: deployment_status
  conditions:
    environment: [production]
    conclusion: [failure]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: image-published
spec:
  workflow: security-patch-train
  type: webhook
  startAt: [scan]
  event: registry_package.published
  conditions:
    packageType: [container]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: changes-requested
spec:
  workflow: security-patch-train
  type: webhook
  startAt: [scan]
  event: pull_request_review.submitted
  conditions:
    reviewState: [changes_requested]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: security-label
spec:
  workflow: security-patch-train
  type: label
  startAt: [scan]
  label: belai:security
  debounceSeconds: 30
  maxRunsPerHour: 20
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: critical-finding
spec:
  workflow: security-patch-train
  type: finding
  startAt: [scan]
  severity: [critical, high]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: card-to-ready
spec:
  workflow: security-patch-train
  type: kanban
  startAt: [scan]
  fromList: backlog
  toList: ready
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: new-package
spec:
  workflow: security-patch-train
  type: firewall
  startAt: [scan]
  source: package-firewall
  events: [package.first_seen, package.blocked]
  newTo: org
  decision: [block]
  ecosystems: [npm, pypi]
  ticketRepo: acme/security-reviews
  maxRunsPerHour: 10
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: new-mcp-server
spec:
  workflow: security-patch-train
  type: firewall
  startAt: [scan]
  source: ai-firewall
  event: ai.capability_first_seen
  kinds: [mcp_server, skill]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: sandbox-egress
spec:
  workflow: security-patch-train
  type: firewall
  startAt: [scan]
  source: egress
  event: egress.host_first_seen
  sandboxes: [build-sandbox]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: guardian-dns
spec:
  workflow: security-patch-train
  type: firewall
  startAt: [scan]
  source: siem
  event: siem.fired
  categories: [dns]
  providers: [aws]
  tables: [dns_events]
  triggers: [suspicious-dns]
```

**HCL** (resource `vulnetix_factory_trigger`)

```hcl
# Every argument the kind supports. From config-schemas examples/FactoryTrigger/advanced.yaml.

resource "vulnetix_factory_trigger" "pr_opened" {
  name = "pr-opened"
  conditions = {
    actions     = ["opened", "synchronize", "reopened"]
    author_type = "user"
    authors = {
      allow = ["alice", "bob"]
      deny  = ["dependabot*"]
    }
    base_branch = ["@default", "release/*"]
    draft       = "exclude"
    head_branch = ["feature/**"]
    labels = {
      all = ["ready"]
      any = ["security"]
    }
    origin = "same_repo"
    properties = jsonencode({
      team = ["payments"]
    })
    subject = "pr"
  }
  debounce_seconds  = 60
  event             = "pull_request"
  max_runs_per_hour = 30
  overlap           = "cancel_previous"
  priority          = 2
  start_at          = ["scan"]
  title             = "Pull request opened or updated"
  type              = "webhook"
  workflow          = "security-patch-train"
  labels = {
    team = "appsec"
  }
}

resource "vulnetix_factory_trigger" "push_default_branch" {
  name = "push-default-branch"
  conditions = {
    base_branch  = ["@default"]
    paths        = ["package.json", "**/go.mod"]
    paths_ignore = ["docs/**"]
  }
  event    = "push"
  ref      = "default"
  start_at = ["scan"]
  type     = "webhook"
  workflow = "security-patch-train"
}

resource "vulnetix_factory_trigger" "ci_failed" {
  name = "ci-failed"
  conditions = {
    conclusion = ["failure", "timed_out"]
  }
  event    = "check_run.completed"
  start_at = ["scan"]
  type     = "webhook"
  workflow = "security-patch-train"
}

resource "vulnetix_factory_trigger" "dependabot_critical" {
  name = "dependabot-critical"
  conditions = {
    severity = ["critical", "high"]
  }
  event    = "dependabot_alert.created"
  start_at = ["scan"]
  type     = "webhook"
  workflow = "security-patch-train"
}

resource "vulnetix_factory_trigger" "production_deploy" {
  name = "production-deploy"
  conditions = {
    conclusion  = ["failure"]
    environment = ["production"]
  }
  event    = "deployment_status"
  start_at = ["scan"]
  type     = "webhook"
  workflow = "security-patch-train"
}

resource "vulnetix_factory_trigger" "image_published" {
  name = "image-published"
  conditions = {
    package_type = ["container"]
  }
  event    = "registry_package.published"
  start_at = ["scan"]
  type     = "webhook"
  workflow = "security-patch-train"
}

resource "vulnetix_factory_trigger" "changes_requested" {
  name = "changes-requested"
  conditions = {
    review_state = ["changes_requested"]
  }
  event    = "pull_request_review.submitted"
  start_at = ["scan"]
  type     = "webhook"
  workflow = "security-patch-train"
}

resource "vulnetix_factory_trigger" "security_label" {
  name              = "security-label"
  debounce_seconds  = 30
  label             = "belai:security"
  max_runs_per_hour = 20
  start_at          = ["scan"]
  type              = "label"
  workflow          = "security-patch-train"
}

resource "vulnetix_factory_trigger" "critical_finding" {
  name     = "critical-finding"
  severity = ["critical", "high"]
  start_at = ["scan"]
  type     = "finding"
  workflow = "security-patch-train"
}

resource "vulnetix_factory_trigger" "card_to_ready" {
  name      = "card-to-ready"
  from_list = "backlog"
  start_at  = ["scan"]
  to_list   = "ready"
  type      = "kanban"
  workflow  = "security-patch-train"
}

resource "vulnetix_factory_trigger" "new_package" {
  name              = "new-package"
  decision          = ["block"]
  ecosystems        = ["npm", "pypi"]
  events            = ["package.first_seen", "package.blocked"]
  max_runs_per_hour = 10
  new_to            = "org"
  source            = "package-firewall"
  start_at          = ["scan"]
  ticket_repo       = "acme/security-reviews"
  type              = "firewall"
  workflow          = "security-patch-train"
}

resource "vulnetix_factory_trigger" "new_mcp_server" {
  name     = "new-mcp-server"
  event    = "ai.capability_first_seen"
  kinds    = ["mcp_server", "skill"]
  source   = "ai-firewall"
  start_at = ["scan"]
  type     = "firewall"
  workflow = "security-patch-train"
}

resource "vulnetix_factory_trigger" "sandbox_egress" {
  name      = "sandbox-egress"
  event     = "egress.host_first_seen"
  sandboxes = ["build-sandbox"]
  source    = "egress"
  start_at  = ["scan"]
  type      = "firewall"
  workflow  = "security-patch-train"
}

resource "vulnetix_factory_trigger" "guardian_dns" {
  name       = "guardian-dns"
  categories = ["dns"]
  event      = "siem.fired"
  providers  = ["aws"]
  source     = "siem"
  start_at   = ["scan"]
  tables     = ["dns_events"]
  triggers   = ["suspicious-dns"]
  type       = "firewall"
  workflow   = "security-patch-train"
}
```

Every field that has a schema default, set to that default: [`terraform/factory_trigger.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/factory_trigger.tf) and [`yaml/FactoryTrigger.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/FactoryTrigger.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/FactoryTrigger.schema.json
# Each trigger type, and each webhook condition with an event it applies to.
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: pr-opened
  labels:
    team: appsec
spec:
  workflow: security-patch-train
  type: webhook
  title: Pull request opened or updated
  startAt: [scan]
  priority: 2
  overlap: cancel_previous
  event: pull_request
  debounceSeconds: 60
  maxRunsPerHour: 30
  conditions:
    actions: [opened, synchronize, reopened]
    baseBranch: ["@default", release/*]
    headBranch: [feature/**]
    labels:
      any: [security]
      all: [ready]
    authorType: user
    authors:
      allow: [alice, bob]
      deny: [dependabot*]
    draft: exclude
    origin: same_repo
    subject: pr
    properties:
      team: [payments]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: push-default-branch
spec:
  workflow: security-patch-train
  type: webhook
  startAt: [scan]
  event: push
  ref: default
  conditions:
    baseBranch: ["@default"]
    paths: [package.json, "**/go.mod"]
    pathsIgnore: [docs/**]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: ci-failed
spec:
  workflow: security-patch-train
  type: webhook
  startAt: [scan]
  event: check_run.completed
  conditions:
    conclusion: [failure, timed_out]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: dependabot-critical
spec:
  workflow: security-patch-train
  type: webhook
  startAt: [scan]
  event: dependabot_alert.created
  conditions:
    severity: [critical, high]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: production-deploy
spec:
  workflow: security-patch-train
  type: webhook
  startAt: [scan]
  event: deployment_status
  conditions:
    environment: [production]
    conclusion: [failure]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: image-published
spec:
  workflow: security-patch-train
  type: webhook
  startAt: [scan]
  event: registry_package.published
  conditions:
    packageType: [container]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: changes-requested
spec:
  workflow: security-patch-train
  type: webhook
  startAt: [scan]
  event: pull_request_review.submitted
  conditions:
    reviewState: [changes_requested]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: security-label
spec:
  workflow: security-patch-train
  type: label
  startAt: [scan]
  label: belai:security
  debounceSeconds: 30
  maxRunsPerHour: 20
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: critical-finding
spec:
  workflow: security-patch-train
  type: finding
  startAt: [scan]
  severity: [critical, high]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: card-to-ready
spec:
  workflow: security-patch-train
  type: kanban
  startAt: [scan]
  fromList: backlog
  toList: ready
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: new-package
spec:
  workflow: security-patch-train
  type: firewall
  startAt: [scan]
  source: package-firewall
  events: [package.first_seen, package.blocked]
  newTo: org
  decision: [block]
  ecosystems: [npm, pypi]
  ticketRepo: acme/security-reviews
  maxRunsPerHour: 10
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: new-mcp-server
spec:
  workflow: security-patch-train
  type: firewall
  startAt: [scan]
  source: ai-firewall
  event: ai.capability_first_seen
  kinds: [mcp_server, skill]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: sandbox-egress
spec:
  workflow: security-patch-train
  type: firewall
  startAt: [scan]
  source: egress
  event: egress.host_first_seen
  sandboxes: [build-sandbox]
---
apiVersion: vulnetix.com/v1
kind: FactoryTrigger
metadata:
  name: guardian-dns
spec:
  workflow: security-patch-train
  type: firewall
  startAt: [scan]
  source: siem
  event: siem.fired
  categories: [dns]
  providers: [aws]
  tables: [dns_events]
  triggers: [suspicious-dns]
EOF
```

## Fields

Paths use dots for nesting and `[]` for the items of a list. **Required** means required whenever the parent object is present. A default is what the server uses when the field is left out.

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| <span id="apiVersion"></span>`apiVersion` | string | yes |  | exactly `vulnetix.com/v1` | The document format version. Every kind in this release is vulnetix.com/v1. |
| <span id="kind"></span>`kind` | string | yes |  | exactly `FactoryTrigger` | Always FactoryTrigger. |
| <span id="metadata"></span>`metadata` | object | yes |  | no other keys |  |
| <span id="metadata-name"></span>`metadata.name` | string | yes |  | pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$` | The object's name, unique per kind within a tenant. It is the natural key: plan, apply, export and the Terraform provider all address an object by kind and name. |
| <span id="metadata-org"></span>`metadata.org` | string | no |  | format `uuid` | The tenant (organization UUID) the document belongs to. When set, plan and apply refuse to run against any other tenant. |
| <span id="metadata-labels"></span>`metadata.labels` | object | no |  | map of string to string (length 0 to 256); keys match `^[a-z0-9]([a-z0-9._/-]{0,61}[a-z0-9])?$` | Free key/value labels. Stored with the object, never interpreted by the server. |
| <span id="metadata-annotations"></span>`metadata.annotations` | object | no |  | map of string to string (length 0 to 4096) | Free key/value notes for people and tools, such as a ticket link. |
| <span id="spec"></span>`spec` | object | yes |  | no other keys |  |
| <span id="spec-workflow"></span>`spec.workflow` | string | yes |  | pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$` | The metadata.name of a FactoryWorkflow: the workflow the trigger starts. |
| <span id="spec-type"></span>`spec.type` | string | yes |  | `webhook`, `finding`, `label`, `kanban`, `manual`, `firewall` | What starts the workflow. webhook: a GitHub delivery to the App (event, conditions). finding: a new finding (severity). label: a label added to an issue or pull request (label). kanban: a card moved on the board (fromList, toList). firewall: a sighting from a firewall, Guardian or the GitHub risk rules (source and its filters). manual: only a person pressing Run. |
| <span id="spec-title"></span>`spec.title` | string | no |  | length 1 to 200 | The trigger node's title in the builder. Left out, the node is titled with metadata.name. |
| <span id="spec-startAt"></span>`spec.startAt` | array of string | yes |  | 1 to any items; items unique; each item: pattern `^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$` | The ids of the steps in the workflow's graph the trigger leads to: one edge from the trigger to each, in this order. |
| <span id="spec-priority"></span>`spec.priority` | integer | no |  | 1 to 5 | The run's priority, 1 (highest) to 5, when runs wait for capacity. |
| <span id="spec-overlap"></span>`spec.overlap` | string | no |  | `skip_if_running`, `queue`, `cancel_previous` | What happens when a run of the workflow for the same subject is already going. Defaults to skip_if_running. |
| <span id="spec-event"></span>`spec.event` | string | no |  | length 1 to any | webhook: the GitHub event, such as push or pull_request, or one action of it, such as pull_request.opened. firewall: one event of the source, such as package.first_seen (or list several in events). |
| <span id="spec-ref"></span>`spec.ref` | string | no |  | `default`, `tags` | webhook push and release events: default for branch pushes, tags for tag pushes and releases. |
| <span id="spec-conditions"></span>`spec.conditions` | object | no |  | no other keys | webhook: conditions the delivery must meet, all of them. A condition the delivery carries no data for does not match. Globs: * is any run of characters except /, ** includes /, ? is one character; @default is the repository's default branch. |
| <span id="spec-conditions-actions"></span>`spec.conditions.actions` | array of string | no |  | each item: length 1 to any | The event's actions that count, such as opened and synchronize for pull_request. Only when event names no action. |
| <span id="spec-conditions-baseBranch"></span>`spec.conditions.baseBranch` | array of string | no |  | 0 to 30 items; each item: length 1 to 200 | Branch globs the pull request targets, or the pushed branch for a push. |
| <span id="spec-conditions-headBranch"></span>`spec.conditions.headBranch` | array of string | no |  | 0 to 30 items; each item: length 1 to 200 | Branch globs of the pull request's head, or the pushed branch for a push. |
| <span id="spec-conditions-paths"></span>`spec.conditions.paths` | array of string | no |  | 0 to 30 items; each item: length 1 to 200 | push only: path globs, at least one of which a pushed commit changed. |
| <span id="spec-conditions-pathsIgnore"></span>`spec.conditions.pathsIgnore` | array of string | no |  | 0 to 30 items; each item: length 1 to 200 | push only: path globs that do not count as a change. |
| <span id="spec-conditions-labels"></span>`spec.conditions.labels` | object | no |  | no other keys | Labels on the issue or pull request. |
| <span id="spec-conditions-labels-any"></span>`spec.conditions.labels.any` | array of string | no |  | each item: length 1 to any | At least one of these labels. |
| <span id="spec-conditions-labels-all"></span>`spec.conditions.labels.all` | array of string | no |  | each item: length 1 to any | Every one of these labels. |
| <span id="spec-conditions-authorType"></span>`spec.conditions.authorType` | string | no |  | `any`, `user`, `bot` | Who made the change: a person (user), a bot, or any. |
| <span id="spec-conditions-authors"></span>`spec.conditions.authors` | object | no |  | no other keys | GitHub logins, as globs. |
| <span id="spec-conditions-authors-allow"></span>`spec.conditions.authors.allow` | array of string | no |  | each item: length 1 to any | Only these authors. |
| <span id="spec-conditions-authors-deny"></span>`spec.conditions.authors.deny` | array of string | no |  | each item: length 1 to any | Never these authors. |
| <span id="spec-conditions-draft"></span>`spec.conditions.draft` | string | no |  | `include`, `exclude`, `only` | Draft pull requests: include them, exclude them, or only them. |
| <span id="spec-conditions-origin"></span>`spec.conditions.origin` | string | no |  | `any`, `same_repo`, `fork` | Pull requests from the same repository, from forks, or any. |
| <span id="spec-conditions-conclusion"></span>`spec.conditions.conclusion` | array of string | no |  | each item: length 1 to any | check_run, check_suite and workflow_run: the conclusions that count, such as failure. deployment_status: the states that count. |
| <span id="spec-conditions-reviewState"></span>`spec.conditions.reviewState` | array of string | no |  | each item: `approved`, `changes_requested`, `dismissed`, `commented` | pull_request_review: the review states that count. |
| <span id="spec-conditions-subject"></span>`spec.conditions.subject` | string | no |  | `any`, `pr`, `issue`, `none` | What the delivery must be about: a pull request (pr), an issue, nothing in particular (none), or any. |
| <span id="spec-conditions-severity"></span>`spec.conditions.severity` | array of string | no |  | each item: length 1 to any | dependabot_alert, code_scanning_alert and posture_finding: the alert severities that count. |
| <span id="spec-conditions-environment"></span>`spec.conditions.environment` | array of string | no |  | 0 to 30 items; each item: length 1 to 200 | deployment_status: environment globs. |
| <span id="spec-conditions-packageType"></span>`spec.conditions.packageType` | array of string | no |  | each item: length 1 to any | registry_package: the package types that count, such as container and npm. |
| <span id="spec-conditions-properties"></span>`spec.conditions.properties` | object | no |  | 1 to any keys; map of string to array of string (1 to any items) | Repository custom properties: each property named with the values it may hold, such as team: [payments]. |
| <span id="spec-debounceSeconds"></span>`spec.debounceSeconds` | integer | no |  | 0 to 3600 | webhook and label: deliveries for the same subject inside this window start one run. 0 to 3600; 30 when left out. |
| <span id="spec-maxRunsPerHour"></span>`spec.maxRunsPerHour` | integer | no |  | 1 to 1000 | webhook, label and firewall: the most runs the trigger starts in an hour, 1 to 1000; 60 when left out. |
| <span id="spec-label"></span>`spec.label` | string | no |  | length 1 to any | label: the issue or pull request label that starts the workflow. |
| <span id="spec-severity"></span>`spec.severity` | array of string | no |  | items unique; each item: `low`, `medium`, `high`, `critical` | finding: the finding severities that start the workflow. All of them when left out. |
| <span id="spec-fromList"></span>`spec.fromList` | string | no |  | length 1 to any | kanban: the board list a card leaves. |
| <span id="spec-toList"></span>`spec.toList` | string | no |  | length 1 to any | kanban: the board list a card enters. |
| <span id="spec-source"></span>`spec.source` | string | no |  | `package-firewall`, `ai-firewall`, `egress`, `siem`, `github-risk`, `github-posture` | firewall: where the sighting comes from: the package firewall, the AI firewall, Pix Sandbox egress, Guardian (siem), or the GitHub risk and posture rules. |
| <span id="spec-events"></span>`spec.events` | array of string | no |  | each item: length 1 to any | firewall: the source's events that start the workflow, such as package.first_seen and package.blocked. Every event of the source when neither this nor event is set. |
| <span id="spec-newTo"></span>`spec.newTo` | string | no |  | `org`, `repo` | firewall: only a first sighting in the organisation (org), or, for packages, in the repository (repo). |
| <span id="spec-decision"></span>`spec.decision` | array of string | no |  | each item: length 1 to any | firewall: the firewall decisions that start the workflow, such as block or hold. |
| <span id="spec-ecosystems"></span>`spec.ecosystems` | array of string | no |  | each item: length 1 to any | firewall, package-firewall source: the package ecosystems, such as npm and pypi. |
| <span id="spec-kinds"></span>`spec.kinds` | array of string | no |  | each item: `tool`, `mcp_server`, `skill`, `client` | firewall, ai-firewall source: the capability kinds. |
| <span id="spec-sandboxes"></span>`spec.sandboxes` | array of string | no |  | each item: length 1 to any | firewall, egress source: the Pix Sandboxes, by name. |
| <span id="spec-categories"></span>`spec.categories` | array of string | no |  | each item: `network`, `dns`, `waf`, `http`, `cloud_audit`, `vulnetix`, `other` | firewall, siem source: the Guardian categories. |
| <span id="spec-providers"></span>`spec.providers` | array of string | no |  | each item: `aws`, `cloudflare`, `vulnetix`, `mixed` | firewall, siem source: the log providers. |
| <span id="spec-tables"></span>`spec.tables` | array of string | no |  | each item: `net_events`, `dns_events`, `waf_events`, `http_events`, `cloud_audit`, `product_events` | firewall, siem source: the Guardian tables. |
| <span id="spec-triggers"></span>`spec.triggers` | array of string | no |  | each item: length 1 to any | firewall, siem source: the Guardian alert triggers by name. |
| <span id="spec-ticketRepo"></span>`spec.ticketRepo` | string | no |  | pattern `^[A-Za-z0-9_.-]{1,100}/[A-Za-z0-9_.-]{1,100}$` | firewall: the repository, owner/name, where review tickets for a sighting are opened. |

## Applying this kind

- **Command.** `vulnetix config apply -f <file>`; the CLI line above says from which release. Plan first with [`vulnetix config plan`](/platform-iac/cli/plan.md): it shows each object as create, update, delete or no change, with a `planHash` that apply then holds to. Apply writes in one transaction.
- **Manager.** Each object records the manager that applied it (`terraform`, `console` or `gitops:<repo>`). `--prune` deletes only objects its own manager owns. See [The manager](/platform-iac/cli/plan.md#the-manager) and the [config engine](/platform-iac/reference/engine.md).
- **Order.** Applied after [`FactoryWorkflow`](/platform-iac/kinds/factory-workflow.md), so a document that refers to one by `metadata.name` can be in the same apply. Deleted before them.
- **Status.** Applied, Unchanged or Deleted, with no other status fields. The phases the engine reports are explained under [status phases](/platform-iac/reference/engine.md#status-phases).

## How apply treats it

Written as the Schedules tab writes them: the engine edits the workflow's published graph and publishes it. It is checked by the graph validator's trigger rules and by the typed condition checks. It references its [`FactoryWorkflow`](/platform-iac/kinds/factory-workflow.md) by name.

> [!CAREFUL] Conditions are typed, not CEL
> Trigger conditions are typed fields in the document. The CEL `event` context exists in the CEL package, but no released kind has a CEL field in it. See [CEL rule expressions](/platform-iac/reference/cel.md).

## Terraform and OpenTofu

The resource is `vulnetix_factory_trigger` in the `vulnetix/resolve` provider. Its arguments are the `spec` in snake case, beside `name`, `labels` and `annotations` from `metadata`. The Minimal and Advanced HCL are above. The provider's own reference is [vulnetix_factory_trigger](https://registry.terraform.io/providers/vulnetix/resolve/latest/docs/resources/factory_trigger).

Import an object that already exists by its name:

```shell
# Import an existing FactoryTrigger by its name (metadata.name).
terraform import vulnetix_factory_trigger.run_now run-now
```

Install, authentication and how state is read: [Terraform and OpenTofu](/platform-iac/terraform.md).

Check a file with `vulnetix config validate -f <file>`. See [Validate documents](/platform-iac/cli/validate.md). In an editor, start the file with the [schema comment](/platform-iac/schemas/editors.md).
