DocsBook a demo

Platform

Platform overviewArchitectureWorkflow orchestrationGitOps configurationGovernance and AAAAI and MCPKnowledge and contextRuntime and executionEvidence and monitoring

Use cases

All use casesProduction incidentRelease preparationHotfix to productionSecurity scan triage
Why NopsAIIntegrationsSecurity

Resources

All resourcesAI agent governanceMCP governanceMCP securitySelf-hosted platforms
PricingGitHub

Company

How a run worksAboutContactBook a demo

Pipeline anatomy

The shape of a pipeline document: what it must declare, what it may declare, and what every step inherits from it.

ReferenceAutomation authorNew userDeveloper

Key points

  • name and steps are the only unconditionally required top-level fields.
  • version defaults to latest, and validation writes the resolved value back when it is omitted.
  • container_image is the default image for every step; a step can override it, and a step that does not inherit this one.
  • working_directory defaults to /workspace. Relative values are joined onto it and may not escape with ..; the container root, NUL bytes, and any value containing : are rejected.
  • timeout is a duration; without it the pipeline falls back to the configured default_pipeline_timeout.
  • runtime_pool and affinity_enabled are placement hints resolved by the runner, not scheduling guarantees.
  • A pipeline may declare at most 512 steps.

Examples

Pipeline so faryaml
name: release-service
description: Build, verify, and publish the payments service.
container_image: alpine:3.20
working_directory: /workspace
timeout: 45m
steps:
  - name: build
    script: |
      make build
Result

A valid pipeline: one step, running make build in alpine:3.20 under /workspace.

Rejected: a working directory that escapes the workspaceyaml
working_directory: ../etc
Result

Validation rejects the value: relative paths are joined onto /workspace and may not escape it.

Field reference

namepipelinestringRequiredNone

Stable pipeline identifier used by runs, triggers, schedules, includes, and the API.

Example

name: release-service

Rules
  • Must match ^[a-zA-Z0-9_.-]+$.
Evidence

services/nopsai/pkg/validation/pipeline.go

versionpipelinestringOptionallatest

Pipeline version label. Validation writes back latest when the field is omitted.

Example

version: "2.4"

Rules
  • Must match ^[a-zA-Z0-9_.-]+$.
Evidence

services/nopsai/pkg/validation/pipeline.go

descriptionpipelinestringOptionalNone

Human-readable summary shown in the UI, API responses, and review surfaces.

Example

description: Build, test, and publish the payments service.

container_imagepipelinestringConditionalNone

Default image for executable steps. Required unless every executable step sets its own image; approval steps never need one.

Example

container_image: ghcr.io/acme/build-tools:1.4

Rules
  • Validation fails with "container_image is a required field if executable steps don't have their own image" when any non-approval step has no image.
Overridden by

steps[].image

Evidence

services/nopsai/pkg/validation/pipeline.go

working_directorypipelinestringOptional/workspace

Working directory inside every step container or pod.

Example

working_directory: services/api

Rules
  • Empty and . both resolve to /workspace.
  • Relative paths are joined onto /workspace and may not escape it with ...
  • Rejects the container root /, NUL bytes, and any value containing :.
Evidence

pkg/models/pipeline_paths.go

timeoutpipelinedurationOptionalFalls back to `default_pipeline_timeout`

Whole-run duration budget. When omitted, the platform default from system configuration applies.

Example

timeout: 45m

Evidence

services/nopsai/run_handlers.go

runtime_poolpipelinestringOptionalRunner default pool

Kubernetes runtime pool for the run. Docker runners ignore this field.

Example

runtime_pool: gpu

Overridden by

steps[].runtime_pool

Evidence

services/k8s-runner

affinity_enabledpipelinebooleanOptionalRunner `KUBERNETES_AFFINITY_ENABLED` setting

Overrides same-node affinity for step pods in this run. Docker runners ignore this field.

Example

affinity_enabled: true

Evidence

services/k8s-runner

stepspipelinestep[]RequiredNone

Ordered list of step definitions. Execution order comes from depends_on, not from list position.

Example

steps:
  - name: build
    script: make build

Rules
  • At least one step is required.
  • Maximum 256 steps per pipeline.
  • Step names must be unique.
Evidence

services/nopsai/pkg/validation/pipeline.go

steps (max per pipeline)limitcountOptional256 maximum

Maximum number of steps in one pipeline.

Example

pipeline has 257 steps; maximum is 256

Evidence

services/nopsai/pkg/validation/pipeline.go

How it works

Read the top of a pipeline as its defaults block. Almost every top-level directive here is a value that steps and tasks inherit unless they say otherwise, which is why the later pages in this chapter mostly add overrides rather than new concepts.

The chapter builds one manifest called release-service. Each page shows it as it stands, so the code block on any page is a complete, valid pipeline rather than a fragment. The finished version is checked into examples/gitops-quickstart/team-repo/pipelines/platform/release-service.yaml.

A step still needs a mode — script, goal, tasks, include, or approval — before the pipeline is runnable. The next page starts there.

Implementation evidence

  • pkg/models/model.go

    Pipeline, step, and task field definitions.

  • services/nopsai/pkg/validation/pipeline.go

    Rules the validator enforces on this directive set.