b5db7e3 docs(mr): document merge request auto-merge · ermite

M docs/cli.md +3 -2


@@ -48,7 +48,7 @@ It does not run:
48	48
49	49		```sh
50	50		ermite repo list \| show <name> \| create <name> [--description …] [--visibility public]
51		-	ermite repo edit <name> [--description …] [--visibility …] [--default-branch …] [--merge-modes …] [--failing-checks-block=false] [--issues off\|owner\|public]
	51	+	ermite repo edit <name> [--description …] [--visibility …] [--default-branch …] [--merge-modes …] [--failing-checks-block=false] [--allow-auto-merge] [--issues off\|owner\|public]
52	52		ermite repo delete <name> [--yes]
53	53
54	54		ermite token create <label> [--preset cli\|agent\|ci\|runner] [--scope …] [--repo …] [--branch-prefix …] [--expires 30d]

@@ -57,7 +57,7 @@ ermite token list \| revoke <id>
57	57		ermite mr create <repo> --source <branch> --title … \| list <repo> \| show <repo> <n> [--diff] # show prints the mergeability: up to date, behind, conflict
58	58		ermite mr comment <repo> <n> -m … [--path … --line N\|A-B --side old\|new] [--reply <id>] [--approve\|--request-changes]
59	59		ermite mr resolve <repo> <n> <comment> \| edit-comment <repo> <n> <comment> -m … \| delete-comment <repo> <n> <comment>
60		-	ermite mr merge <repo> <n> --head <id> [--mode fast-forward\|squash\|merge] [--delete-branch] \| close <repo> <n>
	60	+	ermite mr merge <repo> <n> --head <id> [--mode fast-forward\|squash\|merge] [--delete-branch] \| merge <repo> <n> --head <id> --auto [--mode …] \| merge <repo> <n> --cancel-auto \| close <repo> <n>
61	61
62	62		ermite issue create <repo> --title … [--body … \| --body-file …] \| list <repo> [--state open\|closed\|all]
63	63		ermite issue show <repo> <n> \| comment <repo> <n> -m … \| close <repo> <n> \| reopen <repo> <n>

@@ -99,6 +99,7 @@ Mirrors push repositories to a remote over SSH, never forcing. See [Push mirror]
99	99		- `--json` prints stable field names (listed in each `--help`) on `repo list\|show\|create\|edit`, `issue create\|list\|show\|comment\|close\|reopen`, `token create\|list`, `run list\|view\|cancel\|rerun`, `runner list`, `mirror key\|config\|status` and `version`.
100	100		- `watch --json` prints one object per line. `merge_request_mergeability` events carry `mergeability` (`state`, `behind`, `conflict_paths`…) and print as `repo!n mergeability: behind by 2`.
101	101		- `mr merge --mode squash\|merge` creates a commit signed by the server's own key (generated on first start); the output names its fingerprint, `ermite signing-key show` prints the key. Every mode is allowed by default; `repo edit --merge-modes fast-forward,squash` disables `merge`.
	102	+	- `mr merge --auto` makes the server merge once CI passed on the head (`repo edit --allow-auto-merge` first); `--cancel-auto` cancels it; both are exclusive with each other and `--auto` with `--delete-branch`. `watch --json` adds `merge_request_auto_merge_enabled`, `merge_request_auto_merge_cancelled` (with `reason`), and `auto` (true) on `merge_request_merged` after an auto-merge. See [Merge requests](merge-requests.md#auto-merge).
102	103		- Errors are one line on stderr (`ermite: …`) with exit status 1.
103	104		- Shell completion completes repository names from the server.
104	105

 ```sh
 ermite repo list | show <name> | create <name> [--description …] [--visibility public]
-ermite repo edit <name> [--description …] [--visibility …] [--default-branch …] [--merge-modes …] [--failing-checks-block=false] [--issues off|owner|public]
+ermite repo edit <name> [--description …] [--visibility …] [--default-branch …] [--merge-modes …] [--failing-checks-block=false] [--allow-auto-merge] [--issues off|owner|public]
 ermite repo delete <name> [--yes]
 ermite token create <label> [--preset cli|agent|ci|runner] [--scope …] [--repo …] [--branch-prefix …] [--expires 30d]
 ermite mr create <repo> --source <branch> --title … | list <repo> | show <repo> <n> [--diff]   # show prints the mergeability: up to date, behind, conflict
 ermite mr comment <repo> <n> -m … [--path … --line N|A-B --side old|new] [--reply <id>] [--approve|--request-changes]
 ermite mr resolve <repo> <n> <comment> | edit-comment <repo> <n> <comment> -m … | delete-comment <repo> <n> <comment>
