fd07554 docs: document issues · ermite

M README.md +1 -0


@@ -130,6 +130,7 @@ Give the agent the [`skills/ermite`](skills/ermite/SKILL.md) skill so it knows t
130	130		- [Git over HTTP](docs/git-http.md): URLs and authentication
131	131		- [Tokens](docs/tokens.md): scopes, presets, branch-limited tokens
132	132		- [Merge requests](docs/merge-requests.md)
	133	+	- [Issues](docs/issues.md)
133	134		- [Commit signatures](docs/commit-signatures.md): SSH and OpenPGP badges, trusted keys
134	135		- [Web sign-in](docs/web-sign-in.md): passkeys and one-time links
135	136		- [CI](docs/ci.md): runners, trust, concurrency, reusable workflows


@@ -130,6 +130,7 @@ Give the agent the [`skills/ermite`](skills/ermite/SKILL.md) skill so it knows t
130	- [Git over HTTP](docs/git-http.md): URLs and authentication	130		- [Git over HTTP](docs/git-http.md): URLs and authentication
131	- [Tokens](docs/tokens.md): scopes, presets, branch-limited tokens	131		- [Tokens](docs/tokens.md): scopes, presets, branch-limited tokens
132	- [Merge requests](docs/merge-requests.md)	132		- [Merge requests](docs/merge-requests.md)
		133	+	- [Issues](docs/issues.md)
133	- [Commit signatures](docs/commit-signatures.md): SSH and OpenPGP badges, trusted keys	134		- [Commit signatures](docs/commit-signatures.md): SSH and OpenPGP badges, trusted keys
134	- [Web sign-in](docs/web-sign-in.md): passkeys and one-time links	135		- [Web sign-in](docs/web-sign-in.md): passkeys and one-time links
135	- [CI](docs/ci.md): runners, trust, concurrency, reusable workflows	136		- [CI](docs/ci.md): runners, trust, concurrency, reusable workflows

M docs/cli.md +6 -1


@@ -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]
	51	+	ermite repo edit <name> [--description …] [--visibility …] [--default-branch …] [--merge-modes …] [--failing-checks-block=false] [--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]

@@ -58,6 +58,9 @@ ermite mr create <repo> --source <branch> --title … \| list <repo> \| show <repo
58	58		ermite mr comment <repo> <n> -m … [--path … --line … --side old\|new] \| resolve <repo> <n> <comment>
59	59		ermite mr merge <repo> <n> --head <id> [--squash] [--delete-branch] \| close <repo> <n>
60	60
	61	+	ermite issue create <repo> --title … [--body … \| --body-file …] \| list <repo> [--state open\|closed\|all]
	62	+	ermite issue show <repo> <n> \| comment <repo> <n> -m … \| close <repo> <n> \| reopen <repo> <n>
	63	+
61	64		ermite run list <repo> [--workflow …] [--branch …] [--status …]
62	65		ermite run view <repo> <id> [--attempt n] [--log [--job …]] [--summary]
63	66		ermite run watch <repo> <id> [--log] \| cancel <repo> <id> \| rerun <repo> <id> [--failed]

@@ -81,6 +84,8 @@ ermite version # client and server versions
81	84		ermite completion bash\|zsh\|fish
82	85		```
83	86
	87	+	Issues need a server with the `issues` feature and `ermite repo edit <repo> --issues owner`; they are written with the `issue:write` scope. See [Issues](issues.md).
	88	+
84	89		## Output
85	90
86	91		- `--json` prints stable field names (listed in each `--help`) on `repo list\|show\|create\|edit`, `token create\|list`, `run list\|view\|cancel\|rerun`, `runner list` and `version`.

 ```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]
