GitHub source code#
Link OakCore nodes to files or directories in a GitHub repository. File bindings provide a read-only preview; directory bindings provide a bounded browser for their contents. OakCore stores reference metadata, but it does not copy complete source files into the project.
Connection setup reuses the same GitHub repository connection as issues and pull requests.
Link source code to a node#
- Open a requirement or test node.
- In the sidebar, open Info → Bindings → Source code.
- Choose the repository connection.
- Enter a file or directory reference and select Link source code.
Accepted references:
| Format | Example |
|---|---|
| Repository-relative path using the connection's default ref | src/auth/service.py |
| Path with explicit ref | src/auth@develop |
| GitHub file URL | https://github.com/acme/widgets/blob/main/src/auth/service.py |
| GitHub directory URL | https://github.com/acme/widgets/tree/main/src/auth |
The path must belong to the repository configured by the selected connection. Line anchors such as #L42 are ignored.
Files and directories#
For a file, select the binding to open a syntax-highlighted, read-only preview. Large previews are truncated; use Open in GitHub for the complete file.
For a directory, select the binding to browse its immediate children. You can navigate into descendant directories, page through bounded results, and open files directly in GitHub. Browsing cannot leave the linked directory scope.
OakCore records:
- resource type (
fileordirectory) - repository path and tracking ref
- the commit to which that ref resolved during the latest successful sync
- the Git blob or tree SHA
- bounded preview metadata for files
Sync and refresh#
The initial snapshot is fetched after linking. A branch-based binding follows that branch; refreshing resolves the branch again and updates the commit and blob/tree reference. A tag or commit ref normally remains fixed.
GitHub push events can mark bindings stale. Use Refresh on a stale, failed, or deleted binding to retry. If the path no longer exists, OakCore keeps the last known reference visible until you repair or unlink it.
Source-code bindings do not post comments or backlinks into the repository. Unlinking removes only the OakCore association.
Baselines#
New baselines include the external binding reference. For source code, this contains the path, resource type, tracking ref, and the last successfully resolved commit and blob/tree SHA available when the baseline is created. Baselines do not contain source content or preview text.
What this does not mean#
A source-code binding is a traceability reference. It does not prove that the linked code implements a requirement, and OakCore does not perform AST or semantic code analysis as part of the binding.
Troubleshooting#
| Symptom | What to check |
|---|---|
| Path cannot be linked | Path/ref exists and belongs to the selected repository |
| GitHub denies access | Token has Contents → Read permission |
| File preview is unavailable | Binding is a file and the token can read its contents |
| Directory cannot be browsed | Binding is a directory; requested child remains below the linked root |
| Binding is stale or deleted | Refresh it, then verify branch, path, and repository access |