chore: add artifacts documentation

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=<access-key> \
+  --env=VELA_STORAGE_SECRET_KEY=<secret-key> \
+  --env=VELA_STORAGE_BUCKET=vela \
+  --env=VELA_STORAGE_USE_SSL=true \
+  target/vela-server:latest
+```
+

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.
+:::
+
 

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.
+:::
+

docs/usage/artifacts.md

@@ -0,0 +1,102 @@
+---
+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.
+
+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
+
+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_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.
+
+### 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`.