Skip to content

GitHub Issues#

OakCore does not host tickets natively, but lets you link specification nodes (requirements, tests, risks) to GitHub issues. After setup, OakCore keeps a read-only snapshot of each linked issue and adds a backlink comment on GitHub pointing to the node in OakCore.

Connection setup (PAT, owner/repo, webhooks) is shared with other GitHub binding families — see GitHub repository connection.

Bind an issue to a node#

  1. Open a node whose type supports issue binding (requirement, test, or risk).
  2. In the sidebar, open the Info tab and scroll to Bindings → Issues.
  3. Choose the connection (by label), paste an issue reference, and link.

Requires a GitHub repository connection for the target repo.

Accepted references:

Format Example
Full issue URL https://github.com/acme/widgets/issues/42
Issue number 42
Hash shorthand #42

The URL must match the connection's owner and repository. Pull request URLs are rejected here — use GitHub pull requests instead.

After linking, OakCore:

  1. Pulls the current issue data (title, status, labels, …).
  2. Posts or updates a comment on the GitHub issue — the backlink comment. OakCore uses one managed comment per linked issue, identified by a hidden marker. The comment is written regardless of issue state (open or closed).

Example landing URL in the comment:

{your-oakcore-url}/integration-issue?projectId={project_id}&artifactId={artifact_id}

Additional anchors: When you link another OakCore node to the same GitHub issue, 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 node from an issue, OakCore removes this comment. If other nodes remain linked, the comment is updated to list only the remaining anchors.

Warning — locked issues: GitHub does not allow new comments on locked issues. OakCore still creates the binding and keeps the snapshot, but the backlink comment cannot be written until the issue is unlocked (or you remove the lock on GitHub). Use Refresh after unlocking to retry the backlink.

Webhook events#

On the shared GitHub webhook, subscribe to Issues only (do not add Issue comments). OakCore re-fetches the issue snapshot on opened, edited, closed, reopened, and similar events.

Troubleshooting#

Symptom What to check
Bind rejected as pull request Use the Pull requests binding section or a /pull/ URL in the PR family
Snapshot stays pending Run Test on the connection; wait for background sync
No backlink comment Token needs Issues → Read and write; issue may be locked

See also GitHub repository connection → Troubleshooting.