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.

Add event, schedule and manual workflow triggers

eb07ff5696e0d83201215966e3ea1e6a24467581 · Keenan Nemetz · 8d ago · parent 1cde8b9e

Add event, schedule and manual workflow triggers

Workflows can now react to change requests, issues, comments, cron
schedules and manual runs, and a push trigger can filter by the paths it
changed. Branch and tag patterns gain ! exclusion.

Event runs are pinned with a JSON payload and the runner exposes it as
VOLE_EVENT, VOLE_EVENT_ACTION and VOLE_EVENT_PATH. Change-request runs
check out the base tip and carry the head and changed files, so an event
never executes an unapproved contributor commit.

Workflow dispatch resolves typed inputs and is available from the
workflows page and `vole workflow dispatch`. Deduplication now includes
an occurrence so the same commit can run for a later event or schedule
slot while a push remains idempotent.

Part of: #138

docs/workflows.md +67−7

@@ -1,8 +1,9 @@
	1	1	# Workflows
	2	2
	3		A workflow describes what CI runs: which branches and tags trigger it, which
	4		steps each job executes, and what it publishes. Machines and execution belong to
	5		[runners](runner.md); this page is about the repository side.
		3	A workflow describes what CI runs: which pushes, change requests, issues,
		4	comments, schedules, or manual runs trigger it, which steps each job executes, and
		5	what it publishes. Machines and execution belong to [runners](runner.md); this page
		6	is about the repository side.
	6	7
	7	8	For every field, limit, and default, see the [Workflow reference](reference/workflow-reference.md),
	8	9	including [what a workflow cannot express](reference/workflow-reference.md#what-a-workflow-cannot-express).
@@ -47,10 +48,13 @@ See [Images](#images) for the two forms.
	47	48
	48	49	Triggers work like this:
	49	50
	50		- `on.push.branches` limits a workflow to certain branches.
		51	- `on.push.branches` limits a workflow to certain branches; a leading `!` excludes
		52	what an earlier pattern included.
	51	53	- `on.push.tags` limits it to tag pushes.
	52		- A workflow with neither runs on every branch.
		54	- `on.push.paths` and `on.push.paths-ignore` filter a push by the files it changes.
		55	- A workflow with no `on` trigger at all runs on every branch.
	53	56	- A workflow that names `tags:` runs only on tags.
		57	- A workflow that declares only event triggers does not also run on every push.
	54	58
	55	59	A push queues each job in the workflow as its own run. Jobs are independent and
	56	60	unordered in CI: one job cannot wait for another, read its files, or consume its
@@ -65,6 +69,61 @@ When a push starts a job, Vole remembers the exact commit, the exact workflow
	65	69	file, and the exact image definition. Editing any of them later does not change a
	66	70	job that is already queued.
	67	71
		72	## Triggers beyond a push
		73
		74	A workflow can react to a change request, an issue, a comment, a schedule, or a
		75	maintainer asking for a run:
		76
		77	```yaml
		78	version: 1
		79	on:
		80	change-request:
		81	types: [opened, updated, ready]
		82	issue:
		83	types: [opened, closed]
		84	comment:
		85	types: [created]
		86	schedule:
		87	- cron: "0 3 * * 1-5"
		88	workflow-dispatch:
		89	inputs:
		90	environment:
		91	type: choice
		92	default: staging
		93	options: [staging, production]
		94	jobs:
		95	report:
		96	image: alpine:3.22
		97	steps:
		98	- run: jq . "$VOLE_EVENT_PATH"
		99	```
		100
		101	A change-request run checks out the request's base branch tip, not the proposed
		102	head. The head and the changed files are in the event payload, so a workflow can
		103	report on a change without executing an unapproved contributor commit.
		104
		105	An issue, comment, or schedule run uses the default branch tip. A manual run uses
		106	the branch chosen in the browser or with `--ref`.
		107
		108	The event is a JSON file. The runner sets `VOLE_EVENT`, `VOLE_EVENT_ACTION`, and
		109	`VOLE_EVENT_PATH` (`/run/vole/event.json`) for every non-push trigger. Read it as
		110	data; do not interpolate it into a shell command. See
		111	[Workflow reference § Event data available to steps](reference/workflow-reference.md#event-data-available-to-steps)
		112	for the fields.
		113
		114	## Manual runs
		115
		116	A workflow with `on.workflow-dispatch` gets a Run workflow button on the
		117	workflows page. Maintainers and instance admins can also start one from a clone:
		118
		119	```sh
		120	vole workflow dispatch --workflow .vole/workflows/deploy.yaml \
		121	--ref main --input environment=production
		122	```
		123
		124	The selected branch must exist, and each input is resolved against the types and
		125	defaults the workflow declares before anything is queued.
		126
	68	127	## Combined results
	69	128
	70	129	A change request that cannot fast-forward needs a merge commit before it can land.
@@ -216,12 +275,13 @@ variables: the image's `env:` (or the step) decides whether `/cache` is used. Se
	216	275	[Runners § Caching](runner.md#caching). `--cache-size` caps it (5G by default) and
	217	276	`--no-cache` empties it after every job.
	218	277
	219		A local run still ignores `on.push` filters and `runs-on`, publishes no artifacts,
		278	A local run still ignores triggers and `runs-on`, publishes no artifacts,
	220	279	and deploys no site. It sets `CI=true` and `VOLE_CI=1`, gives each step its
	221	280	declared timeout, and reads no standard input. Jobs run in declaration order and
	222	281	share the working tree, so a later job sees files an earlier one wrote; a pushed
	223	282	run queues each job separately, starts it from a clean checkout, and has no
	224		ordering between jobs.
		283	ordering between jobs. A local run is not an event, so it sets no `VOLE_EVENT*`
		284	variables and has no event payload.
	225	285
	226	286	## Artifacts
	227	287