GitHub pull requests#
Link specification nodes (requirements, tests, risks) to GitHub pull requests for implementation traceability. OakCore keeps a read-only snapshot (title, state, branches, labels, …) and posts a backlink comment on the pull request.
Connection setup reuses the same GitHub repository connection as issue bindings — no second connection or token per repo.
Bind a pull request to a node#
- Open a node whose type supports pull request binding (requirement, test, or risk).
- In the sidebar, Info tab → Bindings → Pull requests.
- Choose the connection, paste a pull request reference, and link.
Requires a GitHub repository connection for the target repo.
Accepted references:
| Format | Example |
|---|---|
| Full pull URL | https://github.com/acme/widgets/pull/7 |
| Pull number | 7 |
| Hash shorthand | #7 |
Use a pull request URL (/pull/) or bind via the Pull requests section. Issue URLs (/issues/) are rejected here.
After linking, OakCore:
- Pulls the current pull request snapshot.
- Posts or updates a comment on the pull request (via GitHub's issue-comment API) with an OakCore landing link. OakCore uses one managed comment per linked pull request. The comment is written regardless of PR state (open, closed, or merged).
Example landing URL:
{your-oakcore-url}/integration-pull-request?projectId={project_id}&artifactId={artifact_id}
Additional anchors: When you link another OakCore node to the same pull request, OakCore updates the same comment so it lists all linked nodes.
Refresh: Manual refresh also rewrites the backlink comment with the current anchor list.
When you unlink the last anchor, OakCore removes the backlink comment. If other nodes remain linked, the comment is updated to list only the remaining anchors.
Warning — locked conversations: GitHub does not allow new comments on locked pull requests. OakCore still creates the binding and keeps the snapshot, but the backlink comment cannot be written until the conversation is unlocked. Use Refresh after unlocking to retry the backlink.
Snapshot fields#
| Field | Meaning |
|---|---|
state_category |
open, closed, or merged |
draft |
Draft pull request |
base_branch / head_branch |
Merge target and source branch |
labels |
GitHub labels on the PR |
Webhook events#
On the shared GitHub webhook, add Pull requests to the selected events (in addition to Issues if you use both families). OakCore updates bound pull requests on opened, synchronize, closed, reopened, and similar events.
Troubleshooting#
| Symptom | What to check |
|---|---|
| Bind rejected | URL is an issue link, not a pull link; wrong repository for the connection |
| PR changes not reflected | Webhook includes Pull requests events |
| No backlink | Token needs Pull requests → Read and write; conversation may be locked (see warning above) |