@kana-ai/edgar-ext-github 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/README.md +130 -74
  2. package/dist/src/api/app.d.ts +25 -6
  3. package/dist/src/api/app.js +72 -9
  4. package/dist/src/api/client.d.ts +9 -6
  5. package/dist/src/api/client.js +58 -19
  6. package/dist/src/api/commits.d.ts +4 -0
  7. package/dist/src/api/commits.js +69 -0
  8. package/dist/src/api/failures.d.ts +4 -0
  9. package/dist/src/api/failures.js +14 -1
  10. package/dist/src/feed/alerts.d.ts +9 -3
  11. package/dist/src/feed/alerts.js +66 -6
  12. package/dist/src/feed/service.d.ts +10 -1
  13. package/dist/src/feed/service.js +79 -16
  14. package/dist/src/index.d.ts +97 -1
  15. package/dist/src/index.js +17 -4
  16. package/dist/src/schemas/config.d.ts +1 -0
  17. package/dist/src/schemas/config.js +73 -29
  18. package/dist/src/schemas/github.d.ts +121 -1
  19. package/dist/src/schemas/github.js +37 -2
  20. package/dist/src/schemas/tools.d.ts +159 -2
  21. package/dist/src/schemas/tools.js +129 -6
  22. package/dist/src/tools/alerts.js +1 -0
  23. package/dist/src/tools/branch.d.ts +12 -0
  24. package/dist/src/tools/branch.js +69 -1
  25. package/dist/src/tools/pull-request.d.ts +55 -7
  26. package/dist/src/tools/pull-request.js +131 -42
  27. package/dist/src/tools/revert.d.ts +27 -0
  28. package/dist/src/tools/revert.js +98 -0
  29. package/dist/src/tools/screenshot.d.ts +1 -1
  30. package/dist/src/tools/screenshot.js +25 -11
  31. package/dist/src/tracker/cards.d.ts +1 -1
  32. package/dist/src/tracker/cards.js +84 -8
  33. package/dist/src/tracker/comments.d.ts +14 -2
  34. package/dist/src/tracker/comments.js +100 -4
  35. package/dist/src/tracker/port.d.ts +1 -1
  36. package/dist/src/tracker/port.js +4 -6
  37. package/dist/src/tracker/read-link.d.ts +2 -0
  38. package/dist/src/tracker/read-link.js +23 -0
  39. package/dist/src/tracker/states.d.ts +14 -3
  40. package/dist/src/tracker/states.js +37 -6
  41. package/dist/src/tracker/tools.d.ts +27 -0
  42. package/dist/src/tracker/tools.js +63 -7
  43. package/dist/src/tracker/transitions.d.ts +14 -3
  44. package/dist/src/tracker/transitions.js +57 -10
  45. package/edgar-extension.json +121 -7
  46. package/package.json +3 -3
  47. package/schemas/attach_screenshot.in.json +19 -0
  48. package/schemas/config.json +49 -23
  49. package/schemas/create_card.in.json +4 -0
  50. package/schemas/delete_closed_branches.in.json +26 -0
  51. package/schemas/delete_closed_branches.out.json +22 -0
  52. package/schemas/find_revert_pull_request.in.json +21 -0
  53. package/schemas/find_revert_pull_request.out.json +14 -0
  54. package/schemas/list_pull_requests.out.json +5 -1
  55. package/schemas/mark_seen.in.json +11 -0
  56. package/schemas/mark_seen.out.json +10 -0
  57. package/schemas/merged_pull_request.in.json +17 -0
  58. package/schemas/merged_pull_request.out.json +18 -0
  59. package/schemas/open_pull_request.in.json +73 -1
  60. package/schemas/park.in.json +15 -0
  61. package/schemas/park.out.json +10 -0
  62. package/schemas/pull_request_state.out.json +10 -1
  63. package/schemas/release_follow_ups.in.json +5 -0
  64. package/schemas/retitle.in.json +16 -0
  65. package/schemas/retitle.out.json +13 -0
  66. package/schemas/revert_pull_request.in.json +11 -0
  67. package/schemas/revert_pull_request.out.json +14 -0
  68. package/schemas/set_priority.in.json +16 -0
  69. package/schemas/set_priority.out.json +10 -0
  70. package/schemas/update_pull_request.in.json +28 -1
  71. package/schemas/wait_for_review.out.json +10 -1
package/README.md CHANGED
@@ -1,34 +1,38 @@
1
1
  # @kana-ai/edgar-ext-github
2
2
 
3
- The GitHub extension of EDGAR. It pushes `edgar/` branches from the run's sandbox, opens, watches, closes and merges pull requests, reads a pull request's checks and discussion, a workflow run's failed jobs, a repository's Dependabot alerts and a branch's protection, dismisses a Dependabot alert on a person's word, and declares the `events` webhook. Its service watches the repositories of `[extensions.github.watch]` and opens a card for a review asked of EDGAR, a red default branch, and red checks on EDGAR's own pull request. With `[extensions.github.dependabot]`, the service also opens a card for each open Dependabot advisory. The default workflows call its tools as `github__<tool>`. With `[extensions.github.columns]` and `[extensions.github.tracker]`, it is also a tracker of the project over GitHub Issues, and the default workflows call its tracker tools as `tracker__<tool>` for the cards it holds.
3
+ The GitHub extension of EDGAR. It pushes `edgar/` branches from the run's sandbox, opens, watches, closes and merges pull requests, reads a pull request's checks and discussion, a workflow run's failed jobs, a repository's Dependabot alerts and a branch's protection, dismisses a Dependabot alert on a person's word, and declares the `events` webhook. Its service watches the repositories of `[extensions.github.watch]` and opens a card for a review asked of EDGAR, a red default branch, and red checks on EDGAR's own pull request, and puts a comment that mentions EDGAR on one of its pull requests on that pull request's card. With `[extensions.github.dependabot]`, the service also opens a card for each open Dependabot advisory. The default workflows call its tools as `github__<tool>`. With `[extensions.github.columns]` and `[extensions.github.tracker]`, it is also a tracker of the project over GitHub Issues, and the default workflows call its tracker tools as `tracker__<tool>` for the cards it holds.
4
4
 
5
5
  ## Tools
6
6
 
