Create your first pipeline

This tutorial walks you through creating, pushing, and verifying a Vetrix CI/CD pipeline from scratch. Each step describes exactly what you should see in the UI or terminal so you can confirm things are working as expected.

Prerequisites

• Complete Getting Started — you need a repository with at least one branch and push access.
• Your repository must use one of the discovery paths Vetrix probes. See the discovery-path list in the Pipeline YAML Reference for the full ordered list; this tutorial uses .ci/pipeline.yml.

Step 1 — Add .ci/pipeline.yml

Create the directory and file at your repository root:

mkdir -p .ci

Paste the following into .ci/pipeline.yml:

stages:
  - build
  - test

build:
  stage: build
  image: alpine:3.19
  commands:
    - echo "Building project"
    - echo "Ref: ${CI_COMMIT_REF_NAME}  SHA: ${CI_COMMIT_SHA}"

test:
  stage: test
  image: alpine:3.19
  commands:
    - echo "Running tests"
    - echo "All tests passed"

Key points:

• stages lists two stages; jobs in build complete before test begins.
• Each job is a top-level key — there is no wrapping jobs: block.
• Commands use commands:, not script: (which is unsupported — see Troubleshooting).
• ${CI_COMMIT_REF_NAME} and ${CI_COMMIT_SHA} are predefined variables the runner injects automatically.

Step 2 — Push to a branch

Commit and push the file to a branch:

git checkout -b develop
git add .ci/pipeline.yml
git commit -m "ci: add initial pipeline"
git push origin develop

What you should see: The push completes normally. No manual trigger is needed — Vetrix detects the push and queues a pipeline run automatically.

Step 3 — Watch the run auto-trigger

Navigate to your repository and open the Pipelines tab.

What you should see:

• A new row appears in the pipeline list within a few seconds.
• Status column shows Running (a spinner or progress indicator).
• Trigger badge reads Push.
• Ref column shows develop.

If no row appears, verify that .ci/pipeline.yml exists at the exact repository root (not in a subdirectory) and that the filename matches one of the supported discovery paths.

Step 4 — Open the run and stream logs

Click the pipeline row to open the run detail page.

What you should see:

• The page header reads Triggered by push to develop.
• Two stages are shown: build then test, each with its own job card.
• Click a job card to expand live log output. While the job is running, log lines stream in real time.
• Once both jobs finish, the pipeline status updates to Success (green).

Step 5 — Gate a deploy job with only:

Add a third job that only runs on staging or develop branches:

stages:
  - build
  - test
  - deploy

build:
  stage: build
  image: alpine:3.19
  commands:
    - echo "Building project"
    - echo "Ref: ${CI_COMMIT_REF_NAME}  SHA: ${CI_COMMIT_SHA}"

test:
  stage: test
  image: alpine:3.19
  commands:
    - echo "Running tests"
    - echo "All tests passed"

deploy-staging:
  stage: deploy
  image: alpine:3.19
  only:
    - staging
    - develop
  commands:
    - echo "Deploying to staging"

Commit and push:

git add .ci/pipeline.yml
git commit -m "ci: add gated deploy stage"
git push origin develop

What you should see (push to develop): All three jobs appear — build, test, and deploy-staging. The pipeline completes with Success.

Now push the same file to a feature branch:

git checkout -b feature/my-feature
git push origin feature/my-feature

What you should see (push to a feature branch): The pipeline still runs, but deploy-staging shows Skipped — the branch feature/my-feature does not match staging or develop, so the runner bypasses the job per the only: filter.

Step 6 — Verify predefined variables in job logs

Open any completed job and inspect the log output.

What you should see: Lines from the build job similar to:

Ref: develop  SHA: a1b2c3d4e5f6...

CI_COMMIT_REF_NAME contains the branch name and CI_COMMIT_SHA contains the full commit hash. These are injected by the runner into every job container — you do not need to declare them yourself. For the full list of predefined variables see the Pipeline YAML Reference — Predefined variables.

Troubleshooting

Pipeline never appears after push / trigger endpoint returns 422

Vetrix probes these paths in order and returns 422 if none resolves, naming every path it checked:

1. .ci/pipeline.yml
2. .vetrix/pipeline.yml
3. vetrix-ci.yml

Check that your file is committed to the repository root and matches one of these names exactly (case-sensitive).

Parse error mentioning on:, script:, or jobs:

These keys come from GitHub Actions and GitLab CI and are not supported. Vetrix detects them at parse time and returns a human-readable error:

Unsupported key	Vetrix equivalent
script: (job-level)	commands:
jobs: (top-level wrapper)	Top-level job keys directly under the document root
on: (top-level)	No equivalent — use only: / except: on each job
steps: (job-level)	commands:
runs-on: (job-level)	image:

Job skipped unexpectedly

If a job has an only: list and the current branch is not in that list, the job is skipped. Check the branch name against the patterns in only:. Glob syntax supports * (single segment) — see the branch filter reference.

Next steps

• Pipeline YAML Reference — full schema: all job fields, variable interpolation, artifacts, secrets, and environments.
• Pipeline Triggers — manual triggers, scheduled runs, API triggers, and the full trigger badge reference.