-ermite mr merge <repo> <n> --head <id> [--mode fast-forward|squash|merge] [--delete-branch] | close <repo> <n>
+ermite mr merge <repo> <n> --head <id> [--mode fast-forward|squash|merge] [--delete-branch] | merge <repo> <n> --head <id> --auto [--mode …] | merge <repo> <n> --cancel-auto | close <repo> <n>
 ermite issue create <repo> --title … [--body … | --body-file …] | list <repo> [--state open|closed|all]
 ermite issue show <repo> <n> | comment <repo> <n> -m … | close <repo> <n> | reopen <repo> <n>
 - `--json` prints stable field names (listed in each `--help`) on `repo list|show|create|edit`, `issue create|list|show|comment|close|reopen`, `token create|list`, `run list|view|cancel|rerun`, `runner list`, `mirror key|config|status` and `version`.
 - `watch --json` prints one object per line. `merge_request_mergeability` events carry `mergeability` (`state`, `behind`, `conflict_paths`…) and print as `repo!n mergeability: behind by 2`.
 - `mr merge --mode squash|merge` creates a commit signed by the server's own key (generated on first start); the output names its fingerprint, `ermite signing-key show` prints the key. Every mode is allowed by default; `repo edit --merge-modes fast-forward,squash` disables `merge`.
