Anvil reads CI pipeline definitions from a .anvil.yml file at the root of your repository. This page documents every field the parser accepts, the values it validates, and the runtime behavior of each.

When a repository has no pipeline configured and a push includes a .anvil.yml, Anvil parses it and creates an enabled pipeline automatically. The whole file is validated before any step runs; on a parse error the run is recorded with an invalid status and no jobs execute.

Minimal example

A pipeline is a list of steps. Each step has a name and a run command. depends_on orders steps and lets independent steps run in parallel.

steps:
  - name: test
    run: mix test
  - name: build
    run: mix release
    depends_on: [test]

Full example

image: hexpm/elixir:1.20-erlang-29.0.1-debian-trixie-20260518

prepare:
  - apt-get update && apt-get install -y build-essential
  - mix local.hex --force && mix local.rebar --force

env:
  MIX_ENV: test
  DATABASE_URL: postgres://postgres:postgres@localhost/myapp_test

steps:
  - name: deps
    run: mix deps.get
    timeout_seconds: 600

  - name: compile
    run: mix compile --warnings-as-errors
    depends_on: [deps]

  - name: test
    run: mix test
    depends_on: [compile]
    allow_failure: false
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: myapp_test
    artifacts:
      - name: test-results
        path: _build/test/lib/*/test-results.xml

  - name: lint
    run: mix format --check-formatted
    depends_on: [deps]
    paths:
      - "lib/**"
      - "test/**"

  - name: build
    run: mix release
    depends_on: [test, lint]
    runs_on: self-hosted

Top-level fields

There is no top-level runs_on. Runner targeting is set per step (see Step fields).

Step fields

A step is a YAML mapping. name and run are required; everything else is optional. The parser rejects unknown keys (see Validation).

Conditions

A condition is a boolean expression evaluated against the run context before the step starts. When the expression is false, the step is skipped with reason condition. An empty or absent condition always runs.

The evaluator is a recursive-descent parser with no code evaluation. It supports only the operators below.

String literals use single or double quotes. The literals true and false are also recognized. An unknown identifier resolves to the empty string, and an empty string is treated as false.

The context exposes these variables:

Because branch holds the full refs/heads/<name> form on push and the bare <name> form on manual runs, an == comparison that works for one trigger can miss the other. Use contains to match a branch name regardless of trigger:

steps:
  - name: deploy
    run: mix deploy
    depends_on: [test]
    condition: "branch contains 'main' && trigger == 'push'"

Path filters

paths and paths_ignore skip a step based on which files changed in the push. When a step is skipped this way, its skip reason is path_filter. If the changed-file list is unavailable (for example a new branch with no parent, or a diff that fails), path filters are treated as satisfied and the step runs.

A step runs when at least one changed file matches a paths pattern, unless every changed file also matches paths_ignore.

steps:
  - name: lint-frontend
    run: npm run lint
    paths:
      - "assets/**"
    paths_ignore:
      - "assets/vendor/**"

Matrix strategies

strategy.matrix expands one step into several jobs, one per combination of the listed dimension values. Each value of every dimension is combined with every value of every other dimension. Reference a dimension in run with ${{ matrix.<dimension> }}; Anvil substitutes the value before the command runs.

steps:
  - name: test
    run: mix test
    strategy:
      matrix:
        elixir: ["1.16", "1.17"]
        otp: ["26", "27"]

The example above produces four jobs. Each expanded job is named after the base name with its values appended, for example test [1.16, 26]. A depends_on that names a matrix step is rewritten to wait on every expanded combination of that step.

exclude removes specific combinations from the product; include either adds extra keys to combinations that already match or appends a new standalone combination:

steps:
  - name: test
    run: mix test
    strategy:
      matrix:
        os: [ubuntu, macos]
        elixir: ["1.16", "1.17"]
      exclude:
        - os: macos
          elixir: "1.16"
      include:
        - os: ubuntu
          elixir: "1.18"

Expansion is capped at 256 combinations. A configuration that would exceed the cap is rejected at parse time.

Artifacts

Artifact specs preserve build outputs for download after the run. Each entry is a mapping with name and path.

artifacts:
  - name: test-results
    path: _build/test/lib/*/test-results.xml
  - name: coverage
    path: cover/

The parser keeps only name and path from each spec; any other key (including expire_in) is rejected as unknown. Artifact retention is fixed and not configurable per step.

Services

Services are containers started as sidecars before a step runs and stopped after it exits. Use them for test databases, message queues, and similar dependencies.

services is a mapping keyed by service name. Each value is a mapping; image is required and the rest are optional.

steps:
  - name: test
    run: mix test
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: myapp_test
      redis:
        image: redis:7

For each declared service, the step environment receives <NAME>_HOST (always 127.0.0.1) and <NAME>_PORT. The port is taken from an explicit port, the first entry of ports, or a well-known default for recognized images (postgres 5432, mysql/mariadb 3306, redis 6379, memcached 11211, mongo/mongodb 27017, elasticsearch 9200, rabbitmq 5672, minio 9000). Custom env keys are added to the step environment as well. Names are upper-cased, so a service named postgres exposes POSTGRES_HOST and POSTGRES_PORT.

Unknown keys on a service (anything other than image, env, ports, port, command) are rejected.

Validation

The parser validates the whole file before any step runs and reports all errors at once. It rejects:

• Missing, non-list, or empty steps.
• Steps missing name or run, or with empty values for them.
• Wrong types (for example a string where a list is required).
• depends_on referencing a step that does not exist.
• Dependency cycles.
• Duplicate step names.
• prepare without a top-level image.
• A condition that is present but not a non-empty string.
• A service without an image, or with an unknown key.
• A matrix that would expand to more than 256 combinations.
• Unknown keys, with a “did you mean?” suggestion based on edit distance.

For example, timout_seconds produces:

step 'test': unknown key 'timout_seconds' (did you mean 'timeout_seconds'?)

Accepted but not yet implemented

Two step fields are validated structurally but have no runtime effect. They are accepted so existing files keep parsing, and the run is flagged with a warning in the UI.

CI secrets

Secrets are stored encrypted and injected as environment variables at run time. They are never written to logs. Manage them with the CLI:

anvil ci set-secret --name API_KEY --value s3cr3t
anvil ci secrets                          # list names only
anvil ci delete-secret --name API_KEY

Pass --env <environment> to set-secret to scope a secret to a specific environment, and --repo <org/repo> to target a repository other than the one inferred from your current directory.

Reference a secret in a step with ordinary shell syntax:

steps:
  - name: publish
    run: mix hex.publish --yes
    env:
      HEX_API_KEY: $API_KEY

Related pages

• Get started
• CLI reference
• Self-hosted runners
• Webhooks