Vetrix Docs

Pipeline triggers & branch filtering

This page explains when Vetrix creates a pipeline run, how to control which jobs run on which branches, and how runs relate to the deployments feed.

1. When a pipeline fires

A pipeline run is created automatically whenever a commit is pushed or a merge lands on any branch in the repository. Each push produces exactly one run; the trigger field on that run is set to push.

Vetrix has no top-level on: block. Because on: is listed as an unsupported key (see pipeline-reference.md), adding it produces a parse error. Branch-level filtering belongs on individual jobs via only: / except:, not at the pipeline level.

Trigger values and UI badge labels

trigger value UI badge label
push Push
manual Manual
schedule Scheduled
api API
  • push — automatic run created on every commit or merge.
  • manual — run started by a user clicking Run pipeline in the UI or pressing the retry/run button on an existing run.
  • schedule — run created by a configured pipeline schedule (cron-based; configured under Settings → Schedules).
  • api — run created via the trigger endpoint (POST /api/v1/repos/<owner>/<repo>/pipelines/trigger).

2. How jobs self-gate with only: / except:

Because all jobs see every push, deploy and integration jobs use only: and except: to opt in or out of specific branches. The full evaluation rules and supported glob syntax are defined in pipeline-reference.md; the short version:

  1. If only is non-empty and the current branch does not match any pattern → job is skipped.
  2. If the current branch matches any except pattern → job is skipped.
  3. Otherwise → job runs.

Refer to pipeline-reference.md for the supported glob forms (main, release/*, *-deploy, *). Do not duplicate the rules here.

3. The staging + develop standard

Gate deploy and integration jobs on both staging and develop so they run on neither feature branches nor production branches by default:

stages:
  - test
  - deploy

unit-test:
  stage: test
  image: golang:1.22
  commands:
    - go test ./...

deploy-staging:
  stage: deploy
  image: alpine:3.19
  environment: staging
  only:
    - staging
    - develop
  commands:
    - ./scripts/deploy.sh --env staging

Use except: to carve out specific branches that would otherwise match a broad only: pattern. For example, if you want to run an integration test on all release/* branches except release candidates:

integration-test:
  stage: test
  image: golang:1.22
  only:
    - release/*
  except:
    - release/*-rc
  commands:
    - go test -tags=integration ./...

only: and except: can be combined on the same job; except: is evaluated after only:.

4. Triggers vs the deployments feed

The deployments feed is keyed on environment name and deployment state — not on trigger source. A deploy job running because of a push, a manual run, a schedule, or an API call all produce identically shaped feed events. There is no "merge-triggered" filter in the feed, and none is planned; the feed intentionally treats all trigger sources the same.

Practically: if you watch the feed for your staging environment, you will see every successful deploy regardless of what caused the run. The trigger field lives on the pipeline run, not on the deployment event, so the two data sets answer different questions:

  • Pipeline run list (with trigger badge) → "how was this run started?"
  • Deployments feed → "what is deployed where right now?"

5. Manual runs and retriggers

To start a pipeline run outside of a push:

  • Manual run — go to Pipelines in the repository sidebar and click Run pipeline. Choose the branch and optionally override variables. The run is created with trigger="manual".
  • Retrigger — on any run detail page, click Retry (or Re-run failed jobs) to create a new run from the same commit. The new run also carries trigger="manual".
  • API trigger — send a POST to the trigger endpoint with a bearer token. Useful from external systems (deployment orchestrators, webhook receivers). The run is created with trigger="api".

For a walkthrough of running your first pipeline and reading the run detail page, see first-pipeline.md.