# FactoryWorkflow

A Software Factory workflow: the graph of steps a run walks, from a trigger through scans, decisions, crews, gates and people to its outputs.

A Software Factory workflow: the graph of steps a run walks, from a trigger through scans, decisions, crews, gates and people to its outputs. metadata.name is the workflow's slug (at most 60 characters; slugs that start with sys- belong to the default workflows and cannot be declared). Workflows are versioned: a change to the graph never edits a published version, it saves a new version and, with publish true, publishes it. Triggers and schedules declared as FactoryTrigger and FactorySchedule documents add their own trigger nodes to the graph; those nodes are not part of this document and a graph change keeps them. Removing the document archives the workflow: it is switched off and its triggers removed, and its versions and run history are kept.

| | |
|---|---|
| `apiVersion` | `vulnetix.com/v1` |
| `kind` | `FactoryWorkflow` |
| 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). |
| Terraform resource | [`vulnetix_factory_workflow`](/platform-iac/terraform/resources.md#vulnetix_factory_workflow), 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/FactoryWorkflow.schema.json`](https://github.com/Vulnesis/config-schemas/releases/download/v1.19.1/FactoryWorkflow.schema.json) |
| Newest schema | [`latest/FactoryWorkflow.schema.json`](https://github.com/Vulnesis/config-schemas/releases/latest/download/FactoryWorkflow.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 FactoryWorkflow` |

## Minimal

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

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/FactoryWorkflow.schema.json
apiVersion: vulnetix.com/v1
kind: FactoryWorkflow
metadata:
  name: patch-on-demand
spec:
  graph:
    nodes:
      - id: start
        type: trigger
        title: Run by hand
        config:
          kind: manual
```

**HCL** (resource `vulnetix_factory_workflow`)

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

resource "vulnetix_factory_workflow" "patch_on_demand" {
  name = "patch-on-demand"
  graph = {
    nodes = [
      {
        config = jsonencode({
          kind = "manual"
        })
        id    = "start"
        title = "Run by hand"
        type  = "trigger"
      },
    ]
  }
}
```

Every field that has a schema default, set to that default: [`terraform/factory_workflow.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/factory_workflow.tf) and [`yaml/FactoryWorkflow.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/FactoryWorkflow.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/FactoryWorkflow.schema.json
apiVersion: vulnetix.com/v1
kind: FactoryWorkflow
metadata:
  name: patch-on-demand
spec:
  graph:
    nodes:
      - id: start
        type: trigger
        title: Run by hand
        config:
          kind: manual
EOF
```

## Advanced

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

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/FactoryWorkflow.schema.json
apiVersion: vulnetix.com/v1
kind: FactoryWorkflow
metadata:
  name: security-patch-train
  labels:
    team: appsec
  annotations:
    owner: appsec@acme.com
spec:
  displayName: Security patch train
  description: Scan, patch with belai:security, hold the change to CI and the quality gate, then open a draft pull request.
  publish: true
  enabled: true
  graph:
    nodes:
      - id: start
        type: trigger
        title: Run by hand
        config:
          kind: manual
        position: { x: 0, y: 0 }
      - id: scan
        type: scan
        title: Scanners
        config:
          source: posture
          scanners: [sca, malscan, secrets]
          failOn: [malware, secrets]
          sbomFormat: cyclonedx-1.6
        githubCalls: { max: 1 }
        onQuotaLow: use_cached
        position: { x: 240, y: 0 }
      - id: patch
        type: crew
        title: Patch and verify
        config:
          crew: belai:security
          mode: goal
          codeTier: smart
          testsPostEnd: goal
          testsOnFail: fix
          maxAttempts: 3
        budget: { tokens: 300000 }
        position: { x: 480, y: 0 }
      - id: gate
        type: gate
        title: Quality gate and tests
        config:
          profile: org_default
          releaseJail: enforce
          onFail: return_to_crew
          checkSource: mirror
          maxGithubCalls: 2
          onQuotaLow: use_cached
        githubCalls: { max: 2 }
        position: { x: 720, y: 0 }
      - id: pr
        type: output
        title: Draft pull request
        config:
          kind: draft_pr
          prState: draft
          reviewers: codeowners
          attach: cdx_slsa
        githubCalls: { max: 2 }
        position: { x: 960, y: 0 }
    edges:
      - { from: start, to: scan }
      - { from: scan, to: patch, label: findings }
      - { from: patch, to: gate, label: branch }
      - { from: gate, to: pr, outcome: pass }
      - { from: gate, to: patch, outcome: fail, loop: true }
    limits:
      runBudgetTokens: 400000
      monthBudgetTokens: 6000000
      concurrency: 2
      githubCallsPerRun: { typical: 4, max: 8 }
      stopTheLineAttempts: 3
      agentCostUsd: 5
      agentFinalizeAt: 0.8
      agentMaxAttempts: 3
      agentMaxContinuations: 2
      agentMaxPasses: 20
      agentMaxWallMinutes: 120
      agentMaxIterations: 80
    scope:
      repos: [acme/payments, acme-labs/*]
      orgs: [acme]
```

**HCL** (resource `vulnetix_factory_workflow`)

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

resource "vulnetix_factory_workflow" "security_patch_train" {
  name         = "security-patch-train"
  description  = "Scan, patch with belai:security, hold the change to CI and the quality gate, then open a draft pull request."
  display_name = "Security patch train"
  enabled      = true
  graph = {
    edges = [
      {
        from = "start"
        to   = "scan"
      },
      {
        from  = "scan"
        label = "findings"
        to    = "patch"
      },
      {
        from  = "patch"
        label = "branch"
        to    = "gate"
      },
      {
        from    = "gate"
        outcome = "pass"
        to      = "pr"
      },
      {
        from    = "gate"
        loop    = true
        outcome = "fail"
        to      = "patch"
      },
    ]
    limits = {
      agent_cost_usd          = 5
      agent_finalize_at       = 0.8
      agent_max_attempts      = 3
      agent_max_continuations = 2
      agent_max_iterations    = 80
      agent_max_passes        = 20
      agent_max_wall_minutes  = 120
      concurrency             = 2
      github_calls_per_run = {
        max     = 8
        typical = 4
      }
      month_budget_tokens    = 6000000
      run_budget_tokens      = 400000
      stop_the_line_attempts = 3
    }
    nodes = [
      {
        config = jsonencode({
          kind = "manual"
        })
        id = "start"
        position = {
          x = 0
          y = 0
        }
        title = "Run by hand"
        type  = "trigger"
      },
      {
        config = jsonencode({
          failOn     = ["malware", "secrets"]
          sbomFormat = "cyclonedx-1.6"
          scanners   = ["sca", "malscan", "secrets"]
          source     = "posture"
        })
        github_calls = {
          max = 1
        }
        id           = "scan"
        on_quota_low = "use_cached"
        position = {
          x = 240
          y = 0
        }
        title = "Scanners"
        type  = "scan"
      },
      {
        budget = {
          tokens = 300000
        }
        config = jsonencode({
          codeTier     = "smart"
          crew         = "belai:security"
          maxAttempts  = 3
          mode         = "goal"
          testsOnFail  = "fix"
          testsPostEnd = "goal"
        })
        id = "patch"
        position = {
          x = 480
          y = 0
        }
        title = "Patch and verify"
        type  = "crew"
      },
      {
        config = jsonencode({
          checkSource    = "mirror"
          maxGithubCalls = 2
          onFail         = "return_to_crew"
          onQuotaLow     = "use_cached"
          profile        = "org_default"
          releaseJail    = "enforce"
        })
        github_calls = {
          max = 2
        }
        id = "gate"
        position = {
          x = 720
          y = 0
        }
        title = "Quality gate and tests"
        type  = "gate"
      },
      {
        config = jsonencode({
          attach    = "cdx_slsa"
          kind      = "draft_pr"
          prState   = "draft"
          reviewers = "codeowners"
        })
        github_calls = {
          max = 2
        }
        id = "pr"
        position = {
          x = 960
          y = 0
        }
        title = "Draft pull request"
        type  = "output"
      },
    ]
    scope = {
      orgs  = ["acme"]
      repos = ["acme/payments", "acme-labs/*"]
    }
  }
  publish = true
  labels = {
    team = "appsec"
  }
  annotations = {
    owner = "appsec@acme.com"
  }
}
```

Every field that has a schema default, set to that default: [`terraform/factory_workflow.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/factory_workflow.tf) and [`yaml/FactoryWorkflow.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/FactoryWorkflow.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/FactoryWorkflow.schema.json
apiVersion: vulnetix.com/v1
kind: FactoryWorkflow
metadata:
  name: security-patch-train
  labels:
    team: appsec
  annotations:
    owner: appsec@acme.com
spec:
  displayName: Security patch train
  description: Scan, patch with belai:security, hold the change to CI and the quality gate, then open a draft pull request.
  publish: true
  enabled: true
  graph:
    nodes:
      - id: start
        type: trigger
        title: Run by hand
        config:
          kind: manual
        position: { x: 0, y: 0 }
      - id: scan
        type: scan
        title: Scanners
        config:
          source: posture
          scanners: [sca, malscan, secrets]
          failOn: [malware, secrets]
          sbomFormat: cyclonedx-1.6
        githubCalls: { max: 1 }
        onQuotaLow: use_cached
        position: { x: 240, y: 0 }
      - id: patch
        type: crew
        title: Patch and verify
        config:
          crew: belai:security
          mode: goal
          codeTier: smart
          testsPostEnd: goal
          testsOnFail: fix
          maxAttempts: 3
        budget: { tokens: 300000 }
        position: { x: 480, y: 0 }
      - id: gate
        type: gate
        title: Quality gate and tests
        config:
          profile: org_default
          releaseJail: enforce
          onFail: return_to_crew
          checkSource: mirror
          maxGithubCalls: 2
          onQuotaLow: use_cached
        githubCalls: { max: 2 }
        position: { x: 720, y: 0 }
      - id: pr
        type: output
        title: Draft pull request
        config:
          kind: draft_pr
          prState: draft
          reviewers: codeowners
          attach: cdx_slsa
        githubCalls: { max: 2 }
        position: { x: 960, y: 0 }
    edges:
      - { from: start, to: scan }
      - { from: scan, to: patch, label: findings }
      - { from: patch, to: gate, label: branch }
      - { from: gate, to: pr, outcome: pass }
      - { from: gate, to: patch, outcome: fail, loop: true }
    limits:
      runBudgetTokens: 400000
      monthBudgetTokens: 6000000
      concurrency: 2
      githubCallsPerRun: { typical: 4, max: 8 }
      stopTheLineAttempts: 3
      agentCostUsd: 5
      agentFinalizeAt: 0.8
      agentMaxAttempts: 3
      agentMaxContinuations: 2
      agentMaxPasses: 20
      agentMaxWallMinutes: 120
      agentMaxIterations: 80
    scope:
      repos: [acme/payments, acme-labs/*]
      orgs: [acme]
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 `FactoryWorkflow` | Always FactoryWorkflow. |
| <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-displayName"></span>`spec.displayName` | string | no |  | length 1 to 120 | The name the console shows. Left out, the workflow is shown under its metadata.name. |
| <span id="spec-description"></span>`spec.description` | string | no |  | length 0 to 2000 | What the workflow is for, shown under its name in the console. |
| <span id="spec-publish"></span>`spec.publish` | boolean | no | `true` |  | true, or left out: the graph is the workflow's published version, and new runs use it; a changed graph is saved as the next version and published, which needs a graph that passes the full publish checks (a trigger, every step reachable, no cycle, every decision outcome routed, and every step but config-apply configured, not left with an empty config). false: the graph is kept as the workflow's draft and runs keep using the last published version. Apply refuses to publish over a draft someone left unpublished in the console unless the draft already holds this graph. A draft may hold steps that are not configured yet (config: {}). |
| <span id="spec-enabled"></span>`spec.enabled` | boolean | no | `true` |  | Whether the factory starts runs of the workflow. Switching a workflow off also switches off its event triggers; a run already going is left to finish. A workflow that has never been published cannot be switched on. |
| <span id="spec-graph"></span>`spec.graph` | object | yes |  | no other keys | The workflow graph, in the shape the console's workflow builder saves and the workflow API takes. |
| <span id="spec-graph-nodes"></span>`spec.graph.nodes` | array of object | yes |  | 0 to 60 items | The steps, at most 60. |
| <span id="spec-graph-nodes-id"></span>`spec.graph.nodes[].id` | string | yes |  | pattern `^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$` | The step's id, unique in the graph: 1 to 40 letters, digits, dashes or underscores. Edges name steps by it. |
| <span id="spec-graph-nodes-type"></span>`spec.graph.nodes[].type` | string | yes |  | `trigger`, `scan`, `decision`, `crew`, `gate`, `human`, `output`, `state`, `config-apply` | What the step does. trigger: what starts a run. scan: run scanners or read their results. decision: ask a model a question and route on the answer. crew: hand the work to a Belai crew or agent. gate: hold the run to CI checks, the quality gate and the release jail, and ask a person to approve a config-apply plan. human: ask a person to approve. output: open a pull request, comment, publish to TEA, notify or write VEX. state: read or write a stored object. config-apply: plan, or apply an approved plan of, the Platform IaC documents in the repository's .vulnetix/config/ directory at the pushed commit (config: phase plan or apply, and prune). |
| <span id="spec-graph-nodes-title"></span>`spec.graph.nodes[].title` | string | yes |  | length 0 to 200 | The step's title in the builder and the run view. Publishing needs a title that is not empty on every step. |
| <span id="spec-graph-nodes-config"></span>`spec.graph.nodes[].config` | object | no |  |  | The step's settings, which depend on its type. A published workflow needs at least one on every step except config-apply, such as a trigger's kind or a gate's profile; a draft (publish: false) may leave them empty (config: {}), and so may a config-apply step, whose settings all have defaults. They are the settings the workflow builder edits, under the same names; the server checks them with the builder's own rules, so a step the builder would refuse is refused here too. A trigger step's config is the same as a FactoryTrigger or FactorySchedule spec, with the type under kind (kind: cron for a schedule, with cron, tz and runsOn). |
| <span id="spec-graph-nodes-budget"></span>`spec.graph.nodes[].budget` | object | no |  | no other keys | The step's token budget. |
| <span id="spec-graph-nodes-budget-tokens"></span>`spec.graph.nodes[].budget.tokens` | integer | no |  | >= 0 | Tokens the step may spend in one run; 0 for no limit of its own. |
| <span id="spec-graph-nodes-githubCalls"></span>`spec.graph.nodes[].githubCalls` | object | no |  | no other keys | The step's GitHub API call limit. |
| <span id="spec-graph-nodes-githubCalls-max"></span>`spec.graph.nodes[].githubCalls.max` | integer | no |  | >= 0 | GitHub API calls the step may make in one run. |
| <span id="spec-graph-nodes-onQuotaLow"></span>`spec.graph.nodes[].onQuotaLow` | string | no |  | `use_cached`, `defer`, `escalate` | What the step does when the GitHub quota is low: carry on with cached data, wait for the quota window, or ask a person. |
| <span id="spec-graph-nodes-position"></span>`spec.graph.nodes[].position` | object | no |  | no other keys | Where the builder draws the step. It has no effect on runs. |
| <span id="spec-graph-nodes-position-x"></span>`spec.graph.nodes[].position.x` | number | no |  |  |  |
| <span id="spec-graph-nodes-position-y"></span>`spec.graph.nodes[].position.y` | number | no |  |  |  |
| <span id="spec-graph-edges"></span>`spec.graph.edges` | array of object | no |  | 0 to 120 items | The connections between steps, at most 120. A run moves along an edge when the step it leaves finishes. |
| <span id="spec-graph-edges-from"></span>`spec.graph.edges[].from` | string | yes |  | length 1 to any | The id of the step the edge leaves. |
| <span id="spec-graph-edges-to"></span>`spec.graph.edges[].to` | string | yes |  | length 1 to any | The id of the step the edge enters. Nothing may lead into a trigger. |
| <span id="spec-graph-edges-label"></span>`spec.graph.edges[].label` | string | no |  | length 0 to 200 | The artifact that travels along the edge, shown on the canvas. |
| <span id="spec-graph-edges-outcome"></span>`spec.graph.edges[].outcome` | string | no |  | length 0 to 41 | On an edge leaving a decision: the outcome that takes it, or $below_threshold or $unknown. On an edge leaving a gate: pass, or fail for the loop back to a crew. |
| <span id="spec-graph-edges-loop"></span>`spec.graph.edges[].loop` | boolean | no |  |  | Marks the one kind of edge allowed to go back: a gate or decision returning work to a crew, bounded by limits.stopTheLineAttempts. |
| <span id="spec-graph-limits"></span>`spec.graph.limits` | object | no |  | no other keys | Run limits. A value left out, or 0, keeps the tenant's setting. |
| <span id="spec-graph-limits-runBudgetTokens"></span>`spec.graph.limits.runBudgetTokens` | integer | no |  | >= 0 | Tokens one run may spend. At most monthBudgetTokens when both are set. |
| <span id="spec-graph-limits-monthBudgetTokens"></span>`spec.graph.limits.monthBudgetTokens` | integer | no |  | >= 0 | Tokens the workflow may spend in a calendar month (UTC). |
| <span id="spec-graph-limits-concurrency"></span>`spec.graph.limits.concurrency` | integer | no |  | 0 to 50 | Runs of the workflow at once, 1 to 50. |
| <span id="spec-graph-limits-githubCallsPerRun"></span>`spec.graph.limits.githubCallsPerRun` | object | no |  | no other keys | The GitHub API calls a run is expected to make, for the estimate the builder shows. |
| <span id="spec-graph-limits-githubCallsPerRun-typical"></span>`spec.graph.limits.githubCallsPerRun.typical` | integer | no |  | >= 0 |  |
| <span id="spec-graph-limits-githubCallsPerRun-max"></span>`spec.graph.limits.githubCallsPerRun.max` | integer | no |  | >= 0 |  |
| <span id="spec-graph-limits-stopTheLineAttempts"></span>`spec.graph.limits.stopTheLineAttempts` | integer | no |  | 0 to 10 | Failed attempts after which a loop back to a crew stops the run, 1 to 10. |
| <span id="spec-graph-limits-agentCostUsd"></span>`spec.graph.limits.agentCostUsd` | number | no |  | 0 to 10000 | The cost limit, in US dollars, of each card a worker this workflow starts takes on, up to 10000. |
| <span id="spec-graph-limits-agentFinalizeAt"></span>`spec.graph.limits.agentFinalizeAt` | number | no |  | 0 to 0.95 | The share of a limit (0 to 0.95) at which a worker starts wrapping up. |
| <span id="spec-graph-limits-agentMaxAttempts"></span>`spec.graph.limits.agentMaxAttempts` | integer | no |  | 0 to 10 | Failed attempts a worker may make on one card, up to 10. |
| <span id="spec-graph-limits-agentMaxContinuations"></span>`spec.graph.limits.agentMaxContinuations` | integer | no |  | 0 to 50 | How often a card may resume after its budget ran out, up to 50. |
| <span id="spec-graph-limits-agentMaxPasses"></span>`spec.graph.limits.agentMaxPasses` | integer | no |  | 0 to 1000 | Passes a worker may make on one card, up to 1000. |
| <span id="spec-graph-limits-agentMaxWallMinutes"></span>`spec.graph.limits.agentMaxWallMinutes` | integer | no |  | 0 to 10080 | Minutes a worker may spend on one card, up to 10080 (a week). |
| <span id="spec-graph-limits-agentMaxIterations"></span>`spec.graph.limits.agentMaxIterations` | integer | no |  | 0 to 400 | Tool rounds a worker may take in one pass, up to 400. |
| <span id="spec-graph-scope"></span>`spec.graph.scope` | object | no |  | no other keys | The repositories the workflow may run on. |
| <span id="spec-graph-scope-repos"></span>`spec.graph.scope.repos` | array of string | no |  | each item: pattern `^(\*\|[A-Za-z0-9._-]{1,100}/(\*\|[A-Za-z0-9._-]{1,100}))$` | Repositories as owner/name, owner/* for every repository of an owner, or * for every managed repository. Names are compared without case. |
| <span id="spec-graph-scope-orgs"></span>`spec.graph.scope.orgs` | array of string | no |  | each item: length 1 to 100 | GitHub organisations whose managed repositories the workflow may run on. |

## 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).
- **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

- The graph is checked by the Resolve Platform's graph validator.
- A change saves the next version. With `publish: true` it also publishes that version through the Resolve Platform's publish, which reconciles the trigger rows and their schedules in the apply transaction. A published version is never edited.
- The trigger nodes that [`FactoryTrigger`](/platform-iac/kinds/factory-trigger.md) and [`FactorySchedule`](/platform-iac/kinds/factory-schedule.md) own are left out of the workflow's document, and kept by its graph changes.

### GitOps from a repository

A workflow node, `config-apply`, lets a config repository manage the tenant. Trigger it on a `push` webhook to the repository's default branch.

- It reads every `.yaml` and `.yml` file under the node's `path` (default `.vulnetix/config`) at the pushed commit, through the forge's git API (at most 4 MiB).
- It plans them as manager `gitops:<owner/repo>`, with prune on unless the node sets `prune: false`. The plan is the step's artifact.
- Blocking conditions fail the step with `config_plan_blocked`. No changes: the step succeeds and applies nothing.
- Otherwise, unless `approval: none`, the step asks for a person through the gate node's human approval, carrying the plan hash. Approved, it applies with that hash. A plan that moved since fails with `config_plan_changed` and applies nothing. Rejected or expired, the step fails.
- External objects that fail in the second phase fail the step with their count. Plan again to see what is left.

## Terraform and OpenTofu

The resource is `vulnetix_factory_workflow` 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_workflow](https://registry.terraform.io/providers/vulnetix/resolve/latest/docs/resources/factory_workflow).

Import an object that already exists by its name:

```shell
# Import an existing FactoryWorkflow by its name (metadata.name).
terraform import vulnetix_factory_workflow.patch_on_demand patch-on-demand
```

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

## More examples

`examples/FactoryWorkflow/config-apply.yaml` from `Vulnesis/config-schemas`:

```yaml
# A published config-apply step may have an empty config: the phase, path, prune and approval all have defaults.
apiVersion: vulnetix.com/v1
kind: FactoryWorkflow
metadata:
  name: apply-config-on-push
spec:
  graph:
    nodes:
      - id: start
        type: trigger
        title: On a push to the default branch
        config:
          kind: webhook
          event: push
      - id: apply
        type: config-apply
        title: Plan and apply the config
        config: {}
    edges:
      - from: start
        to: apply
```

`examples/FactoryWorkflow/draft-unconfigured.yaml` from `Vulnesis/config-schemas`:

```yaml
# A draft keeps its steps as the console saved them, including steps that are not configured yet: config: {} is accepted while publish is false.
apiVersion: vulnetix.com/v1
kind: FactoryWorkflow
metadata:
  name: triage-sketch
spec:
  publish: false
  graph:
    nodes:
      - id: start
        type: trigger
        title: When a finding arrives
        config: {}
      - id: scan
        type: scan
        title: Scan
        config: {}
    edges:
      - from: start
        to: scan
```

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).
