Downstream
Description
This plugin enables you to trigger builds for other repos for Vela in a pipeline.
Source Code: https://github.com/go-vela/vela-downstream
Registry: https://hub.docker.com/r/target/vela-downstream
Usage
NOTE:
Users should refrain from using latest as the tag for the Docker image.
It is recommended to use a semantically versioned tag instead.
Sample of triggering a downstream build:
steps:
- name: trigger_hello-world
image: target/vela-downstream:latest
pull: always
parameters:
repos:
- octocat/hello-world
server: https://vela-server.localhost
Sample of triggering a downstream build for a specific branch:
steps:
- name: trigger_hello-world
image: target/vela-downstream:latest
pull: always
parameters:
+ branch: main
repos:
- octocat/hello-world
server: https://vela-server.localhost
Sample of triggering a downstream build for a specific event:
steps:
- name: trigger_hello-world
image: target/vela-downstream:latest
pull: always
parameters:
+ event: tag
repos:
- octocat/hello-world
server: https://vela-server.localhost
Sample of triggering a downstream build for a specific status:
NOTE:
You can provide a list of statuses to the plugin.
The first build found matching either of the statuses will be triggered.
steps:
- name: trigger_hello-world
image: target/vela-downstream:latest
pull: always
parameters:
repos:
- octocat/hello-world
server: https://vela-server.localhost
+ status: [ success, failure ]
Sample of triggering a downstream build for multiple repos:
steps:
- name: trigger_multiple
image: target/vela-downstream:latest
pull: always
parameters:
repos:
- octocat/hello-world
+ - go-vela/hello-world
server: https://vela-server.localhost
Sample of triggering a downstream build for multiple repos with different branches:
NOTE:
Use the @ symbol at the end of the org/repo to provide a unique branch per repo.
This will override the value set for the
branch
parameter.
steps:
- name: trigger_multiple
image: target/vela-downstream:latest
pull: always
parameters:
repos:
- - octocat/hello-world
+ - octocat/hello-world@test
- - go-vela/hello-world
+ - go-vela/hello-world@stage
server: https://vela-server.localhost
Secrets
NOTE: Users should refrain from configuring sensitive information in your pipeline in plain text.
Internal
Users can use Vela internal secrets to substitute these sensitive values at runtime:
steps:
- name: trigger_hello-world
image: target/vela-downstream:latest
pull: always
+ secrets: [ downstream_token ]
parameters:
repos:
- octocat/hello-world
server: https://vela-server.localhost
- token: superSecretVelaToken
This example will add the secret to the
trigger_hello-world
step as environment variables:
DOWNSTREAM_TOKEN=<value>
External
The plugin accepts the following files for authentication:
Parameter | Volume Configuration |
---|---|
token | /vela/parameters/downstream/token , /vela/secrets/downstream/token |
Users can use Vela external secrets to substitute these sensitive values at runtime:
steps:
- name: trigger_hello-world
image: target/vela-downstream:latest
pull: always
parameters:
repos:
- octocat/hello-world
server: https://vela-server.localhost
- token: superSecretVelaToken
This example will read the secret value in the volume stored at
/vela/secrets/
Parameters
NOTE:
The plugin supports reading all parameters via environment variables or files.
Any values set from a file take precedence over values set from the environment.
The following parameters are used to configure the image:
Name | Description | Required | Default | Environment Variables |
---|---|---|---|---|
branch | branch to trigger a build on | false | N/A | PARAMETER_BRANCH DOWNSTREAM_BRANCH |
event | event to trigger a build on | true | push | PARAMETER_EVENT DOWNSTREAM_EVENT |
log_level | set the log level for the plugin | true | info | PARAMETER_LOG_LEVEL DOWNSTREAM_LOG_LEVEL |
repos | list of | true | N/A | PARAMETER_REPOS DOWNSTREAM_REPOS |
server | Vela server to communicate with | true | N/A | PARAMETER_SERVER DOWNSTREAM_SERVER |
status | list of statuses to trigger a build on | true | [ success ] | PARAMETER_STATUS DOWNSTREAM_STATUS |
token | token for communication with Vela | true | N/A | PARAMETER_TOKEN DOWNSTREAM_TOKEN |
report_back | whether or not to track downstream build status | false | false | PARAMETER_REPORT_BACK DOWNSTREAM_REPORT_BACK |
target_status | list of statuses to look for from downstream builds | false | [ success ] | PARAMETER_TARGET_STATUS DOWNSTREAM_TARGET_STATUS |
timeout | how long should the plugin wait for downstream builds | false | 30m | PARAMETER_TIMEOUT DOWNSTREAM_TIMEOUT |
continue_on_not_found | continue triggering builds on failure to find one | false | false | PARAMETER_CONTINUE_ON_NOT_FOUND DOWNSTREAM_CONTINUE_ON_NOT_FOUND |
Template
COMING SOON!
Troubleshooting
You can start troubleshooting this plugin by tuning the level of logs being displayed:
steps:
- name: trigger_hello-world
image: target/vela-downstream:latest
pull: always
parameters:
+ log_level: trace
repos:
- octocat/hello-world
server: https://vela-server.localhost
Below are a list of common problems and how to solve them: