Pipeline file reference

A pipeline is defined by .infraista/pipeline.yml in your repository (the path is set per pipeline). The editor checks the file as you type and shows errors on their lines; a file with errors starts no jobs.

A complete example

name: web-app
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  manual: true

env:
  NODE_ENV: production

stages:
  - name: test
    jobs:
      - name: unit-tests
        image: node:20
        steps:
          - uses: infraista/checkout@v1
          - uses: infraista/cache@v1
            with:
              key: npm-v1
              path: ~/.npm
          - run: npm ci
          - run: npm test

  - name: build
    jobs:
      - name: image
        steps:
          - uses: infraista/checkout@v1
          - uses: infraista/docker-build-push@v1
            with:
              registry: infraista
              image: registry.infraista.cloud/northwind/web-app
              tags: $GIT_SHORT_SHA

  - name: deploy
    jobs:
      - name: production
        environment: production
        if: branch == main
        steps:
          - uses: infraista/deploy-docker@v1
            with:
              target: web-servers
              registry: infraista
              image: registry.infraista.cloud/northwind/web-app:$GIT_SHORT_SHA
              env_from: pipeline
              containers:
                - name: web
                  ports: ["80:3000"]

Top-level keys

Any other top-level key is an error.

inputs

inputs:
  target:
    type: choice        # boolean, choice or string
    options: [staging, production]
    default: staging
  dry_run:
    type: boolean

Input names use letters, digits and _. A choice needs options, and its default must be one of them. Jobs read inputs as $inputs.NAME.

Stages and jobs

stages:
  - name: test
    jobs:
      - name: lint
        steps: [...]
      - name: unit-tests
        steps: [...]

• Stage names use letters, digits, spaces and - _ .; job names letters, digits and - _ .. Job names must be unique in the pipeline.
• Stages run in order; the jobs in a stage run in parallel. By default a job waits for every job of the earlier stages. Use needs to wait only for specific jobs.
• A pipeline can have up to 50 jobs, and a job up to 50 steps.

Job keys

Steps

Each step is either a shell command (run:) or a built-in action (uses:), never both:

steps:
  - run: npm ci                      # a command
  - name: Run the tests              # optional label in the log
    run: |
      npm run lint
      npm test
    env:
      CI_SHARD: "1"
  - uses: infraista/checkout@v1      # an action

Commands run with bash if the image has it, otherwise sh, and stop at the first failing line (set -e). The job starts in /workspace; use infraista/checkout to get your code there.

Conditions (if)

if: branch == main
if: event == pull_request && branch != main
if: failure()
if: always()

Expressions and variables

Values come from Secrets and variables.

Built-in variables

Every job gets these:

Variables from env: are applied in order: the file's, then the job's, then the step's.

Built-in actions

Actions are written uses: infraista/<name>@v1, with their options under with:.

Code, tools and files

Caches belong to the pipeline and branch; a branch without one falls back to the default branch, then to restore-keys. Pull requests read their base branch's cache but write their own.

Images

docker-build-push builds an image and pushes it:

- uses: infraista/docker-build-push@v1
  with:
    registry: infraista                  # your Container Registry, or a registry deploy target
    image: registry.infraista.cloud/northwind/web-app
    tags: $GIT_SHORT_SHA
    context: .                           # optional
    file: Dockerfile                     # optional
    build_args:                          # optional
      NODE_VERSION: "20"
    push: true                           # optional; pull requests never push

The build runs in a throwaway Docker of its own, never the runner's.

Settings your app needs at build time (for example NEXT_PUBLIC_* or VITE_* values): add env_from: pipeline to pass the job's variables (never secrets) as build arguments, and environment: <name> to choose whose values. Add env_file: .env to write them to that file in the build context instead of build arguments. Secrets never become build arguments, because build arguments stay in the image's history.

Deploying

registry: infraista signs the server in to your Container Registry before the script, so it can pull your images. See Deploy targets for examples.

Containers on a server (deploy-docker)

- uses: infraista/deploy-docker@v1
  with:
    target: web-servers
    registry: infraista
    image: registry.infraista.cloud/northwind/web-app:$GIT_SHORT_SHA
    env_from: pipeline          # the job's secrets and variables as the containers' environment
    containers:
      - name: api
        ports: ["9090:80"]
        after_start: [php artisan migrate --force]
      - name: worker
        command: php artisan queue:work

Each container takes name (required), ports, command, after_start, env, volumes, network and restart. The step pulls the image, replaces the old containers (workers first, then the ones with ports), starts each one, checks it stays up (showing its last logs if not), runs its after_start commands inside it, and prunes old images. Up to 20 containers per step. Deploy a tag like $GIT_SHORT_SHA, so a rollback runs the image that was deployed.

Gates and checks

Not available yet

deploy-containers, deploy-app-platform and terraform are accepted in the file but fail with a clear message when they run.

Limits

• The file can be up to 256 KB, with up to 50 jobs and 50 steps per job.
• Job timeouts go from 1 minute to 72 hours.
• Paste carefully: invisible characters copied from web pages and chat apps are removed before the file is read, so line numbers in errors stay right.

Related

• Triggers
• Secrets and variables
• Deploy targets