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/workflows.md +18−2

@@ -4,7 +4,8 @@ A workflow describes what CI runs: which branches and tags trigger it, which
	4	4	steps each job executes, and what it publishes. Machines and execution belong to
	5	5	[runners](runner.md); this page is about the repository side.
	6	6
	7		For every field, limit, and default, see the [Workflow reference](reference/workflow-reference.md).
		7	For every field, limit, and default, see the [Workflow reference](reference/workflow-reference.md),
		8	including [what a workflow cannot express](reference/workflow-reference.md#what-a-workflow-cannot-express).
	8	9
	9	10	## Add a workflow
	10	11
@@ -13,11 +14,14 @@ checks it before accepting the push, so a broken workflow is rejected early.
	13	14
	14	15	```yaml
	15	16	version: 1
		17	name: Verify main
		18	description: Build, test and lint every push to main.
	16	19	on:
	17	20	push:
	18	21	branches: [main]
	19	22	jobs:
	20	23	build:
		24	name: Build and test
	21	25	runs-on: [linux, arm64] # only a runner with both labels takes this job
	22	26	image: golang:1.27-bookworm
	23	27	steps:
@@ -31,6 +35,12 @@ jobs:
	31	35	path: site/ # publish this directory as the repository's site
	32	36	```
	33	37
		38	`name` and `description` say what the workflow is for; the file path stays its
		39	identity. When `name` is absent, the workflows page shows the file's base name
		40	(`verify.yaml` becomes `verify`). A job's `name` is shown in place of its ID on the
		41	workflows and run pages. These fields are display metadata: they do not change
		42	what runs, and two workflows may share a name.
		43
	34	44	Every job must name the environment it runs in, with exactly one of `image:` or
	35	45	`image-file:`. A workflow that names neither fails the push that introduced it.
	36	46	See [Images](#images) for the two forms.
@@ -42,6 +52,11 @@ Triggers work like this:
	42	52	- A workflow with neither runs on every branch.
	43	53	- A workflow that names `tags:` runs only on tags.
	44	54
		55	A push queues each job in the workflow as its own run. Jobs are independent and
		56	unordered in CI: one job cannot wait for another, read its files, or consume its
		57	result. The order in the file matters only to a local `vole workflow run`, which
		58	executes the selected jobs in that order.
		59
	45	60	`runs-on` asks for a runner with every label in the list. A job with no `runs-on`
	46	61	can run anywhere. See [Runners § Start a runner](runner.md#start-a-runner) for what the
	47	62	labels mean on the machine.
@@ -205,7 +220,8 @@ A local run still ignores `on.push` filters and `runs-on`, publishes no artifact
	205	220	and deploys no site. It sets `CI=true` and `VOLE_CI=1`, gives each step its
	206	221	declared timeout, and reads no standard input. Jobs run in declaration order and
	207	222	share the working tree, so a later job sees files an earlier one wrote; a pushed
	208		run starts each job from a clean checkout.
		223	run queues each job separately, starts it from a clean checkout, and has no
		224	ordering between jobs.
	209	225
	210	226	## Artifacts
	211	227