@kana-ai/edgar-ext-github 0.0.0-stage → 0.1.0
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.
- package/LICENSE +202 -0
- package/README.md +469 -2
- package/agents/dismiss/agent.toml +4 -0
- package/agents/dismiss/instructions.md +25 -0
- package/dist/src/api/app.d.ts +16 -0
- package/dist/src/api/app.js +32 -0
- package/dist/src/api/client.d.ts +26 -0
- package/dist/src/api/client.js +103 -0
- package/dist/src/api/failures.d.ts +8 -0
- package/dist/src/api/failures.js +31 -0
- package/dist/src/feed/alerts.d.ts +26 -0
- package/dist/src/feed/alerts.js +117 -0
- package/dist/src/feed/cards.d.ts +32 -0
- package/dist/src/feed/cards.js +164 -0
- package/dist/src/feed/service.d.ts +28 -0
- package/dist/src/feed/service.js +163 -0
- package/dist/src/index.d.ts +490 -0
- package/dist/src/index.js +62 -0
- package/dist/src/schemas/config.d.ts +57 -0
- package/dist/src/schemas/config.js +89 -0
- package/dist/src/schemas/github.d.ts +417 -0
- package/dist/src/schemas/github.js +216 -0
- package/dist/src/schemas/tools.d.ts +620 -0
- package/dist/src/schemas/tools.js +501 -0
- package/dist/src/tools/alerts.d.ts +45 -0
- package/dist/src/tools/alerts.js +100 -0
- package/dist/src/tools/branch.d.ts +9 -0
- package/dist/src/tools/branch.js +48 -0
- package/dist/src/tools/checks.d.ts +118 -0
- package/dist/src/tools/checks.js +223 -0
- package/dist/src/tools/discussion.d.ts +41 -0
- package/dist/src/tools/discussion.js +66 -0
- package/dist/src/tools/pull-request.d.ts +195 -0
- package/dist/src/tools/pull-request.js +537 -0
- package/dist/src/tools/repository.d.ts +53 -0
- package/dist/src/tools/repository.js +134 -0
- package/dist/src/tools/screenshot.d.ts +21 -0
- package/dist/src/tools/screenshot.js +99 -0
- package/dist/src/tracker/assignee.d.ts +15 -0
- package/dist/src/tracker/assignee.js +65 -0
- package/dist/src/tracker/cards.d.ts +41 -0
- package/dist/src/tracker/cards.js +361 -0
- package/dist/src/tracker/comments.d.ts +9 -0
- package/dist/src/tracker/comments.js +68 -0
- package/dist/src/tracker/description.d.ts +19 -0
- package/dist/src/tracker/description.js +55 -0
- package/dist/src/tracker/hand-back.d.ts +8 -0
- package/dist/src/tracker/hand-back.js +60 -0
- package/dist/src/tracker/port.d.ts +2 -0
- package/dist/src/tracker/port.js +42 -0
- package/dist/src/tracker/states.d.ts +77 -0
- package/dist/src/tracker/states.js +189 -0
- package/dist/src/tracker/tools.d.ts +143 -0
- package/dist/src/tracker/tools.js +131 -0
- package/dist/src/tracker/transitions.d.ts +12 -0
- package/dist/src/tracker/transitions.js +101 -0
- package/edgar-extension.json +507 -0
- package/package.json +43 -3
- package/schemas/assign.in.json +15 -0
- package/schemas/assign.out.json +14 -0
- package/schemas/attach_screenshot.in.json +44 -0
- package/schemas/attach_screenshot.out.json +31 -0
- package/schemas/batch_cards.in.json +27 -0
- package/schemas/batch_cards.out.json +37 -0
- package/schemas/branch_protection.in.json +15 -0
- package/schemas/branch_protection.out.json +67 -0
- package/schemas/ci_run.in.json +12 -0
- package/schemas/ci_run.out.json +109 -0
- package/schemas/close.in.json +14 -0
- package/schemas/close.out.json +10 -0
- package/schemas/close_pull_request.in.json +21 -0
- package/schemas/close_pull_request.out.json +14 -0
- package/schemas/comment.in.json +19 -0
- package/schemas/comment.out.json +10 -0
- package/schemas/config.json +202 -0
- package/schemas/count_sighting.in.json +17 -0
- package/schemas/count_sighting.out.json +10 -0
- package/schemas/create_card.in.json +108 -0
- package/schemas/create_card.out.json +13 -0
- package/schemas/dependabot_alerts.in.json +49 -0
- package/schemas/dependabot_alerts.out.json +75 -0
- package/schemas/dismiss_dependabot_alert.in.json +26 -0
- package/schemas/dismiss_dependabot_alert.out.json +27 -0
- package/schemas/find_assignee.in.json +15 -0
- package/schemas/find_assignee.out.json +10 -0
- package/schemas/find_cards.in.json +18 -0
- package/schemas/find_cards.out.json +33 -0
- package/schemas/find_dependabot_dismissal.in.json +12 -0
- package/schemas/find_dependabot_dismissal.out.json +27 -0
- package/schemas/find_description.in.json +15 -0
- package/schemas/find_description.out.json +10 -0
- package/schemas/find_pull_request.in.json +25 -0
- package/schemas/find_pull_request.out.json +14 -0
- package/schemas/hand_back.in.json +11 -0
- package/schemas/hand_back.out.json +18 -0
- package/schemas/linked_pull_requests.in.json +15 -0
- package/schemas/linked_pull_requests.out.json +44 -0
- package/schemas/list_pull_requests.in.json +26 -0
- package/schemas/list_pull_requests.out.json +42 -0
- package/schemas/merge_pull_request.in.json +22 -0
- package/schemas/merge_pull_request.out.json +16 -0
- package/schemas/move.in.json +15 -0
- package/schemas/move.out.json +10 -0
- package/schemas/note_pull_request.in.json +15 -0
- package/schemas/note_pull_request.out.json +10 -0
- package/schemas/open_pull_request.in.json +113 -0
- package/schemas/open_pull_request.out.json +15 -0
- package/schemas/pull_request_checks.in.json +11 -0
- package/schemas/pull_request_checks.out.json +72 -0
- package/schemas/pull_request_discussion.in.json +11 -0
- package/schemas/pull_request_discussion.out.json +107 -0
- package/schemas/pull_request_state.in.json +11 -0
- package/schemas/pull_request_state.out.json +52 -0
- package/schemas/push_branch.in.json +21 -0
- package/schemas/push_branch.out.json +13 -0
- package/schemas/release_follow_ups.in.json +15 -0
- package/schemas/release_follow_ups.out.json +13 -0
- package/schemas/reopen_dependabot_alert.in.json +33 -0
- package/schemas/reopen_dependabot_alert.out.json +22 -0
- package/schemas/restore_assignee.in.json +20 -0
- package/schemas/restore_assignee.out.json +10 -0
- package/schemas/restore_description.in.json +20 -0
- package/schemas/restore_description.out.json +10 -0
- package/schemas/update_description.in.json +15 -0
- package/schemas/update_description.out.json +14 -0
- package/schemas/update_pull_request.in.json +81 -0
- package/schemas/update_pull_request.out.json +10 -0
- package/schemas/wait_for_checks.in.json +11 -0
- package/schemas/wait_for_checks.out.json +72 -0
- package/schemas/wait_for_merge.in.json +11 -0
- package/schemas/wait_for_merge.out.json +17 -0
- package/schemas/wait_for_passed_checks.in.json +11 -0
- package/schemas/wait_for_passed_checks.out.json +72 -0
- package/schemas/wait_for_review.in.json +11 -0
- package/schemas/wait_for_review.out.json +52 -0
- package/workflows/resume.toml +17 -0
package/README.md
CHANGED
|
@@ -1,3 +1,470 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @kana-ai/edgar-ext-github
|
|
2
2
|
|
|
3
|
-
|
|
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.
|
|
4
|
+
|
|
5
|
+
## Tools
|
|
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. |
|
|
32
|
+
|
|
33
|
+
`repo` is `owner/name`, `git@github.com:owner/name.git` or `https://github.com/owner/name`.
|
|
34
|
+
|
|
35
|
+
### Wait for a review
|
|
36
|
+
|
|
37
|
+
A `wait` stage rechecks the pull request until a review decides:
|
|
38
|
+
|
|
39
|
+
```toml
|
|
40
|
+
[stages.wait_review]
|
|
41
|
+
needs = ["open"]
|
|
42
|
+
wait = { key = "stages.open.output.url", timeout_seconds = 604800, recheck = { tool = "github__wait_for_review", every_seconds = 60 } }
|
|
43
|
+
```
|
|
44
|
+
|
|
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.
|
|
46
|
+
|
|
47
|
+
### Wait for CI
|
|
48
|
+
|
|
49
|
+
A `wait` stage rechecks the pull request until its checks settle:
|
|
50
|
+
|
|
51
|
+
```toml
|
|
52
|
+
[stages.ci]
|
|
53
|
+
needs = ["open"]
|
|
54
|
+
wait = { key = "stages.open.output.url", timeout_seconds = 3600, recheck = { tool = "github__wait_for_checks", every_seconds = 60 } }
|
|
55
|
+
input = { url = "stages.open.output.url" }
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
While a check runs, the recheck answers `skipped` and EDGAR calls it again after 60 seconds. When every check has ended, the wait ends `done` with, for example:
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{
|
|
62
|
+
"url": "https://github.com/shop/api/pull/42",
|
|
63
|
+
"commit": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
|
|
64
|
+
"state": "failed",
|
|
65
|
+
"checks": 3,
|
|
66
|
+
"failed": [
|
|
67
|
+
{
|
|
68
|
+
"name": "test",
|
|
69
|
+
"url": "https://github.com/shop/api/actions/runs/42830265344/job/129878241297"
|
|
70
|
+
}
|
|
71
|
+
],
|
|
72
|
+
"retry_after_seconds": null,
|
|
73
|
+
"summary": "1 of 3 checks failed: test (https://github.com/shop/api/actions/runs/42830265344/job/129878241297)."
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
A later stage reads `stages.ci.output.state`, and gives a failed check's `url` to `ci_run` for the log. A commit with no check run and no status is `passed`. GitHub registers the checks of a new commit some seconds after the push, so `wait_for_checks` answers `skipped` for a pull request with no check that was updated less than 2 minutes ago; after that, no check is `passed`. A comment or a label also updates the pull request, and starts the 2 minutes again. A check that GitHub registers later than that is not seen: the tool does not read which checks the branch requires. GitHub answers `state: "pending"` for the combined status of a commit with no status at all, so the tool reads each status, not the combined state.
|
|
78
|
+
|
|
79
|
+
### Body notices and labels
|
|
80
|
+
|
|
81
|
+
Each extra is optional. With none, `open_pull_request` sends one request, as before.
|
|
82
|
+
|
|
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.`
|
|
85
|
+
- `path_notices`: a list of `{ prefix, notice }`. When a changed file's path starts with `prefix`, the body carries `notice`, once.
|
|
86
|
+
|
|
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.
|
|
89
|
+
- `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
|
+
|
|
91
|
+
The built-in `remediate` passes `large_diff_lines = 200`, and the `[[services.<name>.path_notices]]` of the card's service.
|
|
92
|
+
|
|
93
|
+
The size and the paths come from `GET /repos/{owner}/{repo}/compare/{base}...{branch}`, read before the pull request opens. When the compare call fails, the pull request opens with no large-change line and no path notice, and the failure goes to the runtime log, because an optional warning never costs a finished fix its pull request. The notices go after `body`, then the proof, then the review line:
|
|
94
|
+
|
|
95
|
+
```toml
|
|
96
|
+
input = { repo = "...", branch = "...", title = "...", body = "...", review = "", labels = [
|
|
97
|
+
"edgar",
|
|
98
|
+
], large_diff_lines = 200, path_notices = [
|
|
99
|
+
{ prefix = "web/", notice = "**Frontend affected.**" },
|
|
100
|
+
] }
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
The proof of a change with `checks` and `not_verified` reads:
|
|
104
|
+
|
|
105
|
+
```text
|
|
106
|
+
**Verified:**
|
|
107
|
+
- `lint` passed
|
|
108
|
+
- `unit` passed
|
|
109
|
+
|
|
110
|
+
**Not verified:**
|
|
111
|
+
- `e2e` ended with exit code 1
|
|
112
|
+
- `load` did not run or did not end
|
|
113
|
+
- The mail that the new rule sends.
|
|
114
|
+
```
|
|
115
|
+
|
|
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.
|
|
117
|
+
|
|
118
|
+
### Dismiss a Dependabot alert
|
|
119
|
+
|
|
120
|
+
`dismiss_dependabot_alert` writes a person's decision on the alert at GitHub. Each call waits for a person's approval.
|
|
121
|
+
|
|
122
|
+
The tool reads the alert first, with `GET /repos/{owner}/{repo}/dependabot/alerts/{number}`. Then it acts on the state of the alert:
|
|
123
|
+
|
|
124
|
+
| State of the alert | What the tool does | `reopen` |
|
|
125
|
+
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------- | -------- |
|
|
126
|
+
| `open` | It sends `PATCH` with `state: "dismissed"`, `dismissed_reason` and `dismissed_comment`. | `true` |
|
|
127
|
+
| `dismissed`, with the same `reason` and `comment` | It writes nothing. An earlier attempt of the same call dismissed the alert. | `true` |
|
|
128
|
+
| `dismissed`, with another reason or comment | It writes nothing. `reason` in the output is the reason that the alert holds. | `false` |
|
|
129
|
+
| `fixed` or `auto_dismissed` | It sends the `PATCH`, and GitHub decides. A refusal is `invalid`, with GitHub's message in `cause`. | `false` |
|
|
130
|
+
|
|
131
|
+
The extension adds two stages to the built-in `resume` workflow, in `workflows/resume.toml`, and the role `dismiss`, in `agents/dismiss`. When a person replies on a card of Dependabot alerts that waits on them, and decides that the alerts are not to be fixed, `classify_intent` gives `dismiss`. The `dismiss` stage lists the open alerts of the card's advisory and package with `dependabot_alerts`, so it also finds the alerts past the 20 that a card lists. It takes one of GitHub's reasons from the person's words, and dismisses each open alert, with a comment of at most 280 characters. When the words fit no reason, it dismisses nothing and asks. `say_dismissed` puts on the card which alerts were dismissed and which were left alone. A project turns this off in its own `workflows/resume.toml`, with `disabled = true` on both stages, because `say_dismissed` needs `dismiss`:
|
|
132
|
+
|
|
133
|
+
```toml
|
|
134
|
+
version = 1
|
|
135
|
+
|
|
136
|
+
[stages.dismiss]
|
|
137
|
+
disabled = true
|
|
138
|
+
|
|
139
|
+
[stages.say_dismissed]
|
|
140
|
+
disabled = true
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
An approval covers the manifest and each file that EDGAR loads from the extension, the layer and the role too. This version adds both, so after the upgrade each project runs `edgar extensions approve github` again.
|
|
144
|
+
|
|
145
|
+
A stage of your own that dismisses an alert reads the number, the reason and the comment from an earlier stage. Here that stage is `decide`, a stage of your own workflow:
|
|
146
|
+
|
|
147
|
+
```toml
|
|
148
|
+
[stages.dismiss]
|
|
149
|
+
needs = ["decide"]
|
|
150
|
+
tool = "github__dismiss_dependabot_alert"
|
|
151
|
+
input = { repo = "trigger.card.service.repo", number = "stages.decide.output.alert", reason = "stages.decide.output.reason", comment = "stages.decide.output.comment" }
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
The stage ends with, for example:
|
|
155
|
+
|
|
156
|
+
```json
|
|
157
|
+
{
|
|
158
|
+
"outcome": "done",
|
|
159
|
+
"output": {
|
|
160
|
+
"repo": "shop/api",
|
|
161
|
+
"number": 3,
|
|
162
|
+
"url": "https://github.com/shop/api/security/dependabot/3",
|
|
163
|
+
"reason": "not_used",
|
|
164
|
+
"reopen": true
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
When the run fails later, EDGAR calls `reopen_dependabot_alert` with that output. The alert opens again only when `reopen` is `true`. An alert that a person dismissed before the call stays dismissed.
|
|
170
|
+
|
|
171
|
+
## Tracker
|
|
172
|
+
|
|
173
|
+
The extension holds a tracker port over GitHub Issues, in `src/tracker/`. One project tracks the issues of several repositories at the same time. The manifest declares the port, and the engine takes GitHub as a tracker of the project only when the project writes `[extensions.github.columns]`: a project that enables GitHub beside Linear for its pull requests keeps Linear as its one tracker. When GitHub is a tracker of the project, the cards that the watch service and the Dependabot feed open go to GitHub Issues, in the repository of `repos` whose service the card names, else the first one.
|
|
174
|
+
|
|
175
|
+
### Configure it
|
|
176
|
+
|
|
177
|
+
Write `[extensions.github.columns]` and `[extensions.github.tracker]` together: the `columns` table is what makes GitHub Issues a tracker of the project, so nothing gives it a default. A project that enables GitHub only for pull requests writes neither table.
|
|
178
|
+
|
|
179
|
+
```toml
|
|
180
|
+
[extensions.github.columns] # the label of each open engine state; write each one
|
|
181
|
+
intake = "edgar:intake"
|
|
182
|
+
ready = "edgar:ready"
|
|
183
|
+
working = "edgar:working"
|
|
184
|
+
in_review = "edgar:in_review"
|
|
185
|
+
waiting_on_person = "edgar:waiting_on_person"
|
|
186
|
+
in_testing = "edgar:in_testing"
|
|
187
|
+
|
|
188
|
+
[extensions.github.tracker]
|
|
189
|
+
repos = { API = { repo = "shop/api", service = "api" }, WEB = { repo = "shop/web", service = "web" } }
|
|
190
|
+
title_prefix = "[v2]" # optional: only issues whose title starts with it
|
|
191
|
+
labels = ["edgar"] # optional: only issues that have each of these labels
|
|
192
|
+
assignee_only = false # the default; true: only issues assigned to assignee, or labelled edgar:waiting
|
|
193
|
+
assignee = "edgar-bot" # optional: the default is GITHUB_TOKEN's login; an App needs it, such as edgar[bot]
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
Each key of `repos` is 1 to 10 capitals or digits, starting with a capital. The id of a card is the key, a hyphen, and the issue number, such as `API-123`, so the `edgar/API-123-...` branches of the pull request tools name the card. The engine reads `[extensions.github.columns]` to know the states it lists, as it reads Linear's columns. The extension refuses one table without the other, and a `columns` table that leaves out a state. With neither table, each method answers `permanent_failure(invalid)` with a message that says to write both.
|
|
197
|
+
|
|
198
|
+
### Columns
|
|
199
|
+
|
|
200
|
+
An open issue is in the state of its column label; with two column labels, the state that comes last in the engine's order. An open issue with no column label is `intake` when it is in scope, so a person who files `[v2] Login fails` gives EDGAR the card. A closed issue is `done`, or `cancelled` when GitHub closed it as not planned or as a duplicate. `done` and `cancelled` are not labels: a move to `done` closes the issue as `completed`, and a move to `cancelled` closes it as `not_planned`, with its column labels taken off. A move to an open state adds its column label, takes the other column labels off, and opens a closed issue again. A move adds and takes off one label at a time, so a label that a person sets in the meantime stays; a label that is already gone is fine. A card's `labels` leave out the column labels.
|
|
201
|
+
|
|
202
|
+
### Methods
|
|
203
|
+
|
|
204
|
+
| Method | GitHub calls |
|
|
205
|
+
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
206
|
+
| `list_cards` | `GET /repos/{repo}/issues?state=open&sort=created&direction=asc&per_page=50&page={n}`, with `labels` from the table |
|
|
207
|
+
| `card` | `GET /repos/{repo}/issues/{n}` |
|
|
208
|
+
| `comments` | `GET /repos/{repo}/issues/{n}/comments?per_page=100&since={since}`, and `GET /user` once |
|
|
209
|
+
| `attachments` | none: it answers an empty list |
|
|
210
|
+
| `comment` | `GET /repos/{repo}/issues/{n}`, `GET .../comments?per_page=100&page={last}` when the issue has comments, `POST .../comments` |
|
|
211
|
+
| `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
|
+
| `set_labels` | `GET` and `PATCH /repos/{repo}/issues/{n}`, with the labels made as for `move` |
|
|
213
|
+
| `create_card` | `GET /search/issues?q=...&per_page=5` for a fingerprint, `GET /repos/{repo}/issues?state=all&sort=created&direction=desc&per_page=10` for the marker and an open issue of the fingerprint, `GET` and `PATCH .../{n}` for a sighting and for the issue this process filed for the fingerprint, `POST /repos/{repo}/issues` |
|
|
214
|
+
| `close` | as `move` to `done` |
|
|
215
|
+
| `whoami` | `GET /user` once, or `assignee` for an App |
|
|
216
|
+
| `person` | `GET /users/{login}`: the name, or the login with none, and the public email, or an empty text |
|
|
217
|
+
|
|
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.
|
|
219
|
+
|
|
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.
|
|
221
|
+
|
|
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.
|
|
223
|
+
|
|
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.
|
|
225
|
+
|
|
226
|
+
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
|
+
|
|
228
|
+
### Tools
|
|
229
|
+
|
|
230
|
+
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
|
+
|
|
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` |
|
|
245
|
+
|
|
246
|
+
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
|
+
|
|
248
|
+
### Token and App permissions
|
|
249
|
+
|
|
250
|
+
| Use | Fine-grained token or App permission | Classic token scope |
|
|
251
|
+
| ---------------- | ------------------------------------ | ---------------------------------------------- |
|
|
252
|
+
| The tracker port | `issues: write`, `metadata: read` | `repo` (`public_repo` for a public repository) |
|
|
253
|
+
|
|
254
|
+
## Configuration
|
|
255
|
+
|
|
256
|
+
```toml
|
|
257
|
+
[extensions.github]
|
|
258
|
+
default_base = "main" # the base branch of new pull requests; the default is "main"
|
|
259
|
+
app = { id = 123456, installation = 7890123 } # optional: sign in as this GitHub App installation
|
|
260
|
+
|
|
261
|
+
[extensions.github.watch] # optional: without it the service only waits
|
|
262
|
+
services = { api = "shop/api", web = "git@github.com:shop/web.git" } # each service to watch, with its repository
|
|
263
|
+
login = "edgar-bot" # optional: the login EDGAR works as; the default is GITHUB_TOKEN's, and an App needs it, such as edgar[bot]
|
|
264
|
+
every_seconds = 60 # the default, 30 to 3600
|
|
265
|
+
card_column = "intake" # the default: the column of a new card
|
|
266
|
+
|
|
267
|
+
[extensions.github.dependabot] # optional: without it the service reads no alert
|
|
268
|
+
services = { "shop/api" = "api", "shop/web" = "web" } # each repository as owner/name, with the service that its cards name
|
|
269
|
+
every_seconds = 300 # the default, 60 to 86400
|
|
270
|
+
severity_min = "low" # the default: low, medium, high or critical
|
|
271
|
+
max_per_run = 10 # the default, 1 to 100: the most cards that one sweep opens
|
|
272
|
+
card_column = "intake" # the default: the column of a new card
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
### The watch service
|
|
276
|
+
|
|
277
|
+
Every `every_seconds`, for each service of `watch.services` on github.com, the service reads the open pull requests (one page of 100), the check runs of the newest commit of `default_base`, and the check runs of the head of each pull request `login` opened. A rate limit ends the sweep at once, because the limit is the token's and not the repository's, and the next sweep starts after `every_seconds` or after the wait that GitHub names, whichever is longer. It opens a card with `ctx.cards.open` for:
|
|
278
|
+
|
|
279
|
+
| What it saw | The card | `decided` | Fingerprint of |
|
|
280
|
+
| ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------- |
|
|
281
|
+
| A pull request someone else opened that asks `login` for a review or assigns it, on a branch that is not `edgar/<card>-…` | `request`, "Review shop/api#43: <title>", with the URL, the head repository, branch and commit | `lane = "review"`, `pull_request`, `head_repo`, `head_branch` | the repository and the number |
|
|
282
|
+
| 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
|
+
| 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
|
+
|
|
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.
|
|
286
|
+
|
|
287
|
+
### The Dependabot feed
|
|
288
|
+
|
|
289
|
+
The feed is off until the project sets `[extensions.github.dependabot]`. Then, every `every_seconds`, the service reads the open Dependabot alerts of each repository of `services`. It reads one page of the 100 newest alerts, with `GET /repos/{owner}/{repo}/dependabot/alerts?state=open`. It opens one card with `ctx.cards.open` for each advisory of a package in a repository.
|
|
290
|
+
|
|
291
|
+
`services` maps a repository to a service. `watch.services` maps a service to a repository. A key of `dependabot.services` is `owner/name` only, and the schema refuses a table that has the service first.
|
|
292
|
+
|
|
293
|
+
#### The card
|
|
294
|
+
|
|
295
|
+
GitHub raises one alert for each manifest that holds the package. One card holds all the open alerts of one advisory of one package:
|
|
296
|
+
|
|
297
|
+
| Part | Content |
|
|
298
|
+
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
299
|
+
| Title | `<service>: <package>: <advisory summary>`, at most 120 characters. |
|
|
300
|
+
| Text | The advisory id (GHSA, and CVE when there is one) with its link, the package and its ecosystem, the severity, and the repository. Then one line for each alert: the manifest path, the scope, the vulnerable range, the fixed version, and the link of the alert. A card lists at most 20 alerts. |
|
|
301
|
+
| Block | `kind = "defect"`, `service`, `severity` (the worst of its alerts), `occurrences` (the number of its alerts), `fingerprint`, and `decided.batch`, the repository as `owner/name` in lower case, so `remediate` works one card of a repository at a time. |
|
|
302
|
+
|
|
303
|
+
The card has no label and no `decided` entry. The feed does not judge whether the code reaches the fault. A stage reads that. The text of a card is, for example:
|
|
304
|
+
|
|
305
|
+
```text
|
|
306
|
+
Dependabot reports a medium advisory in undici of shop/api: Unbounded decompression chain
|
|
307
|
+
|
|
308
|
+
Advisory: GHSA-g9mf-h72j-4rw9 (CVE-2026-22036), https://github.com/advisories/GHSA-g9mf-h72j-4rw9
|
|
309
|
+
Package: undici (npm)
|
|
310
|
+
Severity: medium
|
|
311
|
+
Repository: shop/api
|
|
312
|
+
|
|
313
|
+
Where GitHub raised it:
|
|
314
|
+
- `package-lock.json` (runtime): vulnerable in `< 6.23.0`, fixed in `6.23.0`, https://github.com/shop/api/security/dependabot/3
|
|
315
|
+
|
|
316
|
+
`github__dependabot_alerts` with `repo` shop/api and the `number` of an alert reads that alert as it is now.
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
#### One card for one advisory
|
|
320
|
+
|
|
321
|
+
The fingerprint comes from the repository, the advisory id and the package name. The repository is read as `owner/name` in lower case, as every key of this extension is, so `Acme/API` and `acme/api.git` give one fingerprint. The alert number is not in it, so an alert in a second manifest is the same card. A fingerprint that this process opened is not asked for again. After a sweep that read every repository, a fingerprint whose alert is no longer open leaves the memory, so the memory holds only open alerts. The tracker answers a repeat of a fingerprint with the open card that holds it. Thus a second sweep opens no second card, and a sweep after a restart opens none.
|
|
322
|
+
|
|
323
|
+
#### Order and limits
|
|
324
|
+
|
|
325
|
+
An alert under `severity_min` opens no card. The service asks GitHub for the wanted severities only, and it checks the severity of each alert again. A severity that the extension does not know is filed last. The worst advisories are filed first. One sweep opens at most `max_per_run` cards, and the other cards wait for the next sweep.
|
|
326
|
+
|
|
327
|
+
#### Failures
|
|
328
|
+
|
|
329
|
+
| What happened | What the service does |
|
|
330
|
+
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
331
|
+
| A rate limit | It stops the reading, because the limit is the token's and not the repository's. It files what it read. The next sweep starts after `every_seconds` or after the wait that GitHub names, whichever is longer. |
|
|
332
|
+
| GitHub does not find a repository (404), or Dependabot alerts are off or closed to the token (403) | It writes one log line and reads the next repository. The line comes again only when the failure changes. |
|
|
333
|
+
| Another failure of one repository, such as a 503 | The same. The next sweep reads the repository again. |
|
|
334
|
+
| A refused token (401) | The service ends with `permanent_failure(unauthenticated)`, so its breaker opens. The watch stops with it. |
|
|
335
|
+
| The tracker refuses a card | It writes a log line with the reason, and asks for the card again at the next sweep. |
|
|
336
|
+
| The tracker cannot answer: a temporary failure, or an engine error | It asks for no other card in this sweep. The next sweep asks again. |
|
|
337
|
+
|
|
338
|
+
Each sweep writes one log line with its counts:
|
|
339
|
+
|
|
340
|
+
```text
|
|
341
|
+
github dependabot: {"read":2,"filed":1,"tracked":4,"held":0,"below":3,"wait":0}
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
`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
|
+
|
|
346
|
+
The feed does not close a card when GitHub marks its alert as fixed.
|
|
347
|
+
|
|
348
|
+
### Sign in as a GitHub App
|
|
349
|
+
|
|
350
|
+
With `app` set, `GITHUB_TOKEN` holds the App's private key (the PEM file GitHub gives), not a token. Each call then uses an installation token: the extension signs a JWT with the key (RS256, issued one minute back, valid nine minutes), sends it to `POST /app/installations/{installation}/access_tokens`, and keeps the token it gets in the runtime's memory until five minutes before its `expires_at`. The next call mints a new one. Name the source after the key:
|
|
351
|
+
|
|
352
|
+
```toml
|
|
353
|
+
[secrets]
|
|
354
|
+
GITHUB_TOKEN = { env = "GITHUB_APP_PRIVATE_KEY" }
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
The key is a secret of the call: the engine's redaction holds it, it is sent nowhere, and only the JWT signed with it goes to `api.github.com`. A key that is not a PEM private key is `permanent_failure(unauthenticated)` before any request. A refused mint is the call's failure, and nothing is kept. `push_branch` pushes with the sandbox's own git credentials, not with the App.
|
|
358
|
+
|
|
359
|
+
## Secrets
|
|
360
|
+
|
|
361
|
+
- `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`.
|
|
362
|
+
|
|
363
|
+
### What the token must be able to do
|
|
364
|
+
|
|
365
|
+
| Tools | Fine-grained token or App permission | Classic token scope |
|
|
366
|
+
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------- |
|
|
367
|
+
| `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) |
|
|
368
|
+
| `attach_screenshot` | `contents: write`, `pull_requests: write` | `repo` (`public_repo` for a public repository) |
|
|
369
|
+
| `labels` of `open_pull_request` | `issues: write` or `pull_requests: write` | `repo` |
|
|
370
|
+
| `note_pull_request` | `issues: write` or `pull_requests: write` | `repo` |
|
|
371
|
+
| `pull_request_*`, `find_pull_request`, `linked_pull_requests`, `list_pull_requests` | `pull_requests: read` | `repo` |
|
|
372
|
+
| `pull_request_checks` | `checks: read`, `statuses: read` | `repo` |
|
|
373
|
+
| `ci_run` | `actions: read` | `repo` |
|
|
374
|
+
| `dependabot_alerts`, `find_dependabot_dismissal`, the Dependabot feed | `dependabot_alerts: read` | `security_events` or `repo` |
|
|
375
|
+
| `dismiss_dependabot_alert`, `reopen_dependabot_alert` | `dependabot_alerts: write` | `security_events` or `repo` |
|
|
376
|
+
| `branch_protection` | `metadata: read`; `administration: read` for the classic rule | `repo` |
|
|
377
|
+
|
|
378
|
+
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:
|
|
379
|
+
|
|
380
|
+
```json
|
|
381
|
+
{
|
|
382
|
+
"outcome": "permanent_failure",
|
|
383
|
+
"kind": "forbidden",
|
|
384
|
+
"message": "github POST /repos/shop/api/pulls: forbidden: the GITHUB_TOKEN needs pull_requests=write",
|
|
385
|
+
"cause": "403 Resource not accessible by personal access token"
|
|
386
|
+
}
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
- `GITHUB_WEBHOOK_SECRET`: the engine checks the `hmac-sha256` signature of `/hooks/github/events` with it. The delivery id is `X-GitHub-Delivery`.
|
|
390
|
+
|
|
391
|
+
## Errors
|
|
392
|
+
|
|
393
|
+
One table in `src/api/failures.ts` maps each answer to an outcome, with the HTTP status and GitHub's `message` in `cause`: 401 `unauthenticated`; 403 `rate_limited` when `X-RateLimit-Remaining` is `0`, `Retry-After` is present, or the body points at the secondary limits, else `forbidden`; 404 and 410 `not_found`; 422 `invalid`; 429 `rate_limited`; 5xx and network errors `provider_unavailable`; anything else `tool_error`. A rate limit waits for `Retry-After`, then `X-RateLimit-Reset`, then one minute.
|
|
394
|
+
|
|
395
|
+
`push_branch` maps a sandbox port error by its code: `capability_refused` and `sandbox_refused` are a permanent `refused`, `runtime_payload_too_large` keeps its name, `unknown_id` is `not_found`, `call_ended` is `cancelled`, and `engine_error` is a temporary `runtime_crashed`, so the engine runs the step again. A `git` command that exits with a code other than 0 is a permanent `tool_error` with the exit code and stderr in `cause`.
|
|
396
|
+
|
|
397
|
+
## Programs
|
|
398
|
+
|
|
399
|
+
The manifest declares `git` in `executables.requires`: `push_branch` runs `git` in the sandbox of the run. With `[sandbox] kind = "worktree"` or `"none"`, `edgar check` reports `X008` when `git` is not on `PATH`. With `kind = "container"`, `git` must be in `[sandbox] image`.
|
|
400
|
+
|
|
401
|
+
## Limits
|
|
402
|
+
|
|
403
|
+
Each answer's `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (Unix seconds) and `X-RateLimit-Resource` (the window, such as `core` or `graphql`) are read with the SDK's `github` scheme and reported for the source `api.github.com`, on a success and on a failure. A `Retry-After` makes the limit used up until the time it names. The operator sees the source on the console's Limits page and on `GET /api/limits`: the calls left of the window, when it resets, and the rate limited calls of today. While `api.github.com` has none left, EDGAR does not start a stage whose tool has `network:api.github.com`, and records `waited_for_limit` until the reset.
|
|
404
|
+
|
|
405
|
+
## Retries
|
|
406
|
+
|
|
407
|
+
The engine retries a stage after a temporary failure, with a new operation id. A network error can come after GitHub did the write, so each write tool must be safe when it runs a second time:
|
|
408
|
+
|
|
409
|
+
- `push_branch` is safe to retry. A second push of the same commit changes nothing.
|
|
410
|
+
- `close_pull_request` is safe to retry. It reads the pull request first and writes nothing to one that is closed. The line of its `text` is not added a second time.
|
|
411
|
+
- `note_pull_request` is safe to retry. A call whose line is already the last line of the note writes nothing.
|
|
412
|
+
- `update_pull_request` is safe to retry. A second call writes the same title and body.
|
|
413
|
+
- `open_pull_request` reads back on a 422. GitHub refuses a second pull request for a branch with 422. The tool then reads `GET /repos/{owner}/{repo}/pulls?state=open&head=<owner>:<branch>`. When an open pull request is there, the tool returns `done` with its `url` and `number`, so the stage owns it and `close_pull_request` can undo it. When there is none, the 422 stays `invalid`. When the read fails, the tool returns the failure of the read.
|
|
414
|
+
- `merge_pull_request` reads back on a `tool_error`. GitHub answers a second merge with 405. The tool then reads the pull request. When it is merged and its head is `commit`, the tool returns `done` with `merged: true` and the merge commit. When it is not merged and its head is `commit`, the `tool_error` stays. When its head is another commit, the tool answers `invalid`: nothing was merged and the new commit needs its own approval, or the pull request was merged at a commit that nobody approved through EDGAR and a person reads what was merged.
|
|
415
|
+
- `dismiss_dependabot_alert` reads the alert before it writes. A second run finds the alert dismissed with its own `reason` and `comment`. It writes nothing and returns `done` with `reopen: true`.
|
|
416
|
+
- `reopen_dependabot_alert` is safe to retry. It writes only while the alert is dismissed.
|
|
417
|
+
|
|
418
|
+
Example: the first `open_pull_request` sends the POST and the connection drops, so the stage gets `provider_unavailable`. The retry sends the POST again and GitHub answers 422 "A pull request already exists". The read-back finds pull request 42, and the stage ends with:
|
|
419
|
+
|
|
420
|
+
```json
|
|
421
|
+
{ "outcome": "done", "output": { "url": "https://github.com/shop/api/pull/42", "number": 42 } }
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
## Build and test
|
|
425
|
+
|
|
426
|
+
```sh
|
|
427
|
+
pnpm build # writes edgar-extension.json and schemas/
|
|
428
|
+
pnpm test # unit tests with a mock GitHub, no network
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
`edgar-extension.json` and `schemas/` are committed: a change to them in a diff is a change to what a person approves.
|
|
432
|
+
|
|
433
|
+
## Validation
|
|
434
|
+
|
|
435
|
+
Run on 2026-11-11 in `packages/extensions/ext-github`. The answer shapes of check runs, commit statuses, workflow runs, jobs, the job log redirect, branches and branch rules were read from real answers of public repositories with a `gh` session on 2026-11-10; the Dependabot, review comment, compare and installation token shapes come from GitHub's REST reference. The Dependabot feed and the dismissal were not run against GitHub: the `severity` filter of the alert list, and the `PATCH` of an alert with `state`, `dismissed_reason` and `dismissed_comment`, are written from that reference.
|
|
436
|
+
|
|
437
|
+
| Command | Exit code |
|
|
438
|
+
| ----------------------- | ----------------- |
|
|
439
|
+
| `pnpm run check-types` | 0 |
|
|
440
|
+
| `pnpm run lint` | 0 |
|
|
441
|
+
| `pnpm run format:check` | 0 |
|
|
442
|
+
| `pnpm run test` | 0, 81 tests pass |
|
|
443
|
+
| `pnpm run build`, twice | 0, the same bytes |
|
|
444
|
+
|
|
445
|
+
## Shortcuts
|
|
446
|
+
|
|
447
|
+
- 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.
|
|
448
|
+
- 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.
|
|
449
|
+
- 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.
|
|
450
|
+
|
|
451
|
+
- 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.
|
|
452
|
+
- shortcut: `ci_run` declares `network:*.blob.core.windows.net` and `network:*.actions.githubusercontent.com`, where GitHub redirects a job log. `GITHUB_TOKEN` lists both, because the engine gives a call that holds a secret only the hosts of that secret, and `fetch` drops `authorization` on that redirect, so the token goes to `api.github.com` only. Upgrade to exact hosts if GitHub documents them.
|
|
453
|
+
- shortcut: the App private key travels as the `GITHUB_TOKEN` secret, because a manifest secret cannot be optional and a second one would be an `X004` for every project that uses a token. Upgrade to its own `GITHUB_APP_PRIVATE_KEY` secret when the engine has optional secrets.
|
|
454
|
+
- shortcut: the Dependabot feed gets its repositories from `[extensions.github.dependabot] services`, for the same reason as the watch.
|
|
455
|
+
- 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.
|
|
456
|
+
- 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.
|
|
457
|
+
- 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.
|
|
458
|
+
- 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.
|
|
459
|
+
- shortcut: the compare that the body notices read lists at most 300 files.
|
|
460
|
+
- 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.
|
|
461
|
+
- 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.
|
|
462
|
+
- shortcut: `push_branch` pushes the sandbox's `origin` and does not compare it with `repo`. Upgrade when one sandbox holds several repositories.
|
|
463
|
+
- shortcut: the tracker port reads no webhook: the engine sweeps it like any tracker. Upgrade when the engine takes tracker events from a webhook.
|
|
464
|
+
- 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.
|
|
465
|
+
- 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.
|
|
466
|
+
- 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.
|
|
467
|
+
- shortcut: `hand_back` reads the first 100 events of an issue. Upgrade to `Link` pagination when issues get more events before EDGAR hands them back.
|
|
468
|
+
- shortcut: the issue each fingerprint was filed into is remembered by one process only, and forgotten on restart, after which the search has caught up. A holder filed in the last minute by another EDGAR process can still get a second issue. Upgrade when filings of one fingerprint span processes.
|
|
469
|
+
- shortcut: the secondary limit is read from `documentation_url`, because GitHub sends no code for it.
|
|
470
|
+
- shortcut: `open_pull_request` takes any open pull request of the branch as its own after a 422, because GitHub's reason sits in `errors[]` and a message is never matched. Upgrade to matching the `edgar-operation` line of the run when people open pull requests from `edgar/` branches.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Dismiss
|
|
2
|
+
|
|
3
|
+
A person read a card of Dependabot alerts and decided that they are not to be fixed. You write
|
|
4
|
+
that decision on each alert at GitHub. You change no code.
|
|
5
|
+
|
|
6
|
+
- Read the person's comment in the input, then the card. The card names the repository, the
|
|
7
|
+
advisory (`GHSA-…`) and the package. It lists at most 20 alerts, so do not take the list from it.
|
|
8
|
+
- List the open alerts with `github__dependabot_alerts`: `repo` from the card, `ghsa` with the
|
|
9
|
+
card's advisory, `package` with the card's package, `state = ["open"]` and `limit = 100`. These
|
|
10
|
+
are the alerts to dismiss. When the answer has `complete = false`, dismiss these, then list again
|
|
11
|
+
until the answer is complete.
|
|
12
|
+
- Take the reason from the person's words:
|
|
13
|
+
- `not_used`: the vulnerable code is not used, or the package is not in what ships.
|
|
14
|
+
- `tolerable_risk`: the risk is accepted.
|
|
15
|
+
- `inaccurate`: the advisory is wrong for this code.
|
|
16
|
+
- `no_bandwidth`: there is no time to fix it now.
|
|
17
|
+
- `fix_started`: a fix is already in progress somewhere else.
|
|
18
|
+
- When the comment fits none of these, or names alerts of another advisory or package, dismiss
|
|
19
|
+
nothing. Ask the person which reason applies.
|
|
20
|
+
- Call `github__dismiss_dependabot_alert` once for each alert, with a `comment` of at most 280
|
|
21
|
+
characters that gives the person's reason in their own words and names the card.
|
|
22
|
+
- In `text`, say which alerts you dismissed, with their links, and the reason. Say which alerts
|
|
23
|
+
you left alone, and why.
|
|
24
|
+
|
|
25
|
+
Return the result with `edgar__result`.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { type Failure, type Result } from "@kana-ai/edgar-sdk";
|
|
2
|
+
/** How long before its expiry a cached installation token is minted again. */
|
|
3
|
+
export declare const RENEW_BEFORE_MS: number;
|
|
4
|
+
/** The `[extensions.github] app` table: the App's id (or client id) and its installation's id. */
|
|
5
|
+
export interface App {
|
|
6
|
+
readonly id: number | string;
|
|
7
|
+
readonly installation: number;
|
|
8
|
+
}
|
|
9
|
+
/** The JWT that signs the App in, RS256 with its private key, issued a minute back for clock drift and valid for nine minutes; a key that is not a PEM private key is `unauthenticated`. */
|
|
10
|
+
export declare function appJwt(app: App, pem: string, now?: number): Result<string, Failure>;
|
|
11
|
+
/** The installation token minted for `app` that is still good at `now`, past which it is minted again. */
|
|
12
|
+
export declare function heldToken(app: App, now?: number): string | undefined;
|
|
13
|
+
/** Keeps a minted installation token in this process's memory until five minutes before `expires_at`. */
|
|
14
|
+
export declare function holdToken(app: App, token: string, expiresAt: string): void;
|
|
15
|
+
/** Forgets every held token, for a test that starts clean. */
|
|
16
|
+
export declare function forgetTokens(): void;
|