vole
Clone
Read only, no credentials:
https://rodent.software/git/vole.git
Write over SSH with a registered key:
git clone ssh://git@0.0.0.0:2222/vole.git
A free and open-source forge that lives in your Git repo.
Give workflows and jobs a name and description
1cde8b9ea2ba1483beb90f19cde0f58aede2a661 · Keenan Nemetz · 8d ago · parent 30de4a44
Give workflows and jobs a name and description The workflows page showed the file path and job IDs, so a reader had to open the YAML comments to learn what a workflow was for. Add optional top-level and job-level name and description fields, default them to the file stem and job ID, pin them with a queued run, and show them on the workflows and run pages. Also document what the workflow format still cannot express, and state that CI jobs are independent and unordered: only a local run uses the declaration order. Part of: #138
docs/reference/workflow-reference.md +94−2
| @@ -23,6 +23,8 @@ Unknown keys are rejected. A workflow is validated when it is pushed and again b | |||
| 23 | 23 | | Maximum attempt log | 32 MiB (then truncated with a note) | | |
| 24 | 24 | | Maximum `runs-on` labels per job | 8 | | |
| 25 | 25 | | Maximum step command size | 64 KiB | | |
| 26 | | Maximum display name | 80 bytes | | ||
| 27 | | Maximum description | 500 bytes | | ||
| 26 | 28 | | Default step timeout | 10 minutes | | |
| 27 | 29 | | Maximum step timeout | 1 hour | | |
| 28 | 30 | ||
| @@ -31,6 +33,8 @@ Unknown keys are rejected. A workflow is validated when it is pushed and again b | |||
| 31 | 33 | | Field | Type | Required | Default | Meaning | | |
| 32 | 34 | |---|---|---|---|---| | |
| 33 | 35 | | `version` | integer | yes | — | Schema version. Must be `1`. | | |
| 36 | | `name` | string | no | the workflow file's base name | Display name on the workflows and run pages. | | ||
| 37 | | `description` | string | no | none | One-line summary of what the workflow is for. | | ||
| 34 | 38 | | `on` | mapping | no | — | Trigger configuration. Only `on.push` is supported. | | |
| 35 | 39 | | `on.push.branches` | list of strings | no | `["*"]` when neither `branches` nor `tags` is present | Branch patterns that trigger the workflow. | | |
| 36 | 40 | | `on.push.tags` | list of strings | no | none | Tag patterns that trigger the workflow. | | |
| @@ -44,6 +48,34 @@ The only supported value is `1`: | |||
| 44 | 48 | version: 1 | |
| 45 | 49 | ``` | |
| 46 | 50 | ||
| 51 | ### `name` | ||
| 52 | |||
| 53 | A display name for the workflow. The file path stays the identity — it is what a | ||
| 54 | run records and what `vole workflow run` selects — while `name` is what a reader | ||
| 55 | sees on the workflows and run pages: | ||
| 56 | |||
| 57 | ```yaml | ||
| 58 | name: Verify main | ||
| 59 | ``` | ||
| 60 | |||
| 61 | When `name` is absent or empty, the workflow is shown by its file's base name, so | ||
| 62 | `.vole/workflows/verify.yaml` is shown as `verify`. | ||
| 63 | |||
| 64 | The name is trimmed and must be one line of text, at most 80 bytes. It is display | ||
| 65 | metadata; two workflows may share a name. | ||
| 66 | |||
| 67 | ### `description` | ||
| 68 | |||
| 69 | A one-line summary of what the workflow is for, shown under its name on the | ||
| 70 | workflows page and on each run page: | ||
| 71 | |||
| 72 | ```yaml | ||
| 73 | description: Build, test and lint every push to main. | ||
| 74 | ``` | ||
| 75 | |||
| 76 | The description is trimmed and must be one line of text, at most 500 bytes. It is | ||
| 77 | optional; an absent description shows nothing. | ||
| 78 | |||
| 47 | 79 | ### `on.push.branches` | |
| 48 | 80 | ||
| 49 | 81 | A list of branch patterns. The default depends on what else is present: | |
| @@ -97,6 +129,8 @@ letter. At least one job is required. | |||
| 97 | 129 | ||
| 98 | 130 | | Field | Type | Required | Default | Meaning | | |
| 99 | 131 | |---|---|---|---|---| | |
| 132 | | `name` | string | no | the job ID | Display name on the workflows and run pages. | | ||
| 133 | | `description` | string | no | none | One-line summary of what the job does. | | ||
| 100 | 134 | | `image` | string | one of `image` / `image-file` | — | Registry image the job runs in. | | |
| 101 | 135 | | `image-file` | string | one of `image` / `image-file` | — | Name of a definition under `.vole/images/`. | | |
| 102 | 136 | | `runs-on` | string or list of strings | no | any runner | Runner labels the job requires. | | |
| @@ -108,6 +142,35 @@ letter. At least one job is required. | |||
| 108 | 142 | Exactly one of `image` and `image-file` must be present. Declaring both, or | |
| 109 | 143 | neither, is an error. | |
| 110 | 144 | ||
| 145 | ### `name` | ||
| 146 | |||
| 147 | A display name for the job, shown on the workflows page and on the run page in | ||
| 148 | place of the job ID: | ||
| 149 | |||
| 150 | ```yaml | ||
| 151 | jobs: | ||
| 152 | test: | ||
| 153 | name: Unit tests | ||
| 154 | ``` | ||
| 155 | |||
| 156 | When `name` is absent or empty, the job is shown by its ID. The ID stays the key | ||
| 157 | that a run, a lease and `vole workflow run --job` use. | ||
| 158 | |||
| 159 | The name is trimmed and must be one line of text, at most 80 bytes. | ||
| 160 | |||
| 161 | ### `description` | ||
| 162 | |||
| 163 | An optional one-line summary of what the job does: | ||
| 164 | |||
| 165 | ```yaml | ||
| 166 | jobs: | ||
| 167 | test: | ||
| 168 | name: Unit tests | ||
| 169 | description: Runs the Go tests against the pinned toolchain. | ||
| 170 | ``` | ||
| 171 | |||
| 172 | The description is trimmed and must be one line of text, at most 500 bytes. | ||
| 173 | |||
| 111 | 174 | ### `image` | |
| 112 | 175 | ||
| 113 | 176 | An OCI image reference used exactly as written: | |
| @@ -290,13 +353,37 @@ Only one job in a workflow may declare `pages`. The target branch is set by the | |||
| 290 | 353 | instance (`pages_ref`), not by the workflow. The deploy is refused if the run is no | |
| 291 | 354 | longer the newest commit on its branch. See [Workflows § Publish a website](../workflows.md#publish-a-website). | |
| 292 | 355 | ||
| 356 | ## What a workflow cannot express | ||
| 357 | |||
| 358 | The format deliberately supports only push triggers and jobs of shell steps. It | ||
| 359 | does not support: | ||
| 360 | |||
| 361 | - a job graph: there is no `needs`, no job outputs, and no shared artifacts between jobs | ||
| 362 | - non-push triggers: no `on.change_request`, `on.schedule`, or `on.workflow_dispatch` | ||
| 363 | - path filters (`paths`, `paths-ignore`) or negated branch patterns (`!main`) | ||
| 364 | - a build matrix or per-step conditions (`strategy`, `if`, `continue-on-error`) | ||
| 365 | - secrets, secret masking, or an audit trail for secret use | ||
| 366 | - expressions or contexts (`${{ }}`); nothing outside the shell is interpolated | ||
| 367 | - service containers, cache keys, or artifact downloads between jobs | ||
| 368 | - job-level timeouts, concurrency groups, or cancel-in-progress | ||
| 369 | - workflow-level `env`, working directories, or shells; `env` is per job and every | ||
| 370 | step runs through `/bin/sh -c` in the checkout | ||
| 371 | - reusable workflows or composite actions (`uses:`); shell in an image is the | ||
| 372 | reuse mechanism | ||
| 373 | - environments, deployment approvals, per-job permissions, or OIDC | ||
| 374 | |||
| 375 | Change-request results are produced automatically by the server for a commit | ||
| 376 | under review; they are not an `on:` trigger a workflow can declare. A local | ||
| 377 | `vole workflow run` ignores `on.push` and `runs-on`, publishes no artifacts, and | ||
| 378 | deploys no site. | ||
| 379 | |||
| 293 | 380 | ## Validation and pinning | |
| 294 | 381 | ||
| 295 | 382 | - The whole file is validated before a push is accepted. | |
| 296 | 383 | - Unknown keys are errors; use the field names on this page. | |
| 297 | 384 | - `version` must be `1`. | |
| 298 | - The commit, workflow blob, and image definition are pinned when a run is queued. | ||
| 299 | Later edits do not change that run. | ||
| 385 | - The commit, workflow blob, image definition, display names, and descriptions are | ||
| 386 | pinned when a run is queued. Later edits do not change that run. | ||
| 300 | 387 | - `vole workflow check` and `vole workflow run` use the same validation as a push. | |
| 301 | 388 | A local run executes in the job's image and ignores `on.push` and `runs-on`. | |
| 302 | 389 | ||
| @@ -304,12 +391,16 @@ longer the newest commit on its branch. See [Workflows § Publish a website](../ | |||
| 304 | 391 | ||
| 305 | 392 | ```yaml | |
| 306 | 393 | version: 1 | |
| 394 | name: Verify and release | ||
| 395 | description: Test every matching push, then build a release from a version tag. | ||
| 307 | 396 | on: | |
| 308 | 397 | push: | |
| 309 | 398 | branches: [main, "release/*"] | |
| 310 | 399 | tags: ["v*"] | |
| 311 | 400 | jobs: | |
| 312 | 401 | test: | |
| 402 | name: Unit tests | ||
| 403 | description: Runs the test suite against the pinned toolchain. | ||
| 313 | 404 | runs-on: [linux, arm64] | |
| 314 | 405 | image: golang:1.27-bookworm@sha256:... | |
| 315 | 406 | env: | |
| @@ -322,6 +413,7 @@ jobs: | |||
| 322 | 413 | artifacts: | |
| 323 | 414 | - path: coverage/* | |
| 324 | 415 | release: | |
| 416 | name: Build release | ||
| 325 | 417 | runs-on: linux | |
| 326 | 418 | image-file: release-toolchain | |
| 327 | 419 | steps: | |