+ermite repo edit <name> [--description …] [--visibility …] [--default-branch …] [--merge-modes …] [--failing-checks-block=false] [--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 comment <repo> <n> -m … [--path … --line … --side old|new] | resolve <repo> <n> <comment>
 ermite mr merge <repo> <n> --head <id> [--squash] [--delete-branch] | 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>
 ermite run list <repo> [--workflow …] [--branch …] [--status …]
 ermite run view <repo> <id> [--attempt n] [--log [--job …]] [--summary]
 ermite run watch <repo> <id> [--log] | cancel <repo> <id> | rerun <repo> <id> [--failed]
 ermite completion bash|zsh|fish
 ```
+Issues need a server with the `issues` feature and `ermite repo edit <repo> --issues owner`; they are written with the `issue:write` scope. See [Issues](issues.md).
 ## Output
 - `--json` prints stable field names (listed in each `--help`) on `repo list|show|create|edit`, `token create|list`, `run list|view|cancel|rerun`, `runner list` and `version`.

A docs/issues.md +35 -0

@@ -0,0 +1,35 @@
	1	+	# Issues
	2	+
	3	+	An issue records a task, a bug or a question about a repository: a title, a body, comments, and an open or closed state. Issues share the numbering of merge requests: after merge request 1, the next issue is number 2.
	4	+
	5	+	```sh
	6	+	ermite repo edit myrepo --issues owner
	7	+	ermite issue create myrepo --title "Crash on start" --body "It crashes."
	8	+	ermite issue list myrepo [--state open\|closed\|all]
	9	+	ermite issue show myrepo 2
	10	+	ermite issue comment myrepo 2 -m "Reproduced."
	11	+	ermite issue close myrepo 2
	12	+	ermite issue reopen myrepo 2
	13	+	```
	14	+
	15	+	All commands take `--json`. `--body -` and `--body-file -` read standard input. A server needs the `issues` feature (`ermite version`); without it the commands, `repo edit --issues` and `token create --scope issue:write` are refused.
	16	+
	17	+	## The `issues` setting
	18	+
	19	+	`ermite repo edit <repo> --issues off\|owner\|public`, shown by `repo show` (JSON field `issues`):
	20	+
	21	+	- `off` (default): issues are disabled.
	22	+	- `owner`: the owner and tokens with `issue:write` write issues.
	23	+	- `public`: the anonymous moderated form; not available yet, the server refuses it.
	24	+
	25	+	## Who can write
	26	+
	27	+	The owner, and tokens with the `issue:write` scope. For an agent that proposes changes on its own branches and reports issues:
	28	+
	29	+	```sh
	30	+	ermite token create claude --preset agent --scope issue:write --repo <repo> --branch-prefix agent/<name>/
	31	+	```
	32	+
	33	+	## Numbering
	34	+
	35	+	Merge requests and issues of a repository draw `#n` from one sequence, so a number names one thing: `ermite mr show myrepo 1`, `ermite issue show myrepo 2`.

@@ -0,0 +1,35 @@
	1	+	# Issues
	2	+
	3	+	An issue records a task, a bug or a question about a repository: a title, a body, comments, and an open or closed state. Issues share the numbering of merge requests: after merge request 1, the next issue is number 2.
	4	+
	5	+	```sh
	6	+	ermite repo edit myrepo --issues owner
	7	+	ermite issue create myrepo --title "Crash on start" --body "It crashes."
	8	+	ermite issue list myrepo [--state open\|closed\|all]
	9	+	ermite issue show myrepo 2
	10	+	ermite issue comment myrepo 2 -m "Reproduced."
	11	+	ermite issue close myrepo 2
	12	+	ermite issue reopen myrepo 2
	13	+	```
	14	+
	15	+	All commands take `--json`. `--body -` and `--body-file -` read standard input. A server needs the `issues` feature (`ermite version`); without it the commands, `repo edit --issues` and `token create --scope issue:write` are refused.
	16	+
	17	+	## The `issues` setting
	18	+
	19	+	`ermite repo edit <repo> --issues off\|owner\|public`, shown by `repo show` (JSON field `issues`):
	20	+
	21	+	- `off` (default): issues are disabled.
	22	+	- `owner`: the owner and tokens with `issue:write` write issues.
	23	+	- `public`: the anonymous moderated form; not available yet, the server refuses it.
	24	+
	25	+	## Who can write
	26	+
	27	+	The owner, and tokens with the `issue:write` scope. For an agent that proposes changes on its own branches and reports issues:
	28	+
	29	+	```sh
	30	+	ermite token create claude --preset agent --scope issue:write --repo <repo> --branch-prefix agent/<name>/
	31	+	```
	32	+
	33	+	## Numbering
	34	+
	35	+	Merge requests and issues of a repository draw `#n` from one sequence, so a number names one thing: `ermite mr show myrepo 1`, `ermite issue show myrepo 2`.

M docs/tokens.md +2 -1


@@ -6,7 +6,7 @@ ermite token list
6	6		ermite token revoke <id>
7	7		```
8	8
9		-	The secret is printed once. Presets and `--scope` add up. The full scope list is in [`skills/ermite/CLI.md`](../skills/ermite/CLI.md).
	9	+	The secret is printed once. Presets and `--scope` add up (`issue:write` lets a token write issues). The full scope list is in [`skills/ermite/CLI.md`](../skills/ermite/CLI.md).
10	10
11	11		\| Preset \| For \|
12	12		\|---\|---\|

@@ -29,6 +29,7 @@ The token can:
29	29
30	30		- push, force-push and delete branches under its prefixes;
31	31		- open, comment on and close merge requests;
	32	+	- with `issue:write`, open, comment on, close and reopen issues of the repositories where they are enabled;
32	33		- with `mr:merge`, merge into a branch under its prefixes;
33	34		- read CI runs, logs and checks; with `ci:write`, cancel and re-run runs of its own branches;
34	35		- create tokens whose prefixes lie within its own.

 ermite token revoke <id>
 ```
-The secret is printed once. Presets and `--scope` add up. The full scope list is in [`skills/ermite/CLI.md`](../skills/ermite/CLI.md).
+The secret is printed once. Presets and `--scope` add up (`issue:write` lets a token write issues). The full scope list is in [`skills/ermite/CLI.md`](../skills/ermite/CLI.md).
 | Preset | For |
 |---|---|
 - push, force-push and delete branches under its prefixes;
 - open, comment on and close merge requests;
+- with `issue:write`, open, comment on, close and reopen issues of the repositories where they are enabled;
 - with `mr:merge`, merge into a branch under its prefixes;
 - read CI runs, logs and checks; with `ci:write`, cancel and re-run runs of its own branches;
 - create tokens whose prefixes lie within its own.

M skills/ermite/CLI.md +15 -0


@@ -41,6 +41,7 @@ Scopes:
41	41		\| `repo:admin` \| delete a repository, change visibility, description, default branch, merge settings \|
42	42		\| `mr:write` \| open, comment on, resolve, close, mark read \|
43	43		\| `mr:merge` \| merge, and delete the merged source branch with `--delete-branch` \|
	44	+	\| `issue:write` \| open, comment on, close and reopen issues \|
44	45		\| `token:admin` \| create, list and revoke tokens \|
45	46		\| `ci:write`, `secrets:write`, `runner:register` \| reserved for CI \|
46	47

@@ -62,6 +63,20 @@ A token can never grant more than the token that creates it. `--repo` (repeatabl
62	63
63	64		Merge request JSON: `repo`, `number`, `title`, `description`, `source_branch`, `target_branch`, `state`, `author` (token label), `created_at`, `updated_at`, `head_id`, `merged_commit_id`, `merge_mode`. `mr show --json` adds `commits`, `diff_base_id`, `stats`, `files` (with `hunks` under `--diff`: `kind`, `old_number`, `new_number`, `text`), `comments`, `last_read_id`, `last_read_lost`.
64	65
	66	+	## Issues
	67	+
	68	+	Issues share the numbering of merge requests and must be enabled per repository: `repo edit <repo> --issues off\|owner\|public` (`repo:admin`; default `off`; `public` is not available yet). Reading and writing needs a server with the `issues` feature.
	69	+
	70	+	\| Command \| Scope \| Notes \|
	71	+	\|---\|---\|---\|
	72	+	\| `issue create <repo> --title T [--body TEXT\\|-] [--body-file F\\|-]` \| `issue:write` \| title of 120 characters max \|
	73	+	\| `issue list <repo> [--state open\\|closed\\|all] [--json]` \| read access or `issue:write` \| default `open` \|
	74	+	\| `issue show <repo> <n> [--json]` \| read access or `issue:write` \| issue and comments \|
	75	+	\| `issue comment <repo> <n> -m TEXT\\|-` \| `issue:write` \| \|
	76	+	\| `issue close <repo> <n>` / `issue reopen <repo> <n>` \| `issue:write` \| \|
	77	+
	78	+	Issue JSON: `repo`, `number`, `title`, `body`, `state`, `author` (token label), `created_at`, `updated_at`, `comment_count`. `issue show --json` adds `comments` (`id`, `author`, `text`, `created_at`). `repo show --json` has `issues`.
	79	+
65	80		## Workflows
66	81
67	82		\| Command \| Scope \| Notes \|


@@ -41,6 +41,7 @@ Scopes:
41	\| `repo:admin` \| delete a repository, change visibility, description, default branch, merge settings \|	41		\| `repo:admin` \| delete a repository, change visibility, description, default branch, merge settings \|
42	\| `mr:write` \| open, comment on, resolve, close, mark read \|	42		\| `mr:write` \| open, comment on, resolve, close, mark read \|
43	\| `mr:merge` \| merge, and delete the merged source branch with `--delete-branch` \|	43		\| `mr:merge` \| merge, and delete the merged source branch with `--delete-branch` \|
		44	+	\| `issue:write` \| open, comment on, close and reopen issues \|
44	\| `token:admin` \| create, list and revoke tokens \|	45		\| `token:admin` \| create, list and revoke tokens \|
45	\| `ci:write`, `secrets:write`, `runner:register` \| reserved for CI \|	46		\| `ci:write`, `secrets:write`, `runner:register` \| reserved for CI \|
46		47

@@ -62,6 +63,20 @@ A token can never grant more than the token that creates it. `--repo` (repeatabl
62		63
63	Merge request JSON: `repo`, `number`, `title`, `description`, `source_branch`, `target_branch`, `state`, `author` (token label), `created_at`, `updated_at`, `head_id`, `merged_commit_id`, `merge_mode`. `mr show --json` adds `commits`, `diff_base_id`, `stats`, `files` (with `hunks` under `--diff`: `kind`, `old_number`, `new_number`, `text`), `comments`, `last_read_id`, `last_read_lost`.	64		Merge request JSON: `repo`, `number`, `title`, `description`, `source_branch`, `target_branch`, `state`, `author` (token label), `created_at`, `updated_at`, `head_id`, `merged_commit_id`, `merge_mode`. `mr show --json` adds `commits`, `diff_base_id`, `stats`, `files` (with `hunks` under `--diff`: `kind`, `old_number`, `new_number`, `text`), `comments`, `last_read_id`, `last_read_lost`.
64		65
		66	+	## Issues
		67	+
		68	+	Issues share the numbering of merge requests and must be enabled per repository: `repo edit <repo> --issues off\|owner\|public` (`repo:admin`; default `off`; `public` is not available yet). Reading and writing needs a server with the `issues` feature.
		69	+
		70	+	\| Command \| Scope \| Notes \|
		71	+	\|---\|---\|---\|
		72	+	\| `issue create <repo> --title T [--body TEXT\\|-] [--body-file F\\|-]` \| `issue:write` \| title of 120 characters max \|
		73	+	\| `issue list <repo> [--state open\\|closed\\|all] [--json]` \| read access or `issue:write` \| default `open` \|
		74	+	\| `issue show <repo> <n> [--json]` \| read access or `issue:write` \| issue and comments \|
		75	+	\| `issue comment <repo> <n> -m TEXT\\|-` \| `issue:write` \| \|
		76	+	\| `issue close <repo> <n>` / `issue reopen <repo> <n>` \| `issue:write` \| \|
		77	+
		78	+	Issue JSON: `repo`, `number`, `title`, `body`, `state`, `author` (token label), `created_at`, `updated_at`, `comment_count`. `issue show --json` adds `comments` (`id`, `author`, `text`, `created_at`). `repo show --json` has `issues`.
		79	+
65	## Workflows	80		## Workflows
66		81
67	\| Command \| Scope \| Notes \|	82		\| Command \| Scope \| Notes \|