GitHub Reader API reference
Seven read-only operations from @di-atomic/github-reader. The media patch v0.1.1 keeps the v0.1.0 API unchanged. Examples require installation in the caller's brand context and a GitHub integration. These examples document the contract; they are not hired-agent runtime receipts.
Authentication and access
A brand admin configures Settings > Integrations > GitHub. Use a fine-grained personal access token restricted to the selected repositories with Metadata and Contents read, plus Issues or Pull requests read when needed. Credentials stay in the integration. Never pass a token, brand id, arbitrary endpoint or host as a method argument. The declared package requires its brand credential even for public repositories.
Hosted private credential routing and independent brand isolation remain unverified. The hired-agent test is owed when a product carries this skill.
Inputs and pagination
The typed contract is skills/github-reader/schema.yaml; it owns all inputs and closed enum choices. Common repository inputs are owner and repo; lists expose page/per_page (maximum 100). Never pass brand_id, a token, arbitrary host, HTTP verb or endpoint. Only send resource-applicable filters. All examples below require installation and use the caller's brand context.
getRepository
Orient to default branch, visibility and license metadata.
opvs -w demavias-llc tools call @di-atomic/github-reader getRepository --args '{"owner":"octocat","repo":"Hello-World"}'Response: object: default_branch, private, license, html_url.
Errors:
Identifier | Trigger | Resolution |
|---|---|---|
401 | Credential missing, invalid or unavailable | Ask the brand admin to check its GitHub integration. Do not put a token in the request. |
403 | Permission denied or rate limit | Inspect the response and reset headers; request the minimum read permission or wait for reset. |
404 | Resource absent or private access hidden | Check owner, repository, path and ref; verify authorized access before concluding it is absent. |
422 | Invalid ref, query or input | Correct the input against the method contract. |
429 | Request rate exceeded | Respect Retry-After and bound retries. |
readRepositoryResource
Read README or list releases, tags, commits, issues and PRs.
opvs -w demavias-llc tools call @di-atomic/github-reader readRepositoryResource --args '{"owner":"octocat","repo":"Hello-World","resource":"readme","ref":"7fd1a60b01f91b314f59955a4e4d4e80d8edf11d"}'Response: readme: base64 file object; other resources: paginated arrays.
Errors:
Identifier | Trigger | Resolution |
|---|---|---|
401 | Credential missing, invalid or unavailable | Ask the brand admin to check its GitHub integration. Do not put a token in the request. |
403 | Permission denied or rate limit | Inspect the response and reset headers; request the minimum read permission or wait for reset. |
404 | Resource absent or private access hidden | Check owner, repository, path and ref; verify authorized access before concluding it is absent. |
422 | Invalid ref, query or input | Correct the input against the method contract. |
429 | Request rate exceeded | Respect Retry-After and bound retries. |
getTree
Inspect source paths at a fixed commit.
opvs -w demavias-llc tools call @di-atomic/github-reader getTree --args '{"owner":"octocat","repo":"Hello-World","tree_sha":"7fd1a60b01f91b314f59955a4e4d4e80d8edf11d","recursive":"1"}'Response: object: sha, tree entries, truncated.
Errors:
Identifier | Trigger | Resolution |
|---|---|---|
401 | Credential missing, invalid or unavailable | Ask the brand admin to check its GitHub integration. Do not put a token in the request. |
403 | Permission denied or rate limit | Inspect the response and reset headers; request the minimum read permission or wait for reset. |
404 | Resource absent or private access hidden | Check owner, repository, path and ref; verify authorized access before concluding it is absent. |
422 | Invalid ref, query or input | Correct the input against the method contract. |
429 | Request rate exceeded | Respect Retry-After and bound retries. |
getContent
Retrieve exact file bytes at the selected ref.
opvs -w demavias-llc tools call @di-atomic/github-reader getContent --args '{"owner":"octocat","repo":"Hello-World","path":"README","ref":"7fd1a60b01f91b314f59955a4e4d4e80d8edf11d"}'Response: file object with base64 content, blob sha and size; directory array for directories.
Errors:
Identifier | Trigger | Resolution |
|---|---|---|
401 | Credential missing, invalid or unavailable | Ask the brand admin to check its GitHub integration. Do not put a token in the request. |
403 | Permission denied or rate limit | Inspect the response and reset headers; request the minimum read permission or wait for reset. |
404 | Resource absent or private access hidden | Check owner, repository, path and ref; verify authorized access before concluding it is absent. |
422 | Invalid ref, query or input | Correct the input against the method contract. |
429 | Request rate exceeded | Respect Retry-After and bound retries. |
searchGitHub
Discover repos, locate code, or search issues/PRs.
opvs -w demavias-llc tools call @di-atomic/github-reader searchGitHub --args '{"resource":"repositories","q":"repo:octocat/Hello-World","per_page":1}'Response: object: total_count, incomplete_results, items.
Errors:
Identifier | Trigger | Resolution |
|---|---|---|
401 | Credential missing, invalid or unavailable | Ask the brand admin to check its GitHub integration. Do not put a token in the request. |
403 | Permission denied or rate limit | Inspect the response and reset headers; request the minimum read permission or wait for reset. |
404 | Resource absent or private access hidden | Check owner, repository, path and ref; verify authorized access before concluding it is absent. |
422 | Invalid ref, query or input | Correct the input against the method contract. |
429 | Request rate exceeded | Respect Retry-After and bound retries. |
readRepositoryRecord
Read an issue/PR, a commit or a base...head comparison.
opvs -w demavias-llc tools call @di-atomic/github-reader readRepositoryRecord --args '{"owner":"octocat","repo":"Hello-World","resource":"commits","key":"7fd1a60b01f91b314f59955a4e4d4e80d8edf11d"}'Response: issue/PR object, commit object with files, or comparison object.
Errors:
Identifier | Trigger | Resolution |
|---|---|---|
401 | Credential missing, invalid or unavailable | Ask the brand admin to check its GitHub integration. Do not put a token in the request. |
403 | Permission denied or rate limit | Inspect the response and reset headers; request the minimum read permission or wait for reset. |
404 | Resource absent or private access hidden | Check owner, repository, path and ref; verify authorized access before concluding it is absent. |
422 | Invalid ref, query or input | Correct the input against the method contract. |
429 | Request rate exceeded | Respect Retry-After and bound retries. |
readThreadContext
Inspect conversation comments, inline reviews, review records and changed files.
opvs -w demavias-llc tools call @di-atomic/github-reader readThreadContext --args '{"owner":"octocat","repo":"Hello-World","kind":"issues","number":11641,"resource":"comments","per_page":1}'Response: paginated array; issues/comments is conversation, pulls/comments is inline review discussion.
Errors:
Identifier | Trigger | Resolution |
|---|---|---|
401 | Credential missing, invalid or unavailable | Ask the brand admin to check its GitHub integration. Do not put a token in the request. |
403 | Permission denied or rate limit | Inspect the response and reset headers; request the minimum read permission or wait for reset. |
404 | Resource absent or private access hidden | Check owner, repository, path and ref; verify authorized access before concluding it is absent. |
422 | Invalid ref, query or input | Correct the input against the method contract. |
429 | Request rate exceeded | Respect Retry-After and bound retries. |
Resource choices
Operation | Closed choices | Notes |
|---|---|---|
readRepositoryResource | readme, releases, tags, commits, issues, pulls | Use only filters applicable to the resource. |
searchGitHub | repositories, code, issues | Code search is default-branch-only; it does not establish tag behavior. |
readRepositoryRecord | issues, pulls, commits, compare | Compare uses base...head as key. |
readThreadContext | issues/comments; pulls/comments, reviews, files | PR conversation comments use issues/comments; pulls/comments is inline review discussion. |
Evidence and response limits
Record repository, selected ref, resolved commit SHA, path, quoted lines and a source URL for each finding. Keep observed source separate from inference, reproduced behavior and deployment. Lists paginate with page and per_page (maximum 100). A partial page, incomplete search or truncated tree is a gap, not an empty success.
Contents base64 support is complete through 1 MB. Larger files, binary files, LFS and submodules need explicit handling or gaps. Directory content listings cap at 1,000; PR files at 3,000. Tree results, comparison files and patches can truncate. Descend subtrees or narrow the investigation.
Respect rate-limit and Retry-After headers. Anonymous code search returned 401 in retained public controls; navigating trees and files remains a separate fallback. There are no writes, pushes, merges or dispatches. Fetching a skill does not install or activate it.
Sources
The published package schema is the input contract. See GitHub REST documentation, repository contents, and search.