+- `mr merge --auto` makes the server merge once CI passed on the head (`repo edit --allow-auto-merge` first); `--cancel-auto` cancels it; both are exclusive with each other and `--auto` with `--delete-branch`. `watch --json` adds `merge_request_auto_merge_enabled`, `merge_request_auto_merge_cancelled` (with `reason`), and `auto` (true) on `merge_request_merged` after an auto-merge. See [Merge requests](merge-requests.md#auto-merge).
 - Errors are one line on stderr (`ermite: …`) with exit status 1.
 - Shell completion completes repository names from the server.

M docs/merge-requests.md +12 -0


@@ -39,6 +39,18 @@ git -c gpg.format=ssh -c gpg.ssh.allowedSignersFile=allowed_signers verify-commi
39	39
40	40		The merge box of the web page and the output of `mr merge --mode squash\|merge` repeat this with the fingerprint.
41	41
	42	+	## Auto-merge
	43	+
	44	+	A merge request can merge by itself once its checks passed.
	45	+
	46	+	- The repository setting `allow_auto_merge` is off by default: `ermite repo edit <repo> --allow-auto-merge` (`=false` to turn it off).
	47	+	- Enable it with `ermite mr merge <repo> <n> --head <commit> --auto --mode squash` (`--head` is required, as for a plain merge; a head that moved is refused with "branch moved"), or with Merge when ready in the web merge box. It needs `mr:merge` and a server with CI. Re-enabling replaces the previous mode and enabler.
	48	+	- The server merges when CI has settled on the head with every run complete and at least one check passed. A failing or unfinished check always blocks, whatever `failing_checks_block` says. The mode must still be allowed.
	49	+	- The merge is made as the person who enabled it. Their token is checked again at merge time: it must still be valid and allow `mr:merge` on the repository and the target branch.
	50	+	- A pending auto-merge shows in `mr show` (`auto_merge`), in the web merge box and as `merge_request_auto_merge_enabled` in `ermite watch`. A merge request merged this way has `auto_merged` true.
	51	+	- It is cancelled, with the reason in the `merge_request_auto_merge_cancelled` event, when: the source branch gets a new head or is deleted, a check fails, the merge conflicts, the mode is no longer allowed, `allow_auto_merge` is turned off, the enabler's token is revoked or no longer allowed to merge, the request is merged manually or closed.
	52	+	- Cancel it with `ermite mr merge <repo> <n> --cancel-auto` or Cancel auto-merge in the web merge box.
	53	+
42	54		## Mergeability
43	55
44	56		The server checks in the background whether each open request merges with its target, and again whenever the source or the target moves. `mr show` prints it; the web merge box shows it as a live badge; `ermite watch` reports each change.


@@ -39,6 +39,18 @@ git -c gpg.format=ssh -c gpg.ssh.allowedSignersFile=allowed_signers verify-commi
39		39
40	The merge box of the web page and the output of `mr merge --mode squash\|merge` repeat this with the fingerprint.	40		The merge box of the web page and the output of `mr merge --mode squash\|merge` repeat this with the fingerprint.
41		41
		42	+	## Auto-merge
		43	+
		44	+	A merge request can merge by itself once its checks passed.
		45	+
		46	+	- The repository setting `allow_auto_merge` is off by default: `ermite repo edit <repo> --allow-auto-merge` (`=false` to turn it off).
		47	+	- Enable it with `ermite mr merge <repo> <n> --head <commit> --auto --mode squash` (`--head` is required, as for a plain merge; a head that moved is refused with "branch moved"), or with Merge when ready in the web merge box. It needs `mr:merge` and a server with CI. Re-enabling replaces the previous mode and enabler.
		48	+	- The server merges when CI has settled on the head with every run complete and at least one check passed. A failing or unfinished check always blocks, whatever `failing_checks_block` says. The mode must still be allowed.
		49	+	- The merge is made as the person who enabled it. Their token is checked again at merge time: it must still be valid and allow `mr:merge` on the repository and the target branch.
		50	+	- A pending auto-merge shows in `mr show` (`auto_merge`), in the web merge box and as `merge_request_auto_merge_enabled` in `ermite watch`. A merge request merged this way has `auto_merged` true.
		51	+	- It is cancelled, with the reason in the `merge_request_auto_merge_cancelled` event, when: the source branch gets a new head or is deleted, a check fails, the merge conflicts, the mode is no longer allowed, `allow_auto_merge` is turned off, the enabler's token is revoked or no longer allowed to merge, the request is merged manually or closed.
		52	+	- Cancel it with `ermite mr merge <repo> <n> --cancel-auto` or Cancel auto-merge in the web merge box.
		53	+
42	## Mergeability	54		## Mergeability
43		55
44	The server checks in the background whether each open request merges with its target, and again whenever the source or the target moves. `mr show` prints it; the web merge box shows it as a live badge; `ermite watch` reports each change.	56		The server checks in the background whether each open request merges with its target, and again whenever the source or the target moves. `mr show` prints it; the web merge box shows it as a live badge; `ermite watch` reports each change.

M skills/ermite/CLI.md +4 -2


@@ -11,10 +11,10 @@ Errors are one line on standard error (`ermite: ...`) with exit status 1. `--jso
11	11		\| `repo list [--json]` \| none \| repositories you can see \|
12	12		\| `repo show <name> [--json]` \| none \| \|
13	13		\| `repo create <name> [--description TEXT] [--visibility public]` \| `repo:write` \| private by default \|
14		-	\| `repo edit <name> [--description TEXT] [--visibility V] [--default-branch B] [--merge-modes fast-forward,squash,merge] [--failing-checks-block=false]` \| `repo:admin` \| only the given flags change; every merge mode is allowed by default, list the ones to keep; `--description ""` clears it; the branch must exist \|
	14	+	\| `repo edit <name> [--description TEXT] [--visibility V] [--default-branch B] [--merge-modes fast-forward,squash,merge] [--failing-checks-block=false] [--allow-auto-merge]` \| `repo:admin` \| only the given flags change; every merge mode is allowed by default, list the ones to keep; `--description ""` clears it; the branch must exist \|
15	15		\| `repo delete <name> [--yes]` \| `repo:admin` \| \|
16	16
17		-	Repository JSON: `name`, `description`, `visibility`, `default_branch`, `created_at`, `pushed_at` (null before the first push), `merge_modes`, `failing_checks_block`.
	17	+	Repository JSON: `name`, `description`, `visibility`, `default_branch`, `created_at`, `pushed_at` (null before the first push), `merge_modes`, `failing_checks_block`, `allow_auto_merge`.
18	18
19	19		## Tokens
20	20

@@ -62,6 +62,7 @@ A token can never grant more than the token that creates it. `--repo` (repeatabl
62	62		\| `mr delete-comment <repo> <n> <comment-id>` \| `mr:write` \| author only; the text is lost, the verdict is kept \|
63	63		\| `mr resolve <repo> <n> <comment-id> [--undo]` \| `mr:write` \| on the thread root, covers its replies; doing it twice is not an error \|
64	64		\| `mr merge <repo> <n> --head <full-id> [--mode fast-forward\\|squash\\|merge] [--delete-branch]` \| `mr:merge` \| refused if the branch moved, if `fast-forward` and the target is not an ancestor of the head (behind: use `squash` or `merge`), or if `squash`/`merge` conflict; squash and merge commits are signed by the server key (`signing-key show`); answers once the target moved; `--delete-branch` deletes the source after the merge (refused for the default branch or a branch another open request uses; JSON adds `source_branch_deleted`) \|
	65	+	\| `mr merge <repo> <n> --head <full-id> --auto [--mode M]` / `mr merge <repo> <n> --cancel-auto` \| `mr:merge` \| the server merges as you once CI settled on the head with a passed check and no failing one; needs `repo edit --allow-auto-merge`; cancelled by a new head, a failing check, a conflict, a disallowed mode, the setting turned off or your token losing `mr:merge`; JSON `auto_merge` (null unless pending), `auto_merged` \|
65	66		\| `mr close <repo> <n>` \| `mr:write` \| a closed merge request cannot be reopened \|
66	67
67	68		`ermite mr create` and `ermite mr close` print a confirmation followed by the full

@@ -106,6 +107,7 @@ Workflow JSON: `repo`, `file` (always `.github/workflows/<file>`), `name` (the `
106	107		\| `repo_created`, `repo_updated`, `repo_deleted` \| `repo`, `repository` \|
107	108		\| `pushed` \| `repo`, `ref_updates` (`ref`, `old_id`, `new_id`; an empty id means created or deleted) \|
108	109		\| `merge_request_opened`, `merge_request_merged`, `merge_request_closed` \| `repo`, `merge_request` \|
	110	+	\| `merge_request_auto_merge_enabled`, `merge_request_auto_merge_cancelled` \| `repo`, `merge_request`; cancelled also has `reason`. `merge_request_merged` has `auto` true after an auto-merge \|
109	111		\| `merge_request_mergeability` \| `repo`, `number`, `mergeability` (`state`: `checking`, `up_to_date`, `behind`, `conflict`; `behind`, `behind_capped`, `conflict_paths`, `conflict_paths_truncated`); sent when the state changes \|
110	112		\| `comment_added`, `comment_edited`, `comment_deleted`, `comment_resolved` \| `repo`, `number`, `comment` (a verdict note has `verdict` set) \|
111	113		\| `gap` \| none: events were lost, reload the state \|

 | `repo list [--json]` | none | repositories you can see |
 | `repo show <name> [--json]` | none | |
 | `repo create <name> [--description TEXT] [--visibility public]` | `repo:write` | private by default |
-| `repo edit <name> [--description TEXT] [--visibility V] [--default-branch B] [--merge-modes fast-forward,squash,merge] [--failing-checks-block=false]` | `repo:admin` | only the given flags change; every merge mode is allowed by default, list the ones to keep; `--description ""` clears it; the branch must exist |
+| `repo edit <name> [--description TEXT] [--visibility V] [--default-branch B] [--merge-modes fast-forward,squash,merge] [--failing-checks-block=false] [--allow-auto-merge]` | `repo:admin` | only the given flags change; every merge mode is allowed by default, list the ones to keep; `--description ""` clears it; the branch must exist |
 | `repo delete <name> [--yes]` | `repo:admin` | |
-Repository JSON: `name`, `description`, `visibility`, `default_branch`, `created_at`, `pushed_at` (null before the first push), `merge_modes`, `failing_checks_block`.
+Repository JSON: `name`, `description`, `visibility`, `default_branch`, `created_at`, `pushed_at` (null before the first push), `merge_modes`, `failing_checks_block`, `allow_auto_merge`.
 ## Tokens
 | `mr delete-comment <repo> <n> <comment-id>` | `mr:write` | author only; the text is lost, the verdict is kept |
 | `mr resolve <repo> <n> <comment-id> [--undo]` | `mr:write` | on the thread root, covers its replies; doing it twice is not an error |
 | `mr merge <repo> <n> --head <full-id> [--mode fast-forward\|squash\|merge] [--delete-branch]` | `mr:merge` | refused if the branch moved, if `fast-forward` and the target is not an ancestor of the head (behind: use `squash` or `merge`), or if `squash`/`merge` conflict; squash and merge commits are signed by the server key (`signing-key show`); answers once the target moved; `--delete-branch` deletes the source after the merge (refused for the default branch or a branch another open request uses; JSON adds `source_branch_deleted`) |
+| `mr merge <repo> <n> --head <full-id> --auto [--mode M]` / `mr merge <repo> <n> --cancel-auto` | `mr:merge` | the server merges as you once CI settled on the head with a passed check and no failing one; needs `repo edit --allow-auto-merge`; cancelled by a new head, a failing check, a conflict, a disallowed mode, the setting turned off or your token losing `mr:merge`; JSON `auto_merge` (null unless pending), `auto_merged` |
 | `mr close <repo> <n>` | `mr:write` | a closed merge request cannot be reopened |
 `ermite mr create` and `ermite mr close` print a confirmation followed by the full
 | `repo_created`, `repo_updated`, `repo_deleted` | `repo`, `repository` |
 | `pushed` | `repo`, `ref_updates` (`ref`, `old_id`, `new_id`; an empty id means created or deleted) |
 | `merge_request_opened`, `merge_request_merged`, `merge_request_closed` | `repo`, `merge_request` |
+| `merge_request_auto_merge_enabled`, `merge_request_auto_merge_cancelled` | `repo`, `merge_request`; cancelled also has `reason`. `merge_request_merged` has `auto` true after an auto-merge |
 | `merge_request_mergeability` | `repo`, `number`, `mergeability` (`state`: `checking`, `up_to_date`, `behind`, `conflict`; `behind`, `behind_capped`, `conflict_paths`, `conflict_paths_truncated`); sent when the state changes |
 | `comment_added`, `comment_edited`, `comment_deleted`, `comment_resolved` | `repo`, `number`, `comment` (a verdict note has `verdict` set) |
 | `gap` | none: events were lost, reload the state |

M skills/ermite/SKILL.md +2 -0


@@ -39,6 +39,8 @@ git push https://git.example.com/<repo>.git main # password = token,
39	39		4. End a review with a verdict (needs `mr:review`): `--approve` or `--request-changes`, alone or with a message. Verdicts are informative and cannot be edited; a new verdict replaces the previous one.
40	40		5. Merge only when asked: `ermite mr merge <repo> <n> --head <head_id>`, with `--mode squash` for one commit or `--mode merge` for a merge commit (both signed by the server's key, see `ermite signing-key show`) and `--delete-branch` to delete the source branch afterwards.
41	41
	42	+	To merge once CI passed instead of now, add `--auto` (`ermite mr merge <repo> <n> --head <head_id> --auto --mode squash`; needs `repo edit --allow-auto-merge`); `--cancel-auto` cancels it.
	43	+
42	44		The merge is refused when the branch moved since `head_id` (review again) or, for `fast-forward`, when the target is not an ancestor of the head (rebase and push again, or use `squash`/`merge`), or when `squash`/`merge` conflict. `ermite mr show` prints the `mergeability` line (up to date, behind by N, conflict with paths). The repository may allow only some merge modes.
43	45
44	46		### Act on a review


@@ -39,6 +39,8 @@ git push https://git.example.com/<repo>.git main # password = token,
39	4. End a review with a verdict (needs `mr:review`): `--approve` or `--request-changes`, alone or with a message. Verdicts are informative and cannot be edited; a new verdict replaces the previous one.	39		4. End a review with a verdict (needs `mr:review`): `--approve` or `--request-changes`, alone or with a message. Verdicts are informative and cannot be edited; a new verdict replaces the previous one.
40	5. Merge only when asked: `ermite mr merge <repo> <n> --head <head_id>`, with `--mode squash` for one commit or `--mode merge` for a merge commit (both signed by the server's key, see `ermite signing-key show`) and `--delete-branch` to delete the source branch afterwards.	40		5. Merge only when asked: `ermite mr merge <repo> <n> --head <head_id>`, with `--mode squash` for one commit or `--mode merge` for a merge commit (both signed by the server's key, see `ermite signing-key show`) and `--delete-branch` to delete the source branch afterwards.
41		41
		42	+	To merge once CI passed instead of now, add `--auto` (`ermite mr merge <repo> <n> --head <head_id> --auto --mode squash`; needs `repo edit --allow-auto-merge`); `--cancel-auto` cancels it.
		43	+
42	The merge is refused when the branch moved since `head_id` (review again) or, for `fast-forward`, when the target is not an ancestor of the head (rebase and push again, or use `squash`/`merge`), or when `squash`/`merge` conflict. `ermite mr show` prints the `mergeability` line (up to date, behind by N, conflict with paths). The repository may allow only some merge modes.	44		The merge is refused when the branch moved since `head_id` (review again) or, for `fast-forward`, when the target is not an ancestor of the head (rebase and push again, or use `squash`/`merge`), or when `squash`/`merge` conflict. `ermite mr show` prints the `mergeability` line (up to date, behind by N, conflict with paths). The repository may allow only some merge modes.
43		45
44	### Act on a review	46		### Act on a review