docs(ci): describe what a job token with contents: write may push

The job token section said the token writes nothing. With contents: write in a trusted run it pushes branches and tags and publishes releases (never workflow changes), and its pushes start no run.

commit: a7f3fdb81d2eeaaa203a1dc3867e07b64d48a654
author: brice · 2h ago · 2026-10-22 09:33 UTC
parent: 7c1886f
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

1 file · +7 -1

M docs/ci.md +7 -1


@@ -59,7 +59,13 @@ Per-event rules are in [ci-events.md](ci-events.md).
59	59
60	60		## Job token
61	61
62		-	Every job gets `github.token` (`ermitegh_…`). It reads the run's repository (even private) over Git and the REST subset below, writes nothing, and expires with the job. It is not listed in `ermite token list`.
	62	+	Every job gets `github.token` (`ermitegh_…`). It expires with the job and is not listed in `ermite token list`.
	63	+
	64	+	- By default it reads the run's repository (even private) over Git and the REST subset below, and writes nothing.
	65	+	- In a trusted run, `permissions: contents: write` lets it push branches and tags to that repository and publish [releases](releases.md). A push that changes `.github/workflows` is refused, as on GitHub.
	66	+	- `pull-requests: write` gives it `mr:write` on that repository.
	67	+	- An untrusted run gets every `write` lowered to `read`.
	68	+	- A push or a tag made with it starts no run. A workflow that creates a tag and releases it does both in the same run (`needs:`).
63	69
64	70		## Actions
65	71

 ## Job token
-Every job gets `github.token` (`ermitegh_…`). It reads the run's repository (even private) over Git and the REST subset below, writes nothing, and expires with the job. It is not listed in `ermite token list`.
+Every job gets `github.token` (`ermitegh_…`). It expires with the job and is not listed in `ermite token list`.
+- By default it reads the run's repository (even private) over Git and the REST subset below, and writes nothing.
+- In a trusted run, `permissions: contents: write` lets it push branches and tags to that repository and publish [releases](releases.md). A push that changes `.github/workflows` is refused, as on GitHub.
+- `pull-requests: write` gives it `mr:write` on that repository.
+- An untrusted run gets every `write` lowered to `read`.
+- A push or a tag made with it starts no run. A workflow that creates a tag and releases it does both in the same run (`needs:`).
 ## Actions