From c194637d2ca20a38520cd123f434cc03ded63def Mon Sep 17 00:00:00 2001 From: Jordan Christiansen Date: Mon, 12 Aug 2024 09:37:11 -0500 Subject: [PATCH] Document what kind of token is required (#138) A token must: 1. Be a Github personal access token 2. Be tied to a user that Vela knows about 3. Belong to a user that has write permission on the repos --- DOCS.md | 39 +++++++++++++++++++++++++++------------ 1 file changed, 27 insertions(+), 12 deletions(-) diff --git a/DOCS.md b/DOCS.md index ec1d4d6..5d70379 100644 --- a/DOCS.md +++ b/DOCS.md @@ -115,6 +115,10 @@ steps: > **NOTE:** Users should refrain from configuring sensitive information in your pipeline in plain text. +A Github personal access token is required. +The token must be tied to a user that exists in Vela, that is, the user has logged into Vela at least once. +Additionally, the user must have write access in Github to both this repo and any repos you intend to trigger. + ### Internal Users can use [Vela internal secrets](https://go-vela.github.io/docs/tour/secrets/) to substitute these sensitive values at runtime: @@ -170,18 +174,18 @@ steps: 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` | +| 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` | Github personal access token of an existing Vela user | `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 @@ -205,3 +209,14 @@ steps: ``` Below are a list of common problems and how to solve them: + +### `unable to authenticate: user not found` + +Vela doesn't know about the user that owns the token, even though the user exists in Github and the token may be valid. +Log into Vela as this user once to fix the issue. + +### `unable to restart build myorg/myrepo/1234` + +Vela doesn't have permission to restart the build with the given token. +Make sure the user that owns the token has write access to the repo that this .vela.yml is inside as well as any repos you want to trigger builds for. +Admin access on these repos is not required.