Commercial CI/CD

Pipeline YAML reference

Use the current compiler syntax for triggers, stages, jobs, checkout, shell commands, publish staging, and same-run artifact download. The reference also identifies parsed fields that do not yet drive runtime behavior.

Create workspace

Triggers and filters

Use the top-level trigger block with branch, tag, and path include/exclude lists plus pull_requests. Path filters depend on changed paths present in the provider payload.

Jobs and runners

Set runs_on, optional platform image, and timeout_minutes. depends_on controls root dispatch and dependent-job release from immutable run YAML; cyclic dependencies are rejected. Independent matrices expand up to 32 variants; matrix jobs cannot declare job-level dependencies.

Parsed versus executed

Variables substitute $(NAME) or ${NAME} in commands and step environment values. Step env maps are persisted for both runner types. Secret names must match exactly one organization/current-pipeline secret and become step snapshots; missing or ambiguous matches fail. Protected stage/job environments gate dispatch with approvals, and validated built-in tasks generate .NET, Node, Docker build, or Azure Container Apps commands. Deployment-target binding, custom tasks, broader expressions, and matrix-to-matrix dependencies remain incomplete.

Output workflow

Artifacts: use publish to stage a file or tar-gz directory under artifacts/; the generated command requires a POSIX shell with mkdir, tar, and cp.

Tests: write JUnit XML or TRX files under test-results/.

Coverage: write Cobertura XML under coverage/.

Caches: declare a cache step with a stable key, workspace-relative directory path, and optional ordered restore prefixes. Trusted non-pull-request jobs restore checksum-verified exact/fallback matches and save only after successful execution.

Execution matrix

checkoutRunner-managed fetch and verification of the requested commit SHA.
runExecutes the supplied shell command.
cacheRestores/saves a declared dependency directory with same-pipeline/same-branch trust boundaries.
publishStages one file or directory archive for post-job collection.
downloadDownloads the newest available matching artifact from the same run after dependencies make ordering safe.
taskRuns a validated built-in .NET, Node, Docker build, or Azure Container Apps command.
environmentProtected stage/job environments require approval before dispatch.
matrixExpands bounded scalar-list variants; a non-matrix job can fan in on all variants.
depends_onControls root dispatch, release after success, and blocked-dependency cancellation.

Minimal .NET pipeline

name: web-api-ci
trigger:
  branches:
    include:
      - main
stages:
  - stage: build
    jobs:
      - job: test
        runs_on: [self-hosted]
        timeout_minutes: 30
        steps:
          - checkout
          - cache:
              key: nuget-$(OS)-$(LOCK_HASH)
              path: .nuget/packages
              restore_keys:
                - nuget-$(OS)-
          - run: dotnet restore
          - run: dotnet test --logger trx --results-directory test-results
          - run: dotnet publish -c Release -o out
          - publish: out
            artifact: web-api

The supplied runner image is agent-only and does not include Git or the .NET SDK; install tools on the host or build a derived runner image.

Hosted Docker build pattern

name: container-build
trigger:
  branches:
    include:
      - main
stages:
  - stage: package
    jobs:
      - job: image
        runs_on: [hosted-linux]
        image: ubuntu-24.04-docker
        steps:
          - checkout
          - run: docker build -t local/container-build:current .
          - run: docker image inspect local/container-build:current > image-metadata.json
          - publish: image-metadata.json
            artifact: image-metadata.json

Docker-capable hosted execution requires approved access and real-worker validation. Trusted non-pull-request hosted Shipline work receives assignment-scoped checkout and Registry push credentials; pull-request work withholds them. Protected deployment records and target commands are created through the deployment UI/API, not a YAML deploy step.

Secrets and pull requests

Self-hosted work can receive separately persisted organization/pipeline/step/deployment credentials, and all of those are withheld for pull-request runs. Trusted non-pull-request hosted work receives checkout plus organization/pipeline/step/deployment and Shipline credentials through ephemeral step files; hosted PR work receives no checkout or privileged credentials. Known stored pipeline secrets are masked in uploaded logs; arbitrary credentials remain the customer's responsibility.