7
- | Tool | Input | Output | Notes |
8
- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
- | `push_branch` | `repo`, and `branch` or `to` | `branch`, `commit` | Runs `git rev-parse` and `git push origin <branch>` in the sandbox, never forced. Refuses a branch outside `edgar/` or with `:`, `+` or `..`. Needs `git:push` and `sandbox:read`. |
10
- | `open_pull_request` | `repo`, `branch`, `title`, `body`, `review`; optional `labels`, `large_diff_lines`, `path_notices`, `checks`, `not_verified`, `related` | `url`, `number` | Opens onto `default_base`. The body ends with `edgar-operation: <operation id>`. Side effect, undone by `close_pull_request`, found by `find_pull_request`. See [Body notices and labels](#body-notices-and-labels). |
11
- | `close_pull_request` | `stage_output`: the output of `open_pull_request`; optional `text` | `url`, `state` | Closes without merging. A pull request that is merged or closed answers `skipped`, with no write. With `text`, the tool first adds it as one line of EDGAR's note, as `note_pull_request` does: the sweep gives the reason when a person closed the card of the pull request. |
12
- | `find_pull_request` | `operation_id`, `input`: the input of an `open_pull_request` call | `url`, `state` | `skipped` when the branch has no pull request. |
13
- | `linked_pull_requests` | `text`, `repo` | `pull_requests`: `url`, `state`, `title`, `body`, `files` (`path`, `patch`) | Reads each pull request of `repo` that `text` links, in any spelling of the repository: the first 5 links, 100 files each, and 4,000 characters of each patch. A link to another repository is left out with no call, so a card cannot bring code from elsewhere into the project's tracker. A link that answers 404 or 403 is left out. With no link to `repo`, the tool answers `skipped`, with no call. |
14
- | `note_pull_request` | `url`, `text`: one new item | `url`: the note | Adds an item to EDGAR's one note on the pull request, a comment that EDGAR finds by its hidden first line. The item keeps the lines of `text` under its bullet, so its paragraphs and lists stay. The first call makes the note. |
15
- | `update_pull_request` | `url`, `title`, `body`; optional `large_diff_lines`, `path_notices`, `checks`, `not_verified` | `url` | Gives an open pull request a new title and body, when a later change made them untrue. The body gets its notices and proof again, as `open_pull_request` writes them, and the operation line of this call. The review line of the first body is left out, because that review read the change before. A pull request that is merged or closed answers `skipped`, with no write. |
16
- | `attach_screenshot` | `url`; `shot`: `path`, `bytes` and `caption` of a PNG in the sandbox, or `missing` | `attached`; `image` or `missing` | Stores the PNG on the branch `edgar/screenshots` of the pull request's repository, at `<run id>/preview-<hash>.png`, and puts it in the body pinned to the commit that holds it. The first picture of a repository starts that branch from an empty tree, so it shares no history with the code. A picture over 1 MB, one that cannot be read, or an upload that GitHub refuses gives the body one line, "The screenshot is missing:", with the reason, and the output says it too. Only an input that is not a pull request fails. `update_pull_request` keeps the picture when it rewrites the body. |
17
- | `list_pull_requests` | `services`: a list of `repo`; optional `merged_within_hours` (1 to 720) | `pull_requests`: `url`, `branch`, `card`, `unmerged` | One page of open pull requests per repository, read once however the services spell it (`git@github.com:o/r.git`, `https://github.com/o/r`, any letter case), on `edgar/<card>-<slug>` branches whose head is in that repository, so a fork's branch of that name is left out. With `merged_within_hours`, the pull requests merged within that many hours in place of the open ones, from one page of the 100 closed pull requests updated last. The engine passes the project's services. A service whose `repo` is not on github.com has none here, so `merge_watch` goes on for the others. With `merged_within_hours`, `unmerged` lists each pull request of the `Goes with:` line of the body that is not merged, as `url` and `state` (`open` or `closed`); one that answers 404 or 403 is `closed`. It is empty for the open ones and for a pull request that goes with none. |
18
- | `pull_request_state` | `url` | `url`, `state`, `merged`, `review_state`, `approved_by`, `card`, `commit`, `branch`, `head_repo` | `review_state` comes from each reviewer's latest approval or change request. A change request made on a commit before the head is `pending` until its reviewer reviews again, whatever the others did, because a push answered it. `approved_by` lists the login of each reviewer whose latest one approves. `commit` is the merge commit once merged. `card` is `null` for a branch with no card. `branch` is the head branch and `head_repo` its repository as `owner/name`, a fork's for a fork, `null` when that repository was deleted. |
19
- | `wait_for_review` | `url` | as `pull_request_state` | The recheck of a `wait` stage for a review. This tool answers `skipped` while the pull request is open and no review has decided, and the output of `pull_request_state` once it is approved, has a change request, or is merged or closed. |
20
- | `wait_for_merge` | `url` | `url`, `merged`, `sha` | The recheck of a `wait` stage that ends on a merge or a close only. This tool answers `skipped` while the pull request is open, whatever its reviews say, `merged: true` with the merge commit as `sha` once it is merged, and `merged: false` with no `sha` once it is closed without a merge. |
21
- | `merge_pull_request` | `url`, `commit`, `changed_files` | `url`, `merged`, `commit` | Shipped turned off, approval `always`, no undo. Merges `commit` only, the head that `pull_request_state` gave and that the person approved; when the head has moved, GitHub merges nothing and the tool answers `invalid`. With `changed_files`, the call is EDGAR's own merge from a workflow stage: the engine runs it with no person when the count is under `[limits] self_merge_files`, and skips the stage at or past it. |
22
- | `pull_request_checks` | `url` | `url`, `commit`, `state`, `merged`, `checks`, `failed`, `retry_after_seconds`, `summary`, `changed_files` | Reads the check runs and the commit statuses of the head commit, and `changed_files`, the files that the pull request changes. `state` is `failed` when one failed, else `pending` while one runs, else `passed`. A closed pull request, merged or not, is `closed` with no check read, `checks` 0 and `merged` from GitHub; `merged` is `false` while it is open. `failed` lists each failed check's `name` and details `url`. `retry_after_seconds` is 60 while pending, else `null`. `summary` is one sentence that a later stage posts as it is, such as `All 3 checks passed on 6dcb09b.`, `1 of 3 checks failed: test (<details url>).` or `2 checks still run.` See [Wait for CI](#wait-for-ci). |
23
- | `wait_for_checks` | `url` | as `pull_request_checks` | The recheck of a `wait` stage. A recheck that answers `done` ends the wait, so this tool answers `skipped` while a check runs, or while a pull request updated in the last 2 minutes has no check yet, and the output of `pull_request_checks` once every check has ended or the pull request is closed. |
24
- | `wait_for_passed_checks` | `url` | as `pull_request_checks` | The recheck of a `wait` stage that only passed checks end. It answers `skipped` while a check runs and also while a check has failed, so a later push or a rerun that passes ends the wait. A closed pull request ends it as `closed`. The built-in `remediate` uses it after its one repair: no review is asked for while a check is red. |
25
- | `ci_run` | `url` of a run, or of a job | `url`, `workflow`, `status`, `conclusion`, `commit`, `branch`, `attempt`, `jobs`, `logs`, `unread` | Reads a GitHub Actions run and each job of its latest attempt with its failed steps. For each failed job (`failure`, `timed_out`), at most 3, or for the job in a `/job/<id>` URL, it reads the log: the `##[error]` lines (at most 20) and an `excerpt` of the 120 lines up to the first error, at most 16,000 characters, with timestamps and colour codes removed. `gone` is `true` when GitHub no longer keeps the log. `unread` lists the failed jobs past the limit. |
26
- | `pull_request_discussion` | `url` | `url`, `reviews`, `threads`, `conversation`, `complete` | `reviews` holds each verdict, and each review with words; a wordless `COMMENTED` review is left out. `threads` holds each line comment with its `path`, `line`, the last 8 lines of its `hunk` and its `replies`. `conversation` holds the issue comments. EDGAR's own remarks stay, with `by`. A failed read is the failure, never an empty discussion. |
27
- | `dependabot_alerts` | `repo`; optional `number`, `state`, `package`, `ghsa`, `cve`, `limit` | `alerts`, `complete` | With `number`, that alert; the filters then must be empty, or `invalid_input`. Without it, newest first, every state unless `state` names some, at most `limit` (30, at most 100). Each alert has its `package`, `ecosystem`, `severity`, `vulnerable_range`, `first_patched`, `manifest`, `scope`, `ghsa`, `cve` and `summary`. `ghsa` and `cve` match within a page of 100. |
28
- | `branch_protection` | `repo`, `branch` | `branch`, `protected`, `pull_request_required`, `required_approvals`, `required_checks`, `rules`, `classic` | Joins the branch's own protection, each rule and ruleset that applies (`/rules/branches`), and the classic rule. GitHub shows the classic rule to admins only: `classic` is then `unreadable`, and `pull_request_required` and `required_approvals` are `null` unless a rule settles them. |
29
- | `dismiss_dependabot_alert` | `repo`, `number`, `reason`, `comment` | `repo`, `number`, `url`, `reason`, `reopen` | Approval `always`. Side effect, undone by `reopen_dependabot_alert`, found by `find_dependabot_dismissal`. `reason` is one of GitHub's reasons: `fix_started`, `inaccurate`, `no_bandwidth`, `not_used`, `tolerable_risk`. `comment` has 1 to 280 characters. See [Dismiss a Dependabot alert](#dismiss-a-dependabot-alert). |
30
- | `reopen_dependabot_alert` | `stage_output`: the output of `dismiss_dependabot_alert` | `repo`, `number`, `url`, `reopened` | The undo of `dismiss_dependabot_alert`. It opens the alert again when `reopen` is `true` and the alert is still dismissed. Otherwise it writes nothing and answers `reopened: false`. |
31
- | `find_dependabot_dismissal` | `operation_id`, `input`: the input of a `dismiss_dependabot_alert` call | as `dismiss_dependabot_alert` | The lookup of `dismiss_dependabot_alert`. `done` when the alert is dismissed with the `reason` and the `comment` of the call. `skipped` otherwise. |
7
+ | Tool | Input | Output | Notes |
8
+ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
+ | `push_branch` | `repo`, and `branch` or `to` | `branch`, `commit` | Runs `git rev-parse` and `git push origin <branch>` in the sandbox, never forced. Refuses a branch outside `edgar/` or with `:`, `+` or `..`. Needs `git:push` and `sandbox:read`. |
10
+ | `open_pull_request` | `repo`, `branch`, `title`, `body`, `review`; optional `base`, `card`, `labels`, `large_diff_lines`, `path_notices`, `checks`, `not_verified`, `proof`, `proof_passes`, `related` | `url`, `number` | Opens onto `base`, the service's default branch, or onto `default_base` when the call names none. The body ends with `edgar-operation: <operation id>`. Side effect, undone by `close_pull_request`, found by `find_pull_request`. See [Body notices and labels](#body-notices-and-labels). |
11
+ | `close_pull_request` | `stage_output`: the output of `open_pull_request`; optional `text` | `url`, `state` | Closes without merging. A pull request that is merged or closed answers `skipped`, with no write. With `text`, the tool first adds it as one line of EDGAR's note, as `note_pull_request` does: the sweep gives the reason when a person closed the card of the pull request. |
12
+ | `find_pull_request` | `operation_id`, `input`: the input of an `open_pull_request` call | `url`, `state` | `skipped` when the branch has no pull request. |
13
+ | `linked_pull_requests` | `text`, `repo` | `pull_requests`: `url`, `state`, `title`, `body`, `files` (`path`, `patch`) | Reads each pull request of `repo` that `text` links, in any spelling of the repository: the first 5 links, 100 files each, and 4,000 characters of each patch. A link to another repository is left out with no call, so a card cannot bring code from elsewhere into the project's tracker. A link that answers 404 or 403 is left out. With no link to `repo`, the tool answers `skipped`, with no call. |
14
+ | `note_pull_request` | `url`, `text`: one new item | `url`: the note | Adds an item to EDGAR's one note on the pull request, a comment that EDGAR finds by its hidden first line. The note's first sentence, "EDGAR's notes on this pull request, oldest first:", leads the list of items. The item keeps the lines of `text` under its bullet, so its paragraphs and lists stay. The first call makes the note. |
15
+ | `update_pull_request` | `url`, `title`, `body`; optional `card`, `large_diff_lines`, `path_notices`, `checks`, `not_verified` | `url` | Gives an open pull request a new title and body, when a later change made them untrue. The body gets its notices and proof again, as `open_pull_request` writes them, and the operation line of this call. The review line of the first body is left out, because that review read the change before. A pull request that is merged or closed answers `skipped`, with no write. |
16
+ | `attach_screenshot` | `url`; `shot`: `path`, `bytes` and `caption` of a PNG in the sandbox, with the `url` EDGAR serves it at when it is in `[storage]` and a flow's `video`, or `missing` | `attached`; `image` or `missing` | With a `url`, puts that address in the body and writes nothing to the repository. Otherwise stores the PNG on the branch `edgar/screenshots` of the pull request's repository, at `<run id>/preview-<hash>.png`, and puts it in the body pinned to the commit that holds it. The first picture of a repository starts that branch from an empty tree, so it shares no history with the code. A picture over 1 MB, one that cannot be read, or an upload that GitHub refuses gives the body one line, "The screenshot is missing:", with the reason, and the output says it too. A flow's `video` (`path`, `bytes`) goes to the same branch, at `<run id>/flow-<hash>.mp4`, as a link under the picture; a video over 1 MB or not stored gives the line "The video is missing:" with the reason, and the picture still shows. Only an input that is not a pull request fails. `update_pull_request` keeps the picture when it rewrites the body. |
17
+ | `list_pull_requests` | `services`: a list of `repo`; optional `merged_within_hours` (1 to 720) | `pull_requests`: `url`, `branch`, `card`, `unmerged`; `complete` | One page of open pull requests per repository, read once however the services spell it (`git@github.com:o/r.git`, `https://github.com/o/r`, any letter case), on `edgar/<card>-<slug>` branches whose head is in that repository, so a fork's branch of that name is left out. With `merged_within_hours`, the pull requests merged within that many hours in place of the open ones, from one page of the 100 closed pull requests updated last. The engine passes the project's services. A service whose `repo` is not on github.com has none here, so `merge_watch` goes on for the others. With `merged_within_hours`, `unmerged` lists each pull request of the `Goes with:` line of the body that is not merged, as `url` and `state` (`open` or `closed`); one that answers 404 or 403 is `closed`. It is empty for the open ones and for a pull request that goes with none. `complete` is false when the page of a repository came back full, 100 pull requests, so one past them is not listed; the runtime log names that repository. |
18
+ | `delete_closed_branches` | `services`: a list of `repo`; `closed_within_hours` (1 to 720) | `deleted`: `pull_request`, `branch` | Deletes the head branch of each pull request closed within that many hours, merged or not, from one page of the 100 closed pull requests updated last per repository. It deletes only an `edgar/<card>-<slug>` branch whose head is in that repository and that is not the base of its pull request, and only while the branch exists and no open pull request uses it, so `edgar/screenshots`, a fork's branch and a person's branch are never touched. A repository that deletes head branches on merge leaves those to GitHub, and a branch that a delete finds gone already (404 or 422) counts as done, with a log line. The built-in `merge_watch` calls it last, every 10 minutes, with `closed_within_hours = 24`. |
19
+ | `pull_request_state` | `url` | `url`, `state`, `merged`, `review_state`, `approved_by`, `card`, `commit`, `branch`, `head_repo`, `mergeable`, `base_commit` | `review_state` comes from each reviewer's latest approval or change request. A change request made on a commit before the head is `pending` until its reviewer reviews again, whatever the others did, because a push answered it. `approved_by` lists the login of each reviewer whose latest one approves. `commit` is the merge commit once merged. `card` is `null` for a branch with no card. `branch` is the head branch and `head_repo` its repository as `owner/name`, a fork's for a fork, `null` when that repository was deleted. `mergeable` is `false` when the open pull request conflicts with its base branch, and `null` while GitHub computes it or once it is merged or closed. On a conflict, a third read gives `base_commit`, the newest commit of the base branch, to merge into the head. |
20
+ | `wait_for_review` | `url` | as `pull_request_state` | The recheck of a `wait` stage for a review. This tool answers `skipped` while the pull request is open, no review has decided and it does not conflict with its base branch, and the output of `pull_request_state` once it is approved, has a change request, conflicts (`mergeable` is `false`), or is merged or closed. |
21
+ | `wait_for_merge` | `url` | `url`, `merged`, `sha` | The recheck of a `wait` stage that ends on a merge or a close only. This tool answers `skipped` while the pull request is open, whatever its reviews say, `merged: true` with the merge commit as `sha` once it is merged, and `merged: false` with no `sha` once it is closed without a merge. |
22
+ | `merge_pull_request` | `url`, `commit`, `changed_files` | `url`, `merged`, `commit` | Shipped turned off, approval `always`, no undo. Merges `commit` only, the head that `pull_request_state` gave and that the person approved; when the head has moved, GitHub merges nothing and the tool answers `invalid`. With `changed_files`, the call is EDGAR's own merge from a workflow stage: the engine runs it with no person when the count is under `[limits] self_merge_files`, and skips the stage at or past it. |
23
+ | `merged_pull_request` | `repo`, `card` | `url`, `merged_at`, `commit` | The newest merged pull request of the card's `edgar/<card>-` branch, from the 100 closed pull requests updated last; a fork's is left out. `skipped` when there is none. |
24
+ | `revert_pull_request` | `url` | `url`, `state` | Opens GitHub's revert of a merged pull request with GraphQL `revertPullRequest`, as a new pull request whose body says that a person merges it; no tool merges it. The revert already there, found by GitHub's branch name `revert-<number>-<branch>`, is answered instead of a second one. `skipped` when the pull request is not merged. Its undo is `close_pull_request`, its lookup `find_revert_pull_request`. A GraphQL error maps by its `type`: `NOT_FOUND` is `not_found`, `FORBIDDEN` `forbidden`, `UNPROCESSABLE` `invalid`, `RATE_LIMITED` a temporary `rate_limited`, and any other, or none, `tool_error`, with the type and message in `cause`. |
25
+ | `find_revert_pull_request` | `operation_id`, `input`: the input of a `revert_pull_request` call | `url`, `state` | The lookup of `revert_pull_request`. `skipped` when there is no revert. |
26
+ | `pull_request_checks` | `url` | `url`, `commit`, `state`, `merged`, `checks`, `failed`, `retry_after_seconds`, `summary`, `changed_files` | Reads the check runs and the commit statuses of the head commit, and `changed_files`, the files that the pull request changes. `state` is `failed` when one failed, else `pending` while one runs, else `passed`. A closed pull request, merged or not, is `closed` with no check read, `checks` 0 and `merged` from GitHub; `merged` is `false` while it is open. `failed` lists each failed check's `name` and details `url`. `retry_after_seconds` is 60 while pending, else `null`. `summary` is one sentence that a later stage posts as it is, such as `All 3 checks passed on 6dcb09b.`, `1 of 3 checks failed: test (<details url>).` or `2 checks still run.` See [Wait for CI](#wait-for-ci). |
27
+ | `wait_for_checks` | `url` | as `pull_request_checks` | The recheck of a `wait` stage. A recheck that answers `done` ends the wait, so this tool answers `skipped` while a check runs, or while a pull request updated in the last 2 minutes has no check yet, and the output of `pull_request_checks` once every check has ended or the pull request is closed. |
28
+ | `wait_for_passed_checks` | `url` | as `pull_request_checks` | The recheck of a `wait` stage that only passed checks end. It answers `skipped` while a check runs and also while a check has failed, so a later push or a rerun that passes ends the wait. A closed pull request ends it as `closed`. The built-in `remediate` uses it after its last repair: no review is asked for while a check is red. |
29
+ | `ci_run` | `url` of a run, or of a job | `url`, `workflow`, `status`, `conclusion`, `commit`, `branch`, `attempt`, `jobs`, `logs`, `unread` | Reads a GitHub Actions run and each job of its latest attempt with its failed steps. For each failed job (`failure`, `timed_out`), at most 3, or for the job in a `/job/<id>` URL, it reads the log: the `##[error]` lines (at most 20) and an `excerpt` of the 120 lines up to the first error, at most 16,000 characters, with timestamps and colour codes removed. `gone` is `true` when GitHub no longer keeps the log. `unread` lists the failed jobs past the limit. |
30
+ | `pull_request_discussion` | `url` | `url`, `reviews`, `threads`, `conversation`, `complete` | `reviews` holds each verdict, and each review with words; a wordless `COMMENTED` review is left out. `threads` holds each line comment with its `path`, `line`, the last 8 lines of its `hunk` and its `replies`. `conversation` holds the issue comments. EDGAR's own remarks stay, with `by`. A failed read is the failure, never an empty discussion. |
31
+ | `dependabot_alerts` | `repo`; optional `number`, `state`, `package`, `ghsa`, `cve`, `limit` | `alerts`, `complete` | With `number`, that alert; the filters then must be empty, or `invalid_input`. Without it, newest first, every state unless `state` names some, at most `limit` (30, at most 100). Each alert has its `package`, `ecosystem`, `severity`, `vulnerable_range`, `first_patched`, `manifest`, `scope`, `ghsa`, `cve` and `summary`. `ghsa` and `cve` match within a page of 100. |
32
+ | `branch_protection` | `repo`, `branch` | `branch`, `protected`, `pull_request_required`, `required_approvals`, `required_checks`, `rules`, `classic` | Joins the branch's own protection, each rule and ruleset that applies (`/rules/branches`), and the classic rule. GitHub shows the classic rule to admins only: `classic` is then `unreadable`, and `pull_request_required` and `required_approvals` are `null` unless a rule settles them. |
33
+ | `dismiss_dependabot_alert` | `repo`, `number`, `reason`, `comment` | `repo`, `number`, `url`, `reason`, `reopen` | Approval `always`. Side effect, undone by `reopen_dependabot_alert`, found by `find_dependabot_dismissal`. `reason` is one of GitHub's reasons: `fix_started`, `inaccurate`, `no_bandwidth`, `not_used`, `tolerable_risk`. `comment` has 1 to 280 characters. See [Dismiss a Dependabot alert](#dismiss-a-dependabot-alert). |
34
+ | `reopen_dependabot_alert` | `stage_output`: the output of `dismiss_dependabot_alert` | `repo`, `number`, `url`, `reopened` | The undo of `dismiss_dependabot_alert`. It opens the alert again when `reopen` is `true` and the alert is still dismissed. Otherwise it writes nothing and answers `reopened: false`. |
35
+ | `find_dependabot_dismissal` | `operation_id`, `input`: the input of a `dismiss_dependabot_alert` call | as `dismiss_dependabot_alert` | The lookup of `dismiss_dependabot_alert`. `done` when the alert is dismissed with the `reason` and the `comment` of the call. `skipped` otherwise. |
32
36
 
33
37
  `repo` is `owner/name`, `git@github.com:owner/name.git` or `https://github.com/owner/name`.
34
38
 
@@ -42,7 +46,7 @@ needs = ["open"]
42
46
  wait = { key = "stages.open.output.url", timeout_seconds = 604800, recheck = { tool = "github__wait_for_review", every_seconds = 60 } }
43
47
  ```
44
48
 
45
- Each recheck is two requests to the GitHub API, so at 60 seconds one waiting run uses 120 of the 5,000 requests that a token has in an hour. A later stage reads `stages.wait_review.output.review_state`, `state` and `commit`. The wait also ends when a person merges or closes the pull request; `commit` is then the merge commit or the last head, so a merge stage runs only when `state` is `open`. Do not use `pull_request_state` as a recheck: it answers `done` on each read, so the wait ends at its first recheck with `review_state` as it is then.
49
+ Each recheck is two requests to the GitHub API, so at 60 seconds one waiting run uses 120 of the 5,000 requests that a token has in an hour. A later stage reads `stages.wait_review.output.review_state`, `state`, `commit` and `mergeable`. The wait also ends on a conflict with the base branch, so a merge stage runs only when `mergeable` is not `false`. The wait also ends when a person merges or closes the pull request; `commit` is then the merge commit or the last head, so a merge stage runs only when `state` is `open`. Do not use `pull_request_state` as a recheck: it answers `done` on each read, so the wait ends at its first recheck with `review_state` as it is then.
46
50
 
47
51
  ### Wait for CI
48
52
 
@@ -80,12 +84,14 @@ A later stage reads `stages.ci.output.state`, and gives a failed check's `url` t
80
84
 
81
85
  Each extra is optional. With none, `open_pull_request` sends one request, as before.
82
86
 
83
- - `labels`: the labels the pull request gets, added after it opens (`POST /repos/{owner}/{repo}/issues/{number}/labels`), also when a retry reads the pull request back. A refused label is written to the runtime log and the outcome stays `done`, because the change is open and a label only sorts it.
84
- - `large_diff_lines`: when the change has more changed lines than this, the body says `**Large change.** 211 lines across 2 files.`
87
+ - `card`: the run's card, with its `id`, `title` and `url`. The title becomes `<id>: <card title>`, such as `ENG-12: Login times out`, in place of `title`, and the body opens with `Card: [ENG-12](<url>)`, or `Card: ENG-12` for a card with no address. `update_pull_request` writes both the same way. The built-in workflows pass the run's card.
88
+ - `labels`: the labels the pull request gets, with each label of `[extensions.github] pr_labels` first, added after it opens (`POST /repos/{owner}/{repo}/issues/{number}/labels`), also when a retry reads the pull request back. A refused label is written to the runtime log and the outcome stays `done`, because the change is open and a label only sorts it.
89
+ - `large_diff_lines`: when the change has more changed lines than this, the body says `This is a large change: 211 lines across 2 files.`
85
90
  - `path_notices`: a list of `{ prefix, notice }`. When a changed file's path starts with `prefix`, the body carries `notice`, once.
86
91
 
87
- - `checks`: the output of a check stage, such as `stages.checks.output`. The body lists each check that ended with exit code 0 under **Verified**, and each other check under **Not verified**. The lists come from the exit codes that the check stage recorded, and from no words of a model. The body shows the name and the exit code only, never the output of a check.
88
- - `not_verified`: a list of things that the author of the change did not check, one line each. They go under **Not verified**, after the checks.
92
+ - `checks`: the output of a check stage, such as `stages.checks.output`. The body lists each check that ended with exit code 0 under the `## Verified` heading, and says when one passed only on its second run, after a failure. Each other check goes under `## Not verified`, and a check that fails the same way on the base commit says that this change did not cause it. The lists come from the exit codes that the check stage recorded, and from no words of a model. The body shows the name and the exit code only, never the output of a check.
93
+ - `not_verified`: a list of things that the author of the change did not check, one line each. They go under `## Not verified`, after the checks.
94
+ - `proof`: the output of a `check = "proof"` stage. The body gets a `## The change's own proof` section that says whether the proof passed, failed or did not run, with its command, its exit code and the end of its output folded away. With `on_base`, it says how a proof that passed ended on the base commit: `failed` proves the change, and `passed` or `unknown` (EDGAR could not tell) does not. It is advice and blocks nothing. `proof_passes` adds what the author said passing looks like.
89
95
  - `related`: one `https:` URL, or a list of at most 5, of the pull requests that this one goes with. The body carries `Goes with: <url1>, <url2>` after the text of `body`. A list of more than 5, or a URL that is not `https:`, is refused as invalid input.
90
96
 
91
97
  The built-in `remediate` passes `large_diff_lines = 200`, and the `[[services.<name>.path_notices]]` of the card's service.
@@ -96,24 +102,26 @@ The size and the paths come from `GET /repos/{owner}/{repo}/compare/{base}...{br
96
102
  input = { repo = "...", branch = "...", title = "...", body = "...", review = "", labels = [
97
103
  "edgar",
98
104
  ], large_diff_lines = 200, path_notices = [
99
- { prefix = "web/", notice = "**Frontend affected.**" },
105
+ { prefix = "web/", notice = "This change affects the frontend." },
100
106
  ] }
101
107
  ```
102
108
 
103
109
  The proof of a change with `checks` and `not_verified` reads:
104
110
 
105
- ```text
106
- **Verified:**
111
+ ```markdown
112
+ ## Verified
113
+
107
114
  - `lint` passed
108
115
  - `unit` passed
109
116
 
110
- **Not verified:**
117
+ ## Not verified
118
+
111
119
  - `e2e` ended with exit code 1
112
120
  - `load` did not run or did not end
113
121
  - The mail that the new rule sends.
114
122
  ```
115
123
 
116
- With `checks`, the body always has a **Verified** part, so a reader can tell a change that no check passed from a body with no proof: "**Verified:** nothing passed." when each check failed, and "**Verified:** nothing was run. No check applies to this service." when the stage ran no check. "**Not verified:** nothing outstanding." is there only when `not_verified` is given and is empty, and no check failed. A check stage stops at the first check that fails. It gives each check after that one with no exit code, so the body lists it under **Not verified** as a check that did not run or did not end.
124
+ With `checks`, the body always has a `## Verified` section, so a reader can tell a change that no check passed from a body with no proof: the section says "Nothing passed." when each check failed, and "Nothing was run. No check applies to this service." when the stage ran no check. A `## Not verified` section that says "Nothing is outstanding." is there only when `not_verified` is given and is empty, and no check failed. A check stage stops at the first check that fails. It gives each check after that one with no exit code, so the body lists it under `## Not verified` as a check that did not run or did not end.
117
125
 
118
126
  ### Dismiss a Dependabot alert
119
127
 
@@ -206,7 +214,8 @@ An open issue is in the state of its column label; with two column labels, the s
206
214
  | `list_cards` | `GET /repos/{repo}/issues?state=open&sort=created&direction=asc&per_page=50&page={n}`, with `labels` from the table |
207
215
  | `card` | `GET /repos/{repo}/issues/{n}` |
208
216
  | `comments` | `GET /repos/{repo}/issues/{n}/comments?per_page=100&since={since}`, and `GET /user` once |
209
- | `attachments` | none: it answers an empty list |
217
+ | `attachments` | `GET /repos/{repo}/issues/{n}` and `GET .../comments?per_page=100`: the files pasted into the description and the first 100 comments |
218
+ | `mentions` | `GET /repos/{repo}/issues/comments?per_page=100&since={since}` for each repository of `repos`: the comments that mention EDGAR's login |
210
219
  | `comment` | `GET /repos/{repo}/issues/{n}`, `GET .../comments?per_page=100&page={last}` when the issue has comments, `POST .../comments` |
211
220
  | `move` | `GET /repos/{repo}/issues/{n}`; `GET /repos/{repo}/labels/{name}` and `POST /repos/{repo}/labels` once a label; `PATCH .../{n}` with `{state, state_reason}` to close or `{state}` to open; `POST .../{n}/labels` with `{labels}` to add; `DELETE .../{n}/labels/{name}` for each label to take off |
212
221
  | `set_labels` | `GET` and `PATCH /repos/{repo}/issues/{n}`, with the labels made as for `move` |
@@ -215,13 +224,15 @@ An open issue is in the state of its column label; with two column labels, the s
215
224
  | `whoami` | `GET /user` once, or `assignee` for an App |
216
225
  | `person` | `GET /users/{login}`: the name, or the login with none, and the public email, or an empty text |
217
226
 
218
- `list_cards` reads one repository after the other, in the order of `repos`, and leaves out pull requests and issues out of scope. Its cursor holds the repository and the GitHub page. It never lists a closed issue: the engine reads a card that a listing no longer has, and `card` answers `done` or `cancelled`. `card` answers `not_found` for a key that `repos` does not name, a pull request, a deleted issue (410), and an open issue out of scope, such as one whose title lost `title_prefix`, or with `assignee_only` one of someone else that has no `edgar:waiting`. A move of an open issue out of scope is `skipped` unless forced.
227
+ `list_cards` reads one repository after the other, in the order of `repos`, and leaves out pull requests and issues out of scope. A card's `assignee` is the login of the issue's first assignee, and its `taken_by` the login of its first assignee that is a person: not EDGAR's own login (the login of `GITHUB_TOKEN`, read once, and `assignee`) and not a `[bot]`. Its `taken_by_id` is the same login, which `[people.<name>] ids.github` matches to find that person's saved keys. Its `trust` is `team` when the issue's writer is the repository's owner, a member of the organization that owns it, or a collaborator (GitHub's `author_association` `OWNER`, `MEMBER` or `COLLABORATOR`), or one of EDGAR's own logins, and `outside` for anyone else, such as a contributor or a person with no tie to the repository. A comment's `trust` follows the same rule for its writer. Its `priority` is `urgent` with a `priority:urgent` label and `high` with a `priority:high` label, and the engine starts the queued runs of those cards first. `create_card` and `set_labels` drop a priority label they are asked to write, and `set_labels` keeps the one the issue has. Only `set_priority` adds one: it adds `priority:<priority>` from the analysis, and is `skipped` when the issue has any `priority:` label already, so a person's label stays. Its cursor holds the repository and the GitHub page. It never lists a closed issue: the engine reads a card that a listing no longer has, and `card` answers `done` or `cancelled`. `card` answers `not_found` for a key that `repos` does not name, a pull request, a deleted issue (410), and an open issue out of scope, such as one whose title lost `title_prefix`, or with `assignee_only` one of someone else that has no `edgar:waiting`. A move of an open issue out of scope is `skipped` unless forced.
219
228
 
220
- A card carries the service of its repository in its block, because the block is where the engine reads a card's service. An issue with no block gets the block `{ kind = "request", service = "<service>" }`. A block that does not read makes `card` answer `invalid`, and `list_cards` reads it as no block.
229
+ A card carries the service of its repository in its block, because the block is where the engine reads a card's service. An issue with no block gets the block `{ kind = "request", service = "<service>" }`. A block that does not read makes `card` answer `invalid`, and `list_cards` carries it as `{ invalid = "<why>" }`, so the engine refuses the card with one comment that says why instead of working it as plain text.
221
230
 
222
- `comment` ends the body with a hidden marker, `<!-- edgar:op <hash> -->`, where the hash is the first 16 hex characters of the SHA-256 of the operation id. A retry looks for the marker on the issue's last page of comments and posts nothing when it finds it. `comments` takes the marker off the text, and sets `mentioned` when the text names `@<login>` of EDGAR.
231
+ `comment` ends the body with a hidden marker, `<!-- edgar:op <hash> -->`, where the hash is the first 16 hex characters of the SHA-256 of the operation id. A retry looks for the marker on the issue's last page of comments and posts nothing when it finds it. `comments` takes the marker off the text, and sets `mentioned` when the text names `@<login>` of EDGAR. GitHub's `since` is an update time, so `comments` answers each comment made or edited after it, and `edited_at` is `updated_at` when it differs from `created_at`. GitHub keeps no deleted comment, so `comments` never answers `deleted`.
223
232
 
224
- `create_card` files the issue in the repository whose service the block names, else in the first of `repos`. With a fingerprint, it first searches the open issues of every repository of `repos` for it, reads the block of each match, and on a match counts one more sighting on that issue and answers it. The sighting is counted from the issue read again with `GET /repos/{repo}/issues/{n}`, because the search and the issue list can answer an older body. The new issue gets `title_prefix`, `labels`, the label of `spec.column`, the marker of the operation, and with `assignee_only`, `assignee`. A retry finds the issue by its marker among the 10 newest issues of the repository. The search index can lag a new issue by a minute, so those 10 issues are also read for an open issue whose block holds the fingerprint, which counts as a match too. They are read in the target repository only: a card of one fingerprint names one service, so its issues go to one repository. Calls with one fingerprint run one at a time in the extension's process. Both the search and the issue list can miss an issue filed a second ago, so the process remembers the issue it filed or counted on for each fingerprint, and the next call reads that issue first with `GET /repos/{repo}/issues/{n}`, which answers at once. While it is open and its block holds the fingerprint, the call counts the sighting there; otherwise the call forgets it and searches. A retry of the operation that filed it answers that issue again.
233
+ `create_card` files the issue in the repository whose service the block names, else in the first of `repos`. When no open issue holds the fingerprint, it also searches the closed issues of `repos`, the most recently updated first, and reads the block of each match. An issue closed as completed less than 30 days before the sighting is opened again in `ready`, its body gets the line that the fault came back and one more sighting, and it is the answer. An issue closed as not planned, one closed longer ago, or one out of the table's scope stays closed, and the new issue ends with the line "The same fault was on <its URL>, closed as done on <date>." (or "cancelled on"). When a person, not EDGAR's own login or a `[bot]`, commented on that issue before it closed, the line goes on with `The last note there: "<their last comment>"`, cut to 280 characters, from the issue's first 100 comments (`GET .../issues/{n}/comments`). A comment read that fails leaves the note out and still files the issue. With a fingerprint, it first searches the open issues of every repository of `repos` for it, reads the block of each match, and on a match counts one more sighting on that issue and answers it. The sighting is counted from the issue read again with `GET /repos/{repo}/issues/{n}`, because the search and the issue list can answer an older body. The new issue gets `title_prefix`, `labels`, the label of `spec.column`, the marker of the operation, and with `assignee_only`, `assignee`. A retry finds the issue by its marker among the 10 newest issues of the repository. The search index can lag a new issue by a minute, so those 10 issues are also read for an open issue whose block holds the fingerprint, which counts as a match too. They are read in the target repository only: a card of one fingerprint names one service, so its issues go to one repository. Calls with one fingerprint run one at a time in the extension's process. Both the search and the issue list can miss an issue filed a second ago, so the process remembers the issue it filed or counted on for each fingerprint, and the next call reads that issue first with `GET /repos/{repo}/issues/{n}`, which answers at once. While it is open and its block holds the fingerprint, the call counts the sighting there; otherwise the call forgets it and searches. A retry of the operation that filed it answers that issue again.
234
+
235
+ `attachments` lists each file a person pasted into the issue's description or one of its first 100 comments: a Markdown link or image, or the HTML image GitHub writes for a pasted picture, to `github.com/user-attachments` or `user-images.githubusercontent.com`. Each file comes once by url, named by its link text, else by the last part of its url. The engine fetches a file only from a host in `[tracker] attachment_hosts` and follows no redirect. Older `user-images.githubusercontent.com` links answer with the file, so add that host to fetch them. Today's `github.com/user-attachments` links answer with a redirect to a short-lived address, so the agent's notes say each one could not be fetched, and the agent reads the comment's text alone.
225
236
 
226
237
  A label that a write sets and the repository lacks is made first. A label made, and EDGAR's login, are kept for the life of the runtime.
227
238
 
@@ -229,22 +240,30 @@ A label that a write sets and the repository lacks is made first. A label made,
229
240
 
230
241
  The tools have the names and schemas of the Linear tracker's tools, so the default workflows call them the same way once GitHub is a tracker of the project:
231
242
 
232
- | Tool | What it does |
233
- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
234
- | `comment` | `comment` of the port, with an optional `link` on its own line |
235
- | `move` | `move` of the port, answering `{ column }` |
236
- | `close` | closes the issue as completed, answering `{ state: "done" }` |
237
- | `create_card` | `create_card` of the port, answering `{ id, url }` |
238
- | `release_follow_ups` | searches the open issues for `waits_for = <card>`, reads each block, and moves each one in `intake` to `ready` |
239
- | `count_sighting` | raises `occurrences` and `last_seen` in the issue's block; a retry with the same `seen_at` writes nothing, and an issue with no block is not written. The sightings of one issue, from this tool and from `create_card`, are counted one at a time |
240
- | `batch_cards` | searches the open issues for `batch = <batch>`, and keeps at most 20 in scope whose `decided.batch` is the batch, leaving out `except`; with `only`, the others are `skipped` |
241
- | `find_cards` | searches the open issues in scope for the first 200 characters of `text`, without quotes or colons; with `except`, only issues made before that card |
242
- | `hand_back` | assigns the issue to the newest person who assigned it to EDGAR (`GET .../issues/{n}/events?per_page=100`), else to its writer, never EDGAR, an App or a bot, and adds `edgar:waiting` with `POST .../issues/{n}/labels`, made in the repository when it is missing; `skipped` when nobody can be given it |
243
- | `update_description` | replaces the issue's body and keeps its block; `restore_description` undoes it and `find_description` is its lookup |
244
- | `assign` | sets the issue's one assignee to a login, `me` for EDGAR, or nobody for an empty text; `restore_assignee` undoes it and `find_assignee` is its lookup; a login that GitHub does not have is `not_found` |
243
+ | Tool | What it does |
244
+ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
245
+ | `comment` | `comment` of the port, with an optional `link` on its own line |
246
+ | `move` | `move` of the port, answering `{ column }` |
247
+ | `close` | closes the issue as completed, answering `{ state: "done" }` |
248
+ | `create_card` | `create_card` of the port, answering `{ id, url }` |
249
+ | `park` | moves the issue to `intake` from any state, then writes `waits_for = <card>` into its block, a `request` block when it has none; an issue out of scope is skipped with nothing written |
250
+ | `release_follow_ups` | searches the open issues for `waits_for = <card>`, reads each block, and moves each one in `intake` to `ready`, or to `column` (`waiting_on_person` after a close with no merge) |
251
+ | `count_sighting` | raises `occurrences` and `last_seen` in the issue's block; a retry with the same `seen_at` writes nothing, and an issue with no block is not written. The sightings of one issue, from this tool and from `create_card`, are counted one at a time |
252
+ | `set_priority` | adds the label `priority:<priority>` that the analysis gave; `skipped` when the issue has a `priority:` label already, which stays |
253
+ | `retitle` | for an issue a feeder filed (its block names `decided.opened_by`), sets the title to the first sentence of `text`, cut at a word to 100 characters, after `title_prefix`, and changes nothing else: the block keeps the feeder's title in `decided.filed_as`, and a new title alone starts no run again; `skipped` for an issue a person wrote, or one already titled so |
254
+ | `batch_cards` | searches the open issues for `batch = <batch>`, and keeps at most 20 in scope whose `decided.batch` is the batch, leaving out `except`; with `only`, the others are `skipped` |
255
+ | `find_cards` | searches the open issues in scope for the first 200 characters of `text`, without quotes or colons; with `except`, only issues made before that card |
256
+ | `hand_back` | assigns the issue to the newest person who assigned it to EDGAR (`GET .../issues/{n}/events?per_page=100`), else to its writer, never EDGAR, an App or a bot, and adds `edgar:waiting` with `POST .../issues/{n}/labels`, made in the repository when it is missing; `skipped` when nobody can be given it |
257
+ | `mark_seen` | adds an eyes reaction to the issue with `POST .../issues/{n}/reactions`, answering `{ id }`; GitHub keeps one reaction of a kind for each account, so a repeat adds none |
258
+ | `update_description` | replaces the issue's body and keeps its block; `restore_description` undoes it and `find_description` is its lookup |
259
+ | `assign` | sets the issue's one assignee to a login, `me` for EDGAR, or nobody for an empty text; `restore_assignee` undoes it and `find_assignee` is its lookup; a login that GitHub does not have is `not_found` |
245
260
 
246
261
  The search tools call `GET /search/issues?q=<words> is:issue is:open repo:<each repository>&per_page=<n>`. GitHub's search has its own rate limit of 30 requests a minute.
247
262
 
263
+ ### Linked issues
264
+
265
+ The extension reads an issue of a repository in `[extensions.github.tracker] repos` that a card or its comments link, such as `https://github.com/<owner>/<repo>/issues/12`, into the run's inbox (`read_link`, for `github.com`). The text holds the issue's column, link, description and comments, with the same `card` and `comments` reads as the tracker port, so an issue out of the tracker's scope is a failure that the inbox shows in one line. A pull request, an issue of another repository, any other GitHub link, and every link of a project that does not use GitHub Issues as its tracker are not read.
266
+
248
267
  ### Token and App permissions
249
268
 
250
269
  | Use | Fine-grained token or App permission | Classic token scope |
@@ -255,7 +274,8 @@ The search tools call `GET /search/issues?q=<words> is:issue is:open repo:<each
255
274
 
256
275
  ```toml
257
276
  [extensions.github]
258
- default_base = "main" # the base branch of new pull requests; the default is "main"
277
+ default_base = "main" # the base branch of a new pull request whose call names no base; the default is "main"
278
+ pr_labels = ["edgar"] # optional: labels each pull request EDGAR opens gets; the default is none
259
279
  app = { id = 123456, installation = 7890123 } # optional: sign in as this GitHub App installation
260
280
 
261
281
  [extensions.github.watch] # optional: without it the service only waits
@@ -282,7 +302,11 @@ Every `every_seconds`, for each service of `watch.services` on github.com, the s
282
302
  | A failed check on the newest commit of `default_base` | `defect`, one for each workflow run, naming its failed jobs and the run URL, and one for each other failed check run | `lane = "fix"`, `commit`, `run`, `jobs` | the repository and the run URL, or the check run id |
283
303
  | A failed check on the head of a pull request `login` opened on an `edgar/<card>-…` branch | `defect`, "Checks failed on shop/api#42 of ENG-12", with the check summary | `lane = "fix"`, `card`, `pull_request`, `head_branch`, `commit` | the repository and the number |
284
304
 
285
- Each card has the service's name in `service`. A fingerprint this process opened is not asked for again, and the tracker answers a repeat with the open card that holds it, so a second sweep opens nothing twice. After a sweep that read every repository on github.com, a fingerprint whose fault is gone leaves the memory, so the memory holds only the faults that are still there. The built-in `remediate` fixes a card of red checks on EDGAR's own pull request in place: its stage `fix_pull_request` runs `revise` on `head_branch` from the head of `pull_request`, and opens no second pull request. While a run of the pull request's own card is open, it owns the checks: the engine answers the open of this card `skipped`, so no second fix races it on one branch, and the next sweep after that run ends opens the card if the checks are still red. A repository that fails goes to the log and the sweep goes on; a refused token (`unauthenticated`) ends the service with that failure, so its breaker opens. `GET /user` names `login` when it is not set; with `app` set and no `login`, the service ends `invalid` at start.
305
+ Each card has the service's name in `service`. A fingerprint this process opened is not asked for again, and the tracker answers a repeat with the open card that holds it, so a second sweep opens nothing twice. After a sweep that read every repository on github.com, a fingerprint whose fault is gone leaves the memory, so the memory holds only the faults that are still there. The built-in `remediate` fixes a card of red checks on EDGAR's own pull request in place: its stage `fix_pull_request` runs `revise` on `head_branch` from the head of `pull_request`, and opens no second pull request. It reviews a card of lane `review` with its stage `review_pull_request`, posts what it found on the pull request and on the card, and pushes nothing to that branch. While a run of the pull request's own card is open, it owns the checks: the engine answers the open of this card `skipped`, so no second fix races it on one branch, and the next sweep after that run ends opens the card if the checks are still red. A repository that fails goes to the log and the sweep goes on; a refused token (`unauthenticated`) ends the service with that failure, so its breaker opens. `GET /user` names `login` when it is not set; with `app` set and no `login`, the service ends `invalid` at start.
306
+
307
+ #### Mentions on EDGAR's pull requests
308
+
309
+ When a person writes a comment that mentions `login` on one of EDGAR's open pull requests, on an `edgar/<card>-…` branch, the watch puts the comment on that card with `ctx.cards.reply`, as that person's reply, when that person is on the team by the rule of a card's `trust`. The card holds a reply as EDGAR's own comment, so a mention from outside the team stays on the pull request, and the log names its writer. The engine then reads it as a comment on the card, so the run that holds the card answers or resumes from it, as for a comment written on the card itself. Each sweep reads the issue comments made since the last sweep that read every repository, one request for each repository with an EDGAR pull request open (`GET /repos/{owner}/{repo}/issues/comments?since=`), and keeps a comment when it is newer than that time, it is not by `login`, and it mentions `login` with the same rule as the tracker's `comments`. Only comments made after the service started count, and a sweep reads at most 100 comments of a repository. A mention on a pull request that EDGAR did not open is not relayed, and EDGAR answers on the card, not on the pull request. A reply that the engine refuses goes to the log. The sweep's log line counts the comments put on cards in `relayed`.
286
310
 
287
311
  ### The Dependabot feed
288
312
 
@@ -343,7 +367,16 @@ github dependabot: {"read":2,"filed":1,"tracked":4,"held":0,"below":3,"wait":0}
343
367
 
344
368
  `read` counts the repositories that answered. `filed` counts the new cards. `tracked` counts the cards that this process opened before. `held` counts the cards that wait for the next sweep. `below` counts the alerts under `severity_min`. `wait` is the number of seconds that GitHub asked for after a rate limit.
345
369
 
346
- The feed does not close a card when GitHub marks its alert as fixed.
370
+ When an advisory leaves the open alerts after a sweep that read every repository, the feed reads again one alert of the card it opened, with `GET /repos/{owner}/{repo}/dependabot/alerts/{number}`, and acts on its state:
371
+
372
+ | State of the alert | What the feed does |
373
+ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
374
+ | `fixed` | It comments that GitHub reports the alert fixed, with its link, and closes the card. |
375
+ | `dismissed`, `auto_dismissed` | It comments who dismissed the alert, with GitHub's reason and the person's comment, that the fault is not fixed, and that EDGAR files it again if it opens, and closes the card. |
376
+ | `open` | It forgets the card and leaves it open: the alert is past the page that was read, or under a raised `severity_min`. |
377
+ | The read or a write fails | For now, it tries again at the next sweep. For good, it forgets the card and leaves it open. The log names the card. |
378
+
379
+ The comment and the close go through the project's tracker, with the capability `tracker:write` of the service. A tracker that leaves a card alone, such as a card out of its scope, answers `skipped`, and the feed forgets the card.
347
380
 
348
381
  ### Sign in as a GitHub App
349
382
 
@@ -363,28 +396,50 @@ EDGAR's own git, which clones, fetches and pushes each repository, gets an insta
363
396
  git_tokens = { "github.com" = { extension = "github" } }
364
397
  ```
365
398
 
366
- The extension's `git_credential` then answers the engine's ask for `github.com` with the held installation token, or a new one, and its `expires_at`. The engine asks again when the token it holds expires within five minutes, and keeps the token in memory only. The App needs `contents: write` on each repository of `[services]`. With no `app`, `git_credential` answers `GITHUB_TOKEN` itself, with no expiry. An ask for another host is `permanent_failure(invalid)`. With `app` set and `git_tokens` still naming `GITHUB_TOKEN`, `edgar check` reports a `C005` error, because git cannot send the private key as a token.
399
+ The extension's `git_credential` then answers the engine's ask for `github.com` with the held installation token, or a new one, and its `expires_at`. Each token covers only the repository of the git step, and `contents: read` for a clone or fetch or `contents: write` for a push; a submodule fill gets `contents: read` on the installation's repositories. The extension holds one token for each repository and access. For a push, the extension first reads the permissions the installation was granted (`GET /app/installations/<id>`, held for an hour) and also asks for `workflows: write` when the installation holds it, so a change to a file under `.github/workflows` still pushes. Without that permission on the App, GitHub refuses such a push. A tool call with `app` set gets a token of its own too: one that covers only the repository its request names, at `read` for each granted permission that the tools read with (`actions`, `administration`, `checks`, `contents`, `issues`, `metadata`, `pull_requests`, `security_events`, `statuses`, `vulnerability_alerts`) for a `GET`, and with every granted permission of that repository for any other call. `revert_pull_request` names its pull request's repository for its GraphQL call. Only the calls that span repositories send the installation's token: the issue search of the GitHub Issues tracker across the repositories of `[extensions.github.tracker]`, and the read of a user's public profile. The engine asks again when the token it holds expires within five minutes, and keeps the token in memory only. The App needs `contents: write` on each repository of `[services]`. With no `app`, `git_credential` answers `GITHUB_TOKEN` itself, with no expiry and no narrower scope. An ask for another host is `permanent_failure(invalid)`. With `app` set and `git_tokens` still naming `GITHUB_TOKEN`, `edgar check` reports a `C005` error, because git cannot send the private key as a token.
367
400
 
368
401
  `push_branch` runs git in the sandbox, and EDGAR gives that git no token, with or without an App: it pushes with the credentials that git in the sandbox has. The built-in workflows push in their `push` stage, with EDGAR's own git, so they push with the App.
369
402
 
403
+ ### Signed commits
404
+
405
+ A repository whose protected branches require signed commits refuses EDGAR's pushes, because `git push` sends them unsigned. GitHub signs a commit that a GitHub App makes through its API, so the extension can publish EDGAR's pushes for `github.com` in place of git:
406
+
407
+ ```toml
408
+ [sandbox]
409
+ signed_commits = { "github.com" = "github" }
410
+ ```
411
+
412
+ For each push, the extension's `publish_commits` gets EDGAR's plan, and uses the Git Data API of the repository:
413
+
414
+ 1. It reads the tree of the plan's `base` commit (`GET /git/commits/<base>`).
415
+ 2. For each commit, oldest first, it uploads each file the commit writes (`POST /git/blobs`, each blob once for the whole push), then makes the commit's tree on the tree before (`POST /git/trees` with `base_tree`; a deleted file is an entry with `sha: null`), then the commit on the commit before (`POST /git/commits`), with no `author` or `committer`, so GitHub writes the App and signs the commit.
416
+ 3. It makes the branch (`POST /git/refs`) or moves it (`PATCH /git/refs/heads/<branch>` with `force: false`).
417
+
418
+ It checks that the id of each blob and tree that GitHub makes equals EDGAR's. When one differs, it stops with `permanent_failure(tool_error)` before it makes any commit of that tree or moves the branch, and the message says "nothing was published". A branch that moved on GitHub since EDGAR read it is `permanent_failure(invalid)` from the `422` of the ref move, and the branch stays where it was. A plan for another host is `permanent_failure(invalid)`, with no request. The calls need `contents: write` on the repository, and `workflows: write` for a change under `.github/workflows`.
419
+
420
+ Only an App's commits are signed. With no `app`, the calls use `GITHUB_TOKEN`, and GitHub makes the same commits, with the token's user as their author, unsigned.
421
+
370
422
  ## Secrets
371
423
 
372
- - `GITHUB_TOKEN`: a token that can push, open and merge pull requests, or the App's private key when `app` is set. It reaches only `api.github.com`. EDGAR's own git sends the token to `github.com` as `[sandbox] git_tokens` says, or with `{ extension = "github" }`, an installation token that the extension mints.
424
+ - `GITHUB_TOKEN`: a token that can push, open and merge pull requests, or the App's private key when `app` is set. It is sent only to `api.github.com`. Its hosts also list the two hosts where GitHub redirects a job log for `ci_run`, as a shortcut under [Shortcuts](#shortcuts) says. EDGAR's own git sends the token to `github.com` as `[sandbox] git_tokens` says, or with `{ extension = "github" }`, an installation token that the extension mints.
373
425
 
374
426
  ### What the token must be able to do
375
427
 
376
- | Tools | Fine-grained token or App permission | Classic token scope |
377
- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------- |
378
- | `open_pull_request`, `close_pull_request`, `update_pull_request`, `merge_pull_request` | `pull_requests: write`; `contents: write` for a merge | `repo` (`public_repo` for a public repository) |
379
- | `attach_screenshot` | `contents: write`, `pull_requests: write` | `repo` (`public_repo` for a public repository) |
380
- | `labels` of `open_pull_request` | `issues: write` or `pull_requests: write` | `repo` |
381
- | `note_pull_request` | `issues: write` or `pull_requests: write` | `repo` |
382
- | `pull_request_*`, `find_pull_request`, `linked_pull_requests`, `list_pull_requests` | `pull_requests: read` | `repo` |
383
- | `pull_request_checks` | `checks: read`, `statuses: read` | `repo` |
384
- | `ci_run` | `actions: read` | `repo` |
385
- | `dependabot_alerts`, `find_dependabot_dismissal`, the Dependabot feed | `dependabot_alerts: read` | `security_events` or `repo` |
386
- | `dismiss_dependabot_alert`, `reopen_dependabot_alert` | `dependabot_alerts: write` | `security_events` or `repo` |
387
- | `branch_protection` | `metadata: read`; `administration: read` for the classic rule | `repo` |
428
+ | Tools | Fine-grained token or App permission | Classic token scope |
429
+ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | ---------------------------------------------- |
430
+ | `open_pull_request`, `close_pull_request`, `update_pull_request`, `merge_pull_request` | `pull_requests: write`; `contents: write` for a merge | `repo` (`public_repo` for a public repository) |
431
+ | `attach_screenshot` | `contents: write`, `pull_requests: write` | `repo` (`public_repo` for a public repository) |
432
+ | `labels` of `open_pull_request` | `issues: write` or `pull_requests: write` | `repo` |
433
+ | `note_pull_request` | `issues: write` or `pull_requests: write` | `repo` |
434
+ | `pull_request_*`, `wait_for_review`, `wait_for_merge`, `find_pull_request`, `linked_pull_requests`, `list_pull_requests` | `pull_requests: read` | `repo` |
435
+ | `delete_closed_branches` | `contents: write`, `pull_requests: read` | `repo` (`public_repo` for a public repository) |
436
+ | `revert_pull_request` | `contents: write`, `pull_requests: write` | `repo` (`public_repo` for a public repository) |
437
+ | `merged_pull_request`, `find_revert_pull_request` | `pull_requests: read` | `repo` |
438
+ | `pull_request_checks`, `wait_for_checks`, `wait_for_passed_checks` | `checks: read`, `statuses: read` | `repo` |
439
+ | `ci_run` | `actions: read` | `repo` |
440
+ | `dependabot_alerts`, `find_dependabot_dismissal`, the Dependabot feed | `dependabot_alerts: read` | `security_events` or `repo` |
441
+ | `dismiss_dependabot_alert`, `reopen_dependabot_alert` | `dependabot_alerts: write` | `security_events` or `repo` |
442
+ | `branch_protection` | `metadata: read`; `administration: read` for the classic rule | `repo` |
388
443
 
389
444
  No check reads a token's rights ahead of its first call: the engine runs no extension at `edgar check`. GitHub says what a refused call needs in `X-Accepted-GitHub-Permissions` (fine-grained tokens and Apps) or `X-Accepted-OAuth-Scopes` (classic tokens). A 403 that is not a rate limit is `permanent_failure(forbidden)`, which the engine does not retry, and its message names that header's value:
390
445
 
@@ -397,7 +452,7 @@ No check reads a token's rights ahead of its first call: the engine runs no exte
397
452
  }
398
453
  ```
399
454
 
400
- - `GITHUB_WEBHOOK_SECRET`: the engine checks the `hmac-sha256` signature of `/hooks/github/events` with it. The delivery id is `X-GitHub-Delivery`. Until EDGAR serves a webhook route, it needs no entry in `[secrets]` and no value.
455
+ - `GITHUB_WEBHOOK_SECRET`: optional. When GitHub Issues is a tracker of the project, the API checks the `hmac-sha256` signature in `X-Hub-Signature-256` of each `POST /hooks/github/events` with it, and a delivery that matches brings the next sweep forward; its body is never read. Without a value the route is not served, and EDGAR finds each change at its next sweep. The delivery id is `X-GitHub-Delivery`.
401
456
 
402
457
  ## Errors
403
458
 
@@ -457,6 +512,7 @@ Run on 2026-11-11 in `packages/extensions/ext-github`. The answer shapes of chec
457
512
 
458
513
  - shortcut: the watch service gets the repositories from `[extensions.github.watch] services`, not from the project's `[services]`, because a service's context carries only its own table. Upgrade when the engine hands a service the project's services.
459
514
  - shortcut: what the watch service filed lives in memory, so a restart asks for each open card again and the tracker answers with the card it has. Upgrade when a service can keep state.
515
+ - shortcut: the time of the last read of mentions lives in memory, so a mention made while EDGAR was stopped is not read, and a review comment on a line of the diff is not read. Upgrade when a service can keep state.
460
516
  - shortcut: red checks on EDGAR's own pull request open a card that names the pull request's card, because a service can neither comment on a card nor start a sub-run of its run. Upgrade when the engine takes a comment from a service.
461
517
 
462
518
  - shortcut: `pull_request_checks`, `pull_request_discussion` and `dependabot_alerts` read one page of 100 each, and `ci_run` reads the jobs of the latest attempt only. Upgrade to `Link` pagination and `attempts/<n>/jobs` when a re-run that passed hides the failure a card is about.
@@ -465,13 +521,13 @@ Run on 2026-11-11 in `packages/extensions/ext-github`. The answer shapes of chec
465
521
  - shortcut: the Dependabot feed gets its repositories from `[extensions.github.dependabot] services`, for the same reason as the watch.
466
522
  - shortcut: the Dependabot feed reads one page of the 100 newest open alerts of each repository, and writes one log line for a repository with a full page. Upgrade to `Link` pagination when a repository holds more open alerts at one time.
467
523
  - shortcut: what the Dependabot feed filed lives in memory. After a restart it asks for each open card again, and an alert that is still open after its card closed gets a new card. Upgrade when a service can keep state.
468
- - shortcut: the Dependabot feed opens cards only. It does not close a card when its alert is fixed, because a service cannot close a card. Upgrade when the engine takes a close from a service.
524
+ - shortcut: the Dependabot feed closes only the cards that this process opened, so an alert fixed while EDGAR was stopped leaves its card open. Upgrade when a service can keep state.
469
525
  - shortcut: `dismiss_dependabot_alert` reads an alert that holds its own `reason` and `comment` as its own. A person who dismissed with the same words is read as the call, so the undo opens that alert again. Upgrade when GitHub's answer says which call dismissed the alert.
470
526
  - shortcut: the compare that the body notices read lists at most 300 files.
471
527
  - shortcut: pull request lists and reviews read one page of 100. Upgrade to `Link` pagination when a repository holds more than 100 open pull requests.
472
528
  - shortcut: `find_pull_request` matches by branch. The `edgar-operation` line is for people and audits. Upgrade to matching the line if two operations can share a branch.
473
529
  - shortcut: `push_branch` pushes the sandbox's `origin` and does not compare it with `repo`. Upgrade when one sandbox holds several repositories.
474
- - shortcut: the tracker port reads no webhook: the engine sweeps it like any tracker. Upgrade when the engine takes tracker events from a webhook.
530
+ - shortcut: a webhook delivery only wakes the sweep; the engine reads every change by sweeping. Upgrade when the engine takes tracker events from a webhook's body.
475
531
  - shortcut: the tracker port does not use the status of GitHub Projects; labels hold the column. Upgrade when a project wants its board as the columns.
476
532
  - shortcut: `comments` reads the first page of 100 comments after `since`, and `comment` looks for its marker on the last page only. Upgrade to `Link` pagination when an issue gets more than 100 comments between two sweeps.
477
533
  - shortcut: `create_card` does not use `parent`, because a GitHub sub-issue needs the issue's numeric id and its own call. Upgrade when a workflow files sub-cards on GitHub.