|
1
|
+ |
# GitHub Issues and Projects API — implementation assessment
|
|
2
|
+ |
|
|
3
|
+ |
Date: 2026-08-19
|
|
4
|
+ |
Source: `rest-api-description/descriptions/api.github.com/api.github.com.2026-03-10.yaml`
|
|
5
|
+ |
|
|
6
|
+ |
## Goal
|
|
7
|
+ |
|
|
8
|
+ |
Dogfood OpenAgents by using it to track this repo's own issues and projects. We want enough GitHub REST API parity that `gh`, Octokit, and the GitHub CLI can talk to OpenAgents without changes, but we will only build the subset we actually use.
|
|
9
|
+ |
|
|
10
|
+ |
## Summary
|
|
11
|
+ |
|
|
12
|
+ |
The 2026-03-10 OpenAPI spec has 84 endpoints tagged with `issue` or `project`. Most are for advanced features. For day-one use we need the core create/read/update/comment/label/assign/milestone flow, plus the ability to add issues to a project board and update board fields.
|
|
13
|
+ |
|
|
14
|
+ |
## Issues API — what to build
|
|
15
|
+ |
|
|
16
|
+ |
### Phase 1 — must have for dogfooding
|
|
17
|
+ |
|
|
18
|
+ |
These endpoints are enough to open, discuss, label, assign, and close issues in public:
|
|
19
|
+ |
|
|
20
|
+ |
| Method | Path | Why it matters |
|
|
21
|
+ |
| --- | --- | --- |
|
|
22
|
+ |
| GET | `/repos/{owner}/{repo}/issues` | List repository issues |
|
|
23
|
+ |
| GET | `/repos/{owner}/{repo}/issues/{issue_number}` | Get a single issue |
|
|
24
|
+ |
| POST | `/repos/{owner}/{repo}/issues` | Create an issue |
|
|
25
|
+ |
| PATCH | `/repos/{owner}/{repo}/issues/{issue_number}` | Edit, close, or reopen an issue |
|
|
26
|
+ |
| GET | `/repos/{owner}/{repo}/issues/{issue_number}/comments` | List comments on an issue |
|
|
27
|
+ |
| POST | `/repos/{owner}/{repo}/issues/{issue_number}/comments` | Add a comment |
|
|
28
|
+ |
| GET | `/repos/{owner}/{repo}/issues/comments/{comment_id}` | Get a single comment |
|
|
29
|
+ |
| PATCH | `/repos/{owner}/{repo}/issues/comments/{comment_id}` | Edit a comment |
|
|
30
|
+ |
| DELETE | `/repos/{owner}/{repo}/issues/comments/{comment_id}` | Delete a comment |
|
|
31
|
+ |
| GET | `/repos/{owner}/{repo}/labels` | List repository labels |
|
|
32
|
+ |
| GET | `/repos/{owner}/{repo}/labels/{name}` | Get a label |
|
|
33
|
+ |
| POST | `/repos/{owner}/{repo}/labels` | Create a label |
|
|
34
|
+ |
| PATCH | `/repos/{owner}/{repo}/labels/{name}` | Update a label |
|
|
35
|
+ |
| DELETE | `/repos/{owner}/{repo}/labels/{name}` | Delete a label |
|
|
36
|
+ |
| GET | `/repos/{owner}/{repo}/issues/{issue_number}/labels` | List labels on an issue |
|
|
37
|
+ |
| POST | `/repos/{owner}/{repo}/issues/{issue_number}/labels` | Add labels to an issue |
|
|
38
|
+ |
| DELETE | `/repos/{owner}/{repo}/issues/{issue_number}/labels/{name}` | Remove a label from an issue |
|
|
39
|
+ |
| GET | `/repos/{owner}/{repo}/assignees` | List who can be assigned |
|
|
40
|
+ |
| GET | `/repos/{owner}/{repo}/assignees/{assignee}` | Check if a user can be assigned |
|
|
41
|
+ |
| POST | `/repos/{owner}/{repo}/issues/{issue_number}/assignees` | Add assignees |
|
|
42
|
+ |
| DELETE | `/repos/{owner}/{repo}/issues/{issue_number}/assignees` | Remove assignees |
|
|
43
|
+ |
| GET | `/repos/{owner}/{repo}/milestones` | List milestones |
|
|
44
|
+ |
| GET | `/repos/{owner}/{repo}/milestones/{milestone_number}` | Get a milestone |
|
|
45
|
+ |
| POST | `/repos/{owner}/{repo}/milestones` | Create a milestone |
|
|
46
|
+ |
| PATCH | `/repos/{owner}/{repo}/milestones/{milestone_number}` | Update a milestone |
|
|
47
|
+ |
| DELETE | `/repos/{owner}/{repo}/milestones/{milestone_number}` | Delete a milestone |
|
|
48
|
+ |
|
|
49
|
+ |
### Phase 2 — nice to have
|
|
50
|
+ |
|
|
51
|
+ |
| Method | Path | Why it matters |
|
|
52
|
+ |
| --- | --- | --- |
|
|
53
|
+ |
| GET | `/repos/{owner}/{repo}/issues/events` | Activity feed |
|
|
54
|
+ |
| GET | `/repos/{owner}/{repo}/issues/events/{event_id}` | Single event |
|
|
55
|
+ |
| GET | `/repos/{owner}/{repo}/issues/{issue_number}/events` | Issue-specific events |
|
|
56
|
+ |
| GET | `/repos/{owner}/{repo}/issues/{issue_number}/timeline` | Full timeline |
|
|
57
|
+ |
| PUT | `/repos/{owner}/{repo}/issues/{issue_number}/lock` | Lock an issue |
|
|
58
|
+ |
| DELETE | `/repos/{owner}/{repo}/issues/{issue_number}/lock` | Unlock an issue |
|
|
59
|
+ |
|
|
60
|
+ |
### Out for now
|
|
61
|
+ |
|
|
62
|
+ |
- `/issues` and `/user/issues` — cross-repo lists. We can start repo-scoped.
|
|
63
|
+ |
- `/orgs/{org}/issues` — org-level issue list. Not needed for one repo.
|
|
64
|
+ |
- Issue dependencies and sub-issues — useful later, not required for a public tracker.
|
|
65
|
+ |
- Issue suggestions and issue-field-values — tied to newer GitHub custom fields and AI features. Skip until we need them.
|
|
66
|
+ |
|
|
67
|
+ |
## Projects API — what to build
|
|
68
|
+ |
|
|
69
|
+ |
### Important caveat
|
|
70
|
+ |
|
|
71
|
+ |
The 2026-03-10 GitHub REST spec has only a limited Projects V2 surface. It lists projects and items, but it does **not** include a REST endpoint to create or update a project. Board creation and field/schema changes are GraphQL in the official API.
|
|
72
|
+ |
|
|
73
|
+ |
### Phase 1 — implement the existing REST subset
|
|
74
|
+ |
|
|
75
|
+ |
| Method | Path | Why it matters |
|
|
76
|
+ |
| --- | --- | --- |
|
|
77
|
+ |
| GET | `/users/{username}/projectsV2` | List user projects |
|
|
78
|
+ |
| GET | `/users/{username}/projectsV2/{project_number}` | Get a user project |
|
|
79
|
+ |
| GET | `/users/{username}/projectsV2/{project_number}/items` | List project items |
|
|
80
|
+ |
| GET | `/users/{username}/projectsV2/{project_number}/items/{item_id}` | Get a project item |
|
|
81
|
+ |
| POST | `/users/{username}/projectsV2/{project_number}/items` | Add an issue to a project |
|
|
82
|
+ |
| PATCH | `/users/{username}/projectsV2/{project_number}/items/{item_id}` | Update a project item (status, field values) |
|
|
83
|
+ |
| DELETE | `/users/{username}/projectsV2/{project_number}/items/{item_id}` | Remove an item from a project |
|
|
84
|
+ |
| GET | `/users/{username}/projectsV2/{project_number}/fields` | List project fields |
|
|
85
|
+ |
| GET | `/users/{username}/projectsV2/{project_number}/fields/{field_id}` | Get a project field |
|
|
86
|
+ |
| GET | `/users/{username}/projectsV2/{project_number}/views` | Create a view for a user-owned project |
|
|
87
|
+ |
|
|
88
|
+ |
Also implement the same set under `/orgs/{org}/projectsV2` when we are ready for org-scoped projects.
|
|
89
|
+ |
|
|
90
|
+ |
### Phase 1 — add the missing write endpoints
|
|
91
|
+ |
|
|
92
|
+ |
Because the official REST spec is incomplete, add the following non-GitHub-standard OpenAgents-specific project endpoints to unblock day-one board creation and editing:
|
|
93
|
+ |
|
|
94
|
+ |
| Method | Path | Why it matters |
|
|
95
|
+ |
| --- | --- | --- |
|
|
96
|
+ |
| POST | `/{owner}/projectsV2` | Create a new project |
|
|
97
|
+ |
| PATCH | `/{owner}/projectsV2/{project_number}` | Update project title and settings |
|
|
98
|
+ |
| DELETE | `/{owner}/projectsV2/{project_number}` | Delete a project |
|
|
99
|
+ |
| POST | `/{owner}/projectsV2/{project_number}/fields` | Add a custom field |
|
|
100
|
+ |
| POST | `/{owner}/projectsV2/{project_number}/views` | Create a board view |
|
|
101
|
+ |
|
|
102
|
+ |
These are not in the GitHub REST spec, but they are required for a usable project tracker. We can make them GitHub-compatible where it makes sense and document the gap.
|
|
103
|
+ |
|
|
104
|
+ |
### Out for now
|
|
105
|
+ |
|
|
106
|
+ |
- Draft items, project views in detail, and advanced project view item ordering — add once the core board works.
|
|
107
|
+ |
- Organization-level projects — implement after user projects work.
|
|
108
|
+ |
|
|
109
|
+ |
## Recommendation
|
|
110
|
+ |
|
|
111
|
+ |
Build the Issues Phase 1 list first. It is enough for the public to open, discuss, and manage issues on OpenAgents.com. Then add the Projects V2 read endpoints and the non-standard project write endpoints so we can organize those issues into a public board.
|