Learn how to execute a pipeline locally.


$ vela exec pipeline <parameters...> <arguments...>


The following parameters are used to configure the command:

Ruleset Parameters

NameDescriptionEnvironment Variables
branchthe build branch for the pipelineVELA_BRANCH, PIPELINE_BRANCH
commentthe build comment for the pipelineVELA_COMMENT, PIPELINE_COMMENT
eventthe build event for the pipelineVELA_EVENT, PIPELINE_EVENT
tagthe build tag for the pipelineVELA_TAG, PIPELINE_TAG
targetthe build target for the pipelineVELA_TARGET, PIPELINE_TARGET
file-changesetthe build file changeset for the pipelineVELA_FILE_CHANGESET, FILE_CHANGESET

Repo Settings Parameters

NameDescriptionEnvironment Variables
orgprovide the organization for the pipelineVELA_ORG, PIPELINE_ORG
repoprovide the repository for the pipelineVELA_REPO, PIPELINE_REPO
pipeline-typeprovide the repository pipeline typeVELA_PIPELINE_TYPE, PIPELINE_TYPE

Template Parameters

NameDescriptionEnvironment Variables
compiler.github.tokenPAT for accessing GitHub sourced templatesVELA_COMPILER_GITHUB_TOKEN, COMPILER_GITHUB_TOKEN
compiler.github.urlURL for accessing GitHub sourced templatesVELA_COMPILER_GITHUB_URL, COMPILER_GITHUB_URL
template-filelist of local templates in form of :VELA_TEMPLATE_FILE, PIPELINE_TEMPLATE_FILE
max-template-depthmaximum depth for requesting nested templatesVELA_MAX_TEMPLATE_DEPTH, MAX_TEMPLATE_DEPTH

Environment Parameters

NameDescriptionEnvironment Variables
env-fileBool value for whether or not to source from an env file (default .env)VELA_ENV_FILE, ENV_FILE
env-file-pathPath to override default .env sourcing of environmentVELA_ENV_FILE_PATH, ENV_FILE_PATH
local-envBool value for whether or not to onboard your local environmentONBOARD_LOCAL_ENV, LOCAL_ENV
env-varslist of environment variables to include in form of =VELA_ENV_VARS

Other Parameters

NameDescriptionEnvironment Variables
outputformat the output in json, spew or yamlVELA_OUTPUT, PIPELINE_OUTPUT
filename of the file for the pipelineVELA_FILE, PIPELINE_FILE
pathpath to the file for the pipelineVELA_PATH, PIPELINE_PATH
localenables mounting local directory to pipelineVELA_LOCAL, PIPELINE_LOCAL
volumeprovide list of local volumes to mountVELA_VOLUMES, PIPELINE_VOLUMES


Unless the local-env flag is supplied, the vela exec pipeline command will execute without any set environment. Instead, users are encouraged to supply their own environment variables in the form of an env file (e.g. --env-file OR --env-file-path custom.env).

Many plugins, Starlark/Go templates, and other build resources depend on Vela-injected environment variables, such as VELA_BUILD_COMMIT. These variables will have to be supplied by the user, as there is no way for the compiler to determine these values locally.


The Vela Exec command does not have access to any secret you have stored in Vela or any other attached secret store.

Environment variables can be set for the command by using the env-vars flag, ie vela exec pipeline --env-vars MY_SECRET=foo. They can also be set with the env-file or local-env flags.

For example, if a pipeline is using the kaniko plugin, it may require the secret kaniko_password, which can be provided with vela exec pipeline --env-vars KANIKO_PASSWORD=mypass.



vela exec pipeline


[step: init] > Inspecting runtime network...
[step: init] $ docker network inspect localOrg_localRepo_1
 "Name": "localOrg_localRepo_1",
 "Id": "cf204e6081cd4c10e3a285e7545790152afca05991c2dc67534f496844c1d274",
 "Created": "2021-06-01T19:37:35.4772628Z",
 "Scope": "local",
 "Driver": "bridge",
 "EnableIPv6": false,
 "IPAM": {
  "Driver": "default",
  "Options": null,
  "Config": [
    "Subnet": "",
    "Gateway": ""
 "Internal": false,
 "Attachable": false,
 "Ingress": false,
 "ConfigFrom": {
  "Network": ""
 "ConfigOnly": false,
 "Containers": {},
 "Options": {},
 "Labels": {}

[step: init] > Inspecting runtime volume...
[step: init] $ docker volume inspect localOrg_localRepo_1
 "CreatedAt": "2021-06-01T19:37:35Z",
 "Driver": "local",
 "Labels": null,
 "Mountpoint": "/var/lib/docker/volumes/localOrg_localRepo_1/_data",
 "Name": "localOrg_localRepo_1",
 "Options": null,
 "Scope": "local"

[step: init] > Pulling service images...
[step: init] > Pulling stage images...
[step: init] > Pulling step images...
[step: init] $ docker image inspect alpine:latest

[step: hello Vela] $ echo "hello Vela!"
[step: hello Vela] hello Vela!

Complex Samples

Below are several examples using the following Vela pipeline + template


version: "1"

  - name: tmpl
    source: git.example.com/cloud/vela-templates/kaniko.yml@main
    type: github
  - name: testing
    image: alpine:latest
      - echo hello
  - name: file path ruleset
    image: alpine:latest
      matcher: regexp
      path: [ src/* ]
      - echo ran

  - name: docker build
      name: tmpl
        repo: docker.example.com/octocat/hello-world

kaniko.yml Template

version: "1"

  template: true

  REPO: {{ .repo }}

  - name: docker_username
    key: octocat/docker_username
    engine: native
    type: org
  - name: docker_password
    key: octocat/docker_password
    engine: native
    type: org

  - name: Build and Publish
    image: target/vela-kaniko:latest
    secrets: [ docker_username, docker_password ]
      registry: docker.example.com
      repo: ${REPO}

Remote Template + Local Environment Onboarding

$ DOCKER_USERNAME=octocat DOCKER_PASSWORD=abc123 VELA_BUILD_COMMIT=1a2b3c vela exec pipeline --ct <GITHUB_PAT> --cgu https://git.example.com --local-env

Note: --local-env onboards the entire bash environment. To load specific environment variables, use --env-vars:

$ vela exec pipeline --ct <GITHUB_PAT> --cgu https://git.example.com --env-vars DOCKER_USERNAME=octocat,DOCKER_PASSWORD=abc123,VELA_BUILD_COMMIT=1a2b3c

Template Override

$ vela exec pipeline --template-file tmpl:path/to/template.yml --env-vars DOCKER_USERNAME=octocat,DOCKER_PASSWORD=abc123,VELA_BUILD_COMMIT=1a2b3c

Environment File


$ vela exec pipeline --ct <GITHUB_PAT> --cgu https://git.example.com --env-file


$ vela exec pipeline --ct <GITHUB_PAT> --cgu https://git.example.com --env-file-path vela_exec.env

Path Ruleset Inclusion

In order to execute steps with rulesets, be sure to include all necessary flags that match the rules

$ vela exec pipeline --ct <GITHUB_PAT> --cgu https://git.example.com --env-file --file-changeset src/main.go

Other rules: --branch, --event, --comment, --tag, --target

Last modified December 20, 2023: fix: company.com -> example.com (#392) (9b1aa7a3)