Skip to content

Commit 4ccfa7e

Browse files
ecrupperwass3rw3rk
ecrupper
and
wass3rw3rk
authored
chore: adding several doc updates for v27 (#65)
Co-authored-by: David May <49894298+wass3rw3rk@users.noreply.github.com>
1 parent 0721a03 commit 4ccfa7e

File tree

8 files changed

+120
-48
lines changed

8 files changed

+120
-48
lines changed

‎docs/reference/cli/secret/add.md‎

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -26,21 +26,22 @@ Certain characters may require you to encapsulate your secret with `"` or `'`.
2626

2727
The following parameters are used to configure the command:
2828

29-
| Name | Description | Environment Variables |
30-
| --------------- | ------------------------------------------------ | ----------------------------------------- |
31-
| `org` | name of organization for the secret | `VELA_ORG`, `SECRET_ORG` |
32-
| `repo` | name of repository for the secret | `VELA_REPO`, `SECRET_REPO` |
33-
| `secret.engine` | name of engine that stores the secret | `VELA_ENGINE`. `SECRET_ENGINE` |
34-
| `secret.type` | name of type of secret being stored | `VELA_TYPE`, `SECRET_TYPE` |
35-
| `team` | name of team for the secret | `VELA_TEAM`, `SECRET_TEAM` |
36-
| `name` | name of the secret | `VELA_NAME`, `SECRET_NAME` |
37-
| `value` | value of the secret | `VELA_VALUE`, `SECRET_VALUE` |
38-
| `image` | build image(s) that can access the secret | `VELA_IMAGES`, `SECRET_IMAGES` |
39-
| `event` | build event(s) that can access the secret | `VELA_EVENTS`, `SECRET_EVENTS` |
40-
| `commands` | allows a step with commands to access the secret | `VELA_COMMANDS`, `SECRET_COMMANDS` |
41-
| `substitution` | allows substitution of secret using $\{KEY\} format | `VELA_SUBSTITUTION`, `SECRET_SUBSTITUTION` |
42-
| `file` | name of file used to add the secret(s) | `VELA_FILE`, `SECRET_FILE` |
43-
| `output` | format the output for the secret | `VELA_OUTPUT`, `SECRET_OUTPUT` |
29+
| Name | Description | Environment Variables |
30+
| --------------- | ------------------------------------------------ | ----------------------------------------- |
31+
| `org` | name of organization for the secret | `VELA_ORG`, `SECRET_ORG` |
32+
| `repo` | name of repository for the secret | `VELA_REPO`, `SECRET_REPO` |
33+
| `secret.engine` | name of engine that stores the secret | `VELA_ENGINE`. `SECRET_ENGINE` |
34+
| `secret.type` | name of type of secret being stored | `VELA_TYPE`, `SECRET_TYPE` |
35+
| `team` | name of team for the secret | `VELA_TEAM`, `SECRET_TEAM` |
36+
| `name` | name of the secret | `VELA_NAME`, `SECRET_NAME` |
37+
| `value` | value of the secret | `VELA_VALUE`, `SECRET_VALUE` |
38+
| `image` | build image(s) that can access the secret | `VELA_IMAGES`, `SECRET_IMAGES` |
39+
| `event` | build event(s) that can access the secret | `VELA_EVENTS`, `SECRET_EVENTS` |
40+
| `commands` | allows a step with commands to access the secret | `VELA_COMMANDS`, `SECRET_COMMANDS` |
41+
| `substitution` | allows substitution of secret using $\{KEY\} format | `VELA_SUBSTITUTION`, `SECRET_SUBSTITUTION` |
42+
| `repo-allowlist` | add repositories to secret scope | `VELA_REPO_ALLOWLIST`, `SECRET_REPO_ALLOWLIST` |
43+
| `file` | name of file used to add the secret(s) | `VELA_FILE`, `SECRET_FILE` |
44+
| `output` | format the output for the secret | `VELA_OUTPUT`, `SECRET_OUTPUT` |
4445

4546
:::tip
4647
This command also supports setting the following parameters via a configuration file:

‎docs/reference/cli/secret/update.md‎

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -19,21 +19,22 @@ For more information, you can run `vela update secret --help`.
1919

2020
The following parameters are used to configure the command:
2121

22-
| Name | Description | Environment Variables |
23-
| --------------- | ------------------------------------------------ | ----------------------------------------- |
24-
| `org` | name of organization for the secret | `VELA_ORG`, `SECRET_ORG` |
25-
| `repo` | name of repository for the secret | `VELA_REPO`, `SECRET_REPO` |
26-
| `secret.engine` | name of engine that stores the secret | `VELA_ENGINE`. `SECRET_ENGINE` |
27-
| `secret.type` | name of type of secret being stored | `VELA_TYPE`, `SECRET_TYPE` |
28-
| `team` | name of team for the secret | `VELA_TEAM`, `SECRET_TEAM` |
29-
| `name` | name of the secret | `VELA_NAME`, `SECRET_NAME` |
30-
| `value` | value of the secret | `VELA_VALUE`, `SECRET_VALUE` |
31-
| `image` | build image(s) that can access the secret | `VELA_IMAGES`, `SECRET_IMAGES` |
32-
| `event` | build event(s) that can access the secret | `VELA_EVENTS`, `SECRET_EVENTS` |
33-
| `commands` | allows a step with commands to access the secret | `VELA_COMMANDS`, `SECRET_COMMANDS` |
34-
| `substitution` | allows substitution of secret using $\{KEY\} format | `VELA_SUBSTITUTION`, `SECRET_SUBSTITUTION` |
35-
| `file` | name of file used to add the secret(s) | `VELA_FILE`, `SECRET_FILE` |
36-
| `output` | format the output for the secret | `VELA_OUTPUT`, `SECRET_OUTPUT` |
22+
| Name | Description | Environment Variables |
23+
| --------------- | ------------------------------------------------ | ----------------------------------------- |
24+
| `org` | name of organization for the secret | `VELA_ORG`, `SECRET_ORG` |
25+
| `repo` | name of repository for the secret | `VELA_REPO`, `SECRET_REPO` |
26+
| `secret.engine` | name of engine that stores the secret | `VELA_ENGINE`. `SECRET_ENGINE` |
27+
| `secret.type` | name of type of secret being stored | `VELA_TYPE`, `SECRET_TYPE` |
28+
| `team` | name of team for the secret | `VELA_TEAM`, `SECRET_TEAM` |
29+
| `name` | name of the secret | `VELA_NAME`, `SECRET_NAME` |
30+
| `value` | value of the secret | `VELA_VALUE`, `SECRET_VALUE` |
31+
| `image` | build image(s) that can access the secret | `VELA_IMAGES`, `SECRET_IMAGES` |
32+
| `event` | build event(s) that can access the secret | `VELA_EVENTS`, `SECRET_EVENTS` |
33+
| `commands` | allows a step with commands to access the secret | `VELA_COMMANDS`, `SECRET_COMMANDS` |
34+
| `substitution` | allows substitution of secret using $\{KEY\} format | `VELA_SUBSTITUTION`, `SECRET_SUBSTITUTION` |
35+
| `repo-allowlist` | add repositories to secret scope | `VELA_REPO_ALLOWLIST`, `SECRET_REPO_ALLOWLIST` |
36+
| `file` | name of file used to add the secret(s) | `VELA_FILE`, `SECRET_FILE` |
37+
| `output` | format the output for the secret | `VELA_OUTPUT`, `SECRET_OUTPUT` |
3738

3839
:::tip
3940
This command also supports setting the following parameters via a configuration file:

‎docs/reference/environment/variables.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,8 @@ The following table includes variables only available when the step `id_request`
143143
| `VELA_REPO_TOPICS` | `cloud,security` | comma-separated list of repository topics |
144144
| `VELA_REPO_TRUSTED` | `false` | trusted setting for the repository |
145145
| `VELA_REPO_VISIBILITY` | `public` | visibility setting for the repository |
146+
| `VELA_REPO_INSTALL_ID` | `100` | scm app install id (if installed) |
147+
| `VELA_REPO_CUSTOM_PROPS` | `{"foo":"bar","foob":"baz"}` | custom properties assigned to repository |
146148

147149
#### User Environment Variables
148150

‎docs/reference/yaml/git.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: "Git"
3+
linkTitle: "Git"
4+
weight: 3
5+
description: >
6+
YAML keys for git block
7+
---
8+
9+
The `git` key is intended to be used to add additional scope to app installation tokens.
10+
11+
## Keys
12+
13+
| Key | Required | Type | Description |
14+
| --------------- | -------- | ----------- | ----------------------------------------------------------------- |
15+
| `token` | N | (see below) | Token scope settings for `VELA_GIT_TOKEN` variable |
16+
17+
### Usage
18+
19+
#### The `token` key
20+
21+
| Key | Required | Type | Description |
22+
| --------------- | -------- | ----------- | ----------------------------------------------------------------- |
23+
| `repositories` | N | slice | Add repositories to receive permissions set for token |
24+
| `permissions` | N | map | Define permissions for the token (checks, contents) |
25+
26+
The `token` key can be used to generate an installation token so long as the repo has the Vela GitHub App installed.
27+
28+
```yaml
29+
---
30+
# This setting will generate an installation token with write contents and write checks permissions for
31+
# the repositories listed below as well as the repository running the build: VELA_GIT_TOKEN
32+
git:
33+
token:
34+
repositories:
35+
- alpha/beta
36+
- gamma/delta
37+
permissions:
38+
checks: write
39+
contents: write
40+
```
41+
42+
:::note
43+
This token will only be generated if the repository owner also has access to the repositories listed.
44+
:::

‎docs/usage/open_id_connect.md‎

Lines changed: 26 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -74,25 +74,33 @@ The `id_request` key being set to _anything_ will result in the injection of the
7474

7575
```json
7676
{
77-
"build_number": 42,
78-
"build_id": 100,
79-
"actor": "Octocat",
80-
"actor_scm_id": "1",
81-
"repo": "Octocat/vela-testing",
82-
"token_type": "ID",
83-
"image": "golang:1.22.4",
84-
"request": "yes",
85-
"commands": true,
86-
"event": "pull_request:opened",
87-
"ref": "refs/heads/main",
88-
"sha": "15b17a5751dd2fd04a7b4ca056063dc876984073",
89-
"iss": "https://vela-server.com/_services/token",
90-
"sub": "repo:Octocat/vela-testing:ref:refs/heads/main:event:pull_request",
91-
"aud": [
77+
"sub": "repo:Octocat/vela-testing:ref:refs/heads/main:event:pull_request",
78+
"exp": 1717699924,
79+
"iat": 1717699624,
80+
"iss": "https://vela-server.com/_services/token",
81+
"aud": [
9282
"artifactory"
93-
],
94-
"exp": 1717699924,
95-
"iat": 1717699624
83+
],
84+
"branch": "main",
85+
"build_number": 42,
86+
"build_id": 100,
87+
"repo": "Octocat/vela-testing",
88+
"pull_fork": "false",
89+
"token_type": "ID",
90+
"actor": "Octocat",
91+
"actor_scm_id": "1",
92+
"commands": "true",
93+
"image": "golang:1.22.4",
94+
"image_name": "golang",
95+
"image_tag": "1.22.4",
96+
"request": "yes",
97+
"event": "pull_request:opened",
98+
"sha": "15b17a5751dd2fd04a7b4ca056063dc876984073",
99+
"ref": "refs/heads/main",
100+
"custom_properties": {
101+
"prop1": "foo",
102+
"prop2": "bar"
103+
}
96104
}
97105
```
98106

‎docs/usage/outputs.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,12 @@ steps:
8181

8282
After the first step is complete, the logs will mask any mention of the `$API_KEY`.
8383

84+
### Base64 Option
85+
86+
If the output value contains special characters or newlines, it may be a good option to `base64` encode the value. Rather than encoding, writing to `$VELA_OUTPUTS`, and decoding manually in another step, Vela has a `$VELA_BASE64_OUTPUTS` (and `$VELA_MASKED_BASE64_OUTPUTS`) which will automatically decode the values for future steps.
87+
88+
Note: the user will still need to encode the value when writing to this file.
89+
8490
### Limitations
8591

8692
- Outputs can only be used as environment variables (`$VAR`) or substitution variables (`${VAR}`). Inline Go templating (`{{ .VAR }}`) is done at compile time and will not dynamically be evaluated.

‎docs/usage/secrets.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,10 @@ secrets:
9393
type: shared
9494
```
9595

96+
#### Allowlists
97+
98+
Both shared and org secrets can have repository allowlists. These can be configured in the UI and CLI. These allowlists will scope access to specific repositories.
99+
96100
### Protecting Secrets
97101

98102
Learn the best practices for keeping your Vela secrets safe.

‎docs/usage/troubleshooting.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,12 @@ This behavior indicates the number of `running` builds for the system is greater
119119

120120
Unfortunately, the only way to resolve the issue is to wait until a worker becomes available to run your build.
121121

122+
### Queue length exceeds configured limit, please wait for the queue to decrease in size before retrying
123+
124+
This error is given in response to a build restart request of a `pending` build whenever the queue is larger than the configured limit by the platform admins.
125+
126+
This is a measure to prevent queue bloat from builds that are already in the queue.
127+
122128
### Context Deadline Exceeded
123129

124130
![Context Deadline Exceeded](/img/troubleshooting/context_deadline_exceeded.png)

0 commit comments

Comments
 (0)