From ff080a42066241a138f555caa9422e2e19e29512 Mon Sep 17 00:00:00 2001 From: Tim Huynh Date: Thu, 5 Mar 2026 11:20:50 -0600 Subject: [PATCH 1/4] artifact doc --- docs/usage/artifacts.md | 94 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 docs/usage/artifacts.md diff --git a/docs/usage/artifacts.md b/docs/usage/artifacts.md new file mode 100644 index 0000000..37eb56c --- /dev/null +++ b/docs/usage/artifacts.md @@ -0,0 +1,94 @@ +--- +title: "Artifacts" +toc: true +description: > + Learn how to collect and store build artifacts from your pipeline steps. +--- + +:::tip +Artifacts functionality is only available in the Docker runtime and requires the Vela server to be configured with an S3-compatible object storage backend. +::: + +### What are artifacts? + +Artifacts are files produced by a pipeline step — such as test reports, screenshots, videos, or build binaries — that you want to preserve after the build completes. By declaring `artifacts.paths` on a step, Vela will automatically collect matching files from the step's workspace and upload them to configured object storage once the step finishes. + +### Usage + +Add an `artifacts` block to any step with a `paths` list of glob patterns: + +```yaml +version: "1" + +steps: + - name: cypress_tests + image: cypress/browsers:node-20.16.0-chrome-127.0.6533.119-1-ff-129.0.1-edge-127.0.2651.98-1 + commands: + - npm install + - npm run cy:run + artifacts: + paths: + - cypress/screenshots/**/*.png + - cypress/videos/**/*.mp4 + - test-results/*.xml + - coverage/**/*.xml +``` + +After the step completes, Vela searches the step's workspace for any files matching those patterns and uploads them to object storage. The files are stored under the path: + +``` +{org}/{repo}/{build_number}/{filename} +``` + +#### Another example — Go test reports + +```yaml +version: "1" + +steps: + - name: test + image: golang:latest + commands: + - go test -v ./... 2>&1 | tee test-output.txt + - go test -json ./... > test-results.json + artifacts: + paths: + - test-output.txt + - test-results.json +``` + +### Downloading artifacts + +Once a build has completed, artifacts can be downloaded from the **Artifacts** tab on the build page in the Vela UI. Each artifact is listed by filename with a download link backed by a temporary presigned URL, allowing direct access to the file from object storage without requiring any additional credentials. + +### File size limits + +The worker enforces limits on artifact uploads to prevent runaway storage usage: + +- **Per-file limit** — files exceeding the configured per-file size limit are skipped. +- **Per-build limit** — once the total uploaded bytes for a build reaches the configured build-level limit, remaining files are skipped. + +Files that are skipped due to size limits are logged at the worker level. Contact your Vela administrator for the limits configured on your installation. + +### Server configuration + +Artifacts require the Vela server to be configured with an S3-compatible object storage backend (e.g. MinIO). The following environment variables must be set on the server: + +| Variable | Description | +|---|---| +| `VELA_STORAGE_DRIVER` | Object storage driver (e.g. `minio`) | +| `VELA_STORAGE_ADDRESS` | Storage endpoint (e.g. `https://minio.example.com`) | +| `VELA_STORAGE_ACCESS_KEY` | Storage access key | +| `VELA_STORAGE_SECRET_KEY` | Storage secret key | +| `VELA_STORAGE_BUCKET` | Bucket name to store artifacts in | +| `VELA_STORAGE_USE_SSL` | Set to `true` to enable SSL (default: `false`) | + +If storage is not enabled on the server, any step with `artifacts.paths` will be skipped silently and the build will continue normally. + +### Limitations + +- Artifacts are only supported in the **Docker runtime**. The Kubernetes runtime does not support artifact collection. +- Glob patterns are evaluated relative to the step's workspace root. Only regular files are collected — directories and symlinks are excluded. +- Only the **filename** (basename) is preserved in storage, not the full path. If two different paths resolve to files with the same filename, only one will be stored. +- Artifacts are not available for download until the step that declares them has completed. +- The `artifacts` key is supported on `steps` only, not on `services`. From 81b2b356bbf041f522fcf26da56b4eed7277e7f8 Mon Sep 17 00:00:00 2001 From: Tim Huynh Date: Thu, 5 Mar 2026 11:38:09 -0600 Subject: [PATCH 2/4] add env enable --- docs/usage/artifacts.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/usage/artifacts.md b/docs/usage/artifacts.md index 37eb56c..7932b70 100644 --- a/docs/usage/artifacts.md +++ b/docs/usage/artifacts.md @@ -74,14 +74,15 @@ Files that are skipped due to size limits are logged at the worker level. Contac Artifacts require the Vela server to be configured with an S3-compatible object storage backend (e.g. MinIO). The following environment variables must be set on the server: -| Variable | Description | -|---|---| -| `VELA_STORAGE_DRIVER` | Object storage driver (e.g. `minio`) | -| `VELA_STORAGE_ADDRESS` | Storage endpoint (e.g. `https://minio.example.com`) | -| `VELA_STORAGE_ACCESS_KEY` | Storage access key | -| `VELA_STORAGE_SECRET_KEY` | Storage secret key | -| `VELA_STORAGE_BUCKET` | Bucket name to store artifacts in | -| `VELA_STORAGE_USE_SSL` | Set to `true` to enable SSL (default: `false`) | +| Variable | Description | +|---------------------------|-----------------------------------------------------| +| `VELA_STORAGE_ENABLE` | Set to `true` to enable storage (default: `false`) | +| `VELA_STORAGE_DRIVER` | Object storage driver (e.g. `minio`) | +| `VELA_STORAGE_ADDRESS` | Storage endpoint (e.g. `https://minio.example.com`) | +| `VELA_STORAGE_ACCESS_KEY` | Storage access key | +| `VELA_STORAGE_SECRET_KEY` | Storage secret key | +| `VELA_STORAGE_BUCKET` | Bucket name to store artifacts in | +| `VELA_STORAGE_USE_SSL` | Set to `true` to enable SSL (default: `false`) | If storage is not enabled on the server, any step with `artifacts.paths` will be skipped silently and the build will continue normally. From 1f784538daf38335c196c35c617054fcd6717724 Mon Sep 17 00:00:00 2001 From: Tim Huynh Date: Thu, 5 Mar 2026 13:36:51 -0600 Subject: [PATCH 3/4] add file size doc --- docs/usage/artifacts.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/usage/artifacts.md b/docs/usage/artifacts.md index 7932b70..2b1372b 100644 --- a/docs/usage/artifacts.md +++ b/docs/usage/artifacts.md @@ -68,6 +68,13 @@ The worker enforces limits on artifact uploads to prevent runaway storage usage: - **Per-file limit** — files exceeding the configured per-file size limit are skipped. - **Per-build limit** — once the total uploaded bytes for a build reaches the configured build-level limit, remaining files are skipped. +These limits are configured on the worker via the following environment variables: + +| Variable | Description | +|--------------------------------------|------------------------------------------------------------------------------------------| +| `VELA_STORAGE_FILE_SIZE_LIMIT` | Maximum size (in MB) for a single artifact file. Set to `0` for no limit. | +| `VELA_STORAGE_BUILD_FILE_SIZE_LIMIT` | Maximum total size (in MB) of all artifacts for a single build. Set to `0` for no limit. | + Files that are skipped due to size limits are logged at the worker level. Contact your Vela administrator for the limits configured on your installation. ### Server configuration From 24ac21b189063ab234f7bad82e2d62d362005632 Mon Sep 17 00:00:00 2001 From: timhuynh94 Date: Thu, 2 Apr 2026 16:00:11 -0500 Subject: [PATCH 4/4] add to installation and yaml reference --- docs/reference/installation/server/server.md | 83 ++++++++++++++++++++ docs/reference/installation/worker/worker.md | 34 ++++++++ docs/reference/yaml/steps.md | 49 ++++++++++++ 3 files changed, 166 insertions(+) diff --git a/docs/reference/installation/server/server.md b/docs/reference/installation/server/server.md index 4723817..6ba0e6c 100644 --- a/docs/reference/installation/server/server.md +++ b/docs/reference/installation/server/server.md @@ -1018,3 +1018,86 @@ This variable sets OTel tracestate [(span) attributes](https://www.w3.org/TR/tra :::note This variable has no default value. ::: + +## Storage (Artifacts) + +This section contains configuration variables for enabling S3-compatible object storage on the server. Object storage is required for the [artifacts feature](/docs/usage/artifacts.md), which allows pipeline steps to collect and preserve build output files (e.g. test reports, screenshots, binaries). + +When storage is enabled, the server manages presigned download URLs that are surfaced in the Vela UI under the **Artifacts** tab of each build. + +If `VELA_STORAGE_ENABLE` is not set to `true`, any pipeline step that declares `artifacts.paths` will be skipped silently and the build will continue normally. + +### VELA_STORAGE_ENABLE + +This variable enables S3-compatible object storage support on the server. + +The variable should be provided as a `boolean`. + +:::note +This variable has a default value of `false`. +::: + +### VELA_STORAGE_DRIVER + +This variable sets the object storage driver. + +The variable should be provided as a `string`. + +:::note +The possible options to provide for this variable are: + +* `minio` +::: + +### VELA_STORAGE_ADDRESS + +This variable sets a fully qualified URL to the object storage endpoint. + +The variable should be provided as a `string` (e.g. `https://minio.example.com`). + +:::note +The address must include a scheme (`https://` or `http://`) and must **not** contain a trailing slash. +::: + +### VELA_STORAGE_ACCESS_KEY + +This variable sets the access key (username) used to authenticate with the object storage backend. + +The variable should be provided as a `string`. + +### VELA_STORAGE_SECRET_KEY + +This variable sets the secret key (password) used to authenticate with the object storage backend. + +The variable should be provided as a `string`. + +### VELA_STORAGE_BUCKET + +This variable sets the name of the bucket in which artifacts will be stored. + +The variable should be provided as a `string`. + +### VELA_STORAGE_USE_SSL + +This variable controls whether the server communicates with the object storage backend over SSL/TLS. + +The variable should be provided as a `boolean`. + +:::note +This variable has a default value of `false`. +::: + +#### Example: enabling storage with MinIO + +```shell +$ docker run \ + --env=VELA_STORAGE_ENABLE=true \ + --env=VELA_STORAGE_DRIVER=minio \ + --env=VELA_STORAGE_ADDRESS=https://minio.example.com \ + --env=VELA_STORAGE_ACCESS_KEY= \ + --env=VELA_STORAGE_SECRET_KEY= \ + --env=VELA_STORAGE_BUCKET=vela \ + --env=VELA_STORAGE_USE_SSL=true \ + target/vela-server:latest +``` + diff --git a/docs/reference/installation/worker/worker.md b/docs/reference/installation/worker/worker.md index 35e31fd..8cfd2c4 100644 --- a/docs/reference/installation/worker/worker.md +++ b/docs/reference/installation/worker/worker.md @@ -301,4 +301,38 @@ The possible options to provide for this variable are: * `1.3` ::: +## Storage (Artifacts) + +This section contains configuration variables that control how the worker handles artifact uploads. Artifacts are files declared by pipeline steps via the `artifacts.paths` YAML key and are collected after each step completes, then uploaded to the object storage backend configured on the server. + +These limits are enforced on the worker independently of the server-side storage configuration. Setting either variable to `0` disables the corresponding limit entirely. + +### VELA_STORAGE_FILE_SIZE_LIMIT + +This variable sets the maximum size (in MB) allowed for a single artifact file upload. + +Files exceeding this limit are skipped and logged at the worker level; the build continues normally. + +The variable can be provided as an `integer`. + +:::note +This variable has a default value of `100` (MB). + +Set to `0` for no per-file size limit. +::: + +### VELA_STORAGE_BUILD_FILE_SIZE_LIMIT + +This variable sets the maximum total size (in MB) of all artifact file uploads for a single build. + +Once the cumulative size of uploaded artifacts for a build reaches this limit, any remaining files are skipped and logged at the worker level. + +The variable can be provided as an `integer`. + +:::note +This variable has a default value of `500` (MB). + +Set to `0` for no per-build total size limit. +::: + diff --git a/docs/reference/yaml/steps.md b/docs/reference/yaml/steps.md index f03e5d9..d34c952 100644 --- a/docs/reference/yaml/steps.md +++ b/docs/reference/yaml/steps.md @@ -37,6 +37,7 @@ steps: | `detach` | N | []string | Run the container in a detached (headless) state. | | `ulimits` | N | string | Set the user limits for the container. | | `user` | N | string | Set the user for the container. | +| `artifacts` | N | struct | Files to collect and upload to object storage after the step. | ### Usage @@ -478,3 +479,51 @@ steps: - user: foo ``` +#### The `artifacts:` key + +:::tip +Artifact collection is only available in the **Docker runtime** and requires the Vela server to be configured with an S3-compatible object storage backend. See the [artifacts usage guide](/docs/usage/artifacts.md) for more details. +::: + +The `artifacts` key accepts a struct with the following field: + +| Name | Required | Type | Description | +|---------|----------|----------|----------------------------------------------------------| +| `paths` | Y | []string | List of glob patterns matching files to collect and upload after the step completes. | + +Glob patterns are evaluated relative to the step's workspace root. Only regular files are collected — directories and symlinks are skipped. + +```yaml +--- +steps: + # Collect files matching the given glob patterns and upload them + # to configured object storage once the step finishes. + - name: test + image: golang:latest + commands: + - go test -v ./... 2>&1 | tee test-output.txt + artifacts: + paths: + - test-output.txt +``` + +```yaml +--- +steps: + # Multiple glob patterns can be provided. + - name: cypress_tests + image: cypress/browsers:node-20.16.0-chrome-127.0.6533.119-1-ff-129.0.1-edge-127.0.2651.98-1 + commands: + - npm install + - npm run cy:run + artifacts: + paths: + - cypress/screenshots/**/*.png + - cypress/videos/**/*.mp4 + - test-results/*.xml +``` + +:::note +The `artifacts` key is supported on `steps` only, not on `services` or `stages` steps. Only the **filename** (basename) is preserved in storage — if two matched paths resolve to files with the same name, only one will be stored. +::: +