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 / names to trigger a build on	`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:

Last modified March 8, 2022: feat(openssh): Add SSH & SCP documentation (#287) (fe29de8f)