Operate GitHub via NyxID
Overview
This skill lets an AI agent act on a user's GitHub account using the GitHub REST API — read repos, open issues and pull requests, commit files, trigger Actions, etc. — on the user's behalf.
The one premise: the agent never holds a GitHub token. Every call goes through
NyxID's credential-brokering proxy for the connected service api-github. NyxID
stores the user's GitHub credential (connected via OAuth — "the GitHub account the user
bound in NyxID") encrypted at rest, strips any client Authorization header, injects the
GitHub credential server-side, and forwards the request to https://api.github.com. You
only ever send your NyxID bearer; you never see, request, or log the GitHub token.
What "operate GitHub" really means here: anything the GitHub REST API allows and that the OAuth scopes granted to the
api-githubconnection permit. The ceiling is the granted scopes, not the entire API surface (see Scopes & permissions).
1. Preflight — use the product connection flow
In an Aevatar interactive turn, the request-local exact GitHub operations are the connection
evidence. If those operations are present, call the admitted GET /user operation directly;
do not second-guess the active connection or claim that no GitHub tool is available.
If the exact operations are absent, use the route-owned typed readiness action for
service_slug=api-github and the real catalog capability requested_scopes=["read:user"].
That action emits the authorization/connect-required event rendered as the Web UI connection
card. Never tell an Aevatar Web UI user to run nyxid, gh, curl, raw HTTP, or any other CLI
fallback. If the typed readiness action is unavailable, return a typed failure; do not replace it
with prose connection instructions.
CLI and raw HTTP are operator-only alternatives outside the Aevatar Web UI. Operators may inspect
nyxid service list --output json or the NyxID service API, and may request broader scopes during
OAuth. These commands are not user-facing chat remedies.
Do not ask the user to paste a GitHub token into chat — the OAuth flow handles it.
(If broader, user-controlled scopes are needed, api-github-pat is an operator-selected fallback;
never solicit the PAT in chat.)
2. How to call the GitHub API
Always call through the NyxID proxy for slug api-github. The path you send is
appended to the service base URL https://api.github.com, so paths are relative and
standard GitHub REST v3 — e.g. /user, /repos/{owner}/{repo}/issues. Do not put a host
or a GitHub token in the request.
For Aevatar tool calls, keep these three invocation modes separate. They hit the same NyxID proxy, but do not accept the same fields.
a) Raw one-off nyxid_proxy. The raw caller owns the route and must send exact
service_id + slug + path; method, body, allowed non-sensitive headers, and response mode are
optional. To read the connected account:
{
"tool": "nyxid_proxy",
"arguments": {
"service_id": "us-gh-7",
"slug": "api-github",
"path": "/user",
"method": "GET"
}
}
b) Interactive request-local operation. Call the exact nyxid_service_operation__* tool
emitted by the current request. Its dynamic schema requires an enumerated user_service_id and
only the operation fields declared by the exact UserService OpenAPI. For an emitted get_user
operation with no other parameters:
{
"tool": "nyxid_service_operation__get_user",
"arguments": {"user_service_id": "us-gh-7"}
}
Do not derive the tool name from api-github, reuse it in another request, or add route fields not
present in the emitted schema.
c) Compiled workflow admitted operation. The step calls nyxid_proxy, copies the exact
selector into step-level capability.nyxid_operation, and supplies only admitted runtime values.
For an admission that owns get-user, GET, UserService us-gh-7, slug, and /user:
- id: read_user
type: tool_call
capability:
nyxid_operation:
user_service_id: us-gh-7
operation_id: get-user
parameters:
tool: nyxid_proxy
arguments: '{}'
The server-owned proof also owns the contract digest, schemas, and response policy. Runtime
arguments may contain only admitted path_params, query, headers, body, and
response_mode; never put service_id, user_service_id, operation_id, slug, path,
method, or proof fields there.
Outside the Aevatar tool surface, operators may still use the lower-level transports below. These examples are operator documentation and must never be sent to an Aevatar Web UI user as a fallback:
Raw HTTP (any runtime that holds a NyxID bearer):
{METHOD} https://nyx-api.chrono-ai.fun/api/v1/proxy/s/api-github/{path}
Authorization: Bearer <NYXID_TOKEN>
Content-Type: application/json # for write bodies
NyxID CLI:
nyxid proxy request api-github /user -m GET
nyxid proxy request api-github /repos/OWNER/REPO/issues -m POST \
-d '{"title":"Bug: ...","body":"..."}'
Recommended GitHub content headers (optional — NyxID handles auth, you set content):
Accept: application/vnd.github+json and X-GitHub-Api-Version: 2022-11-28.
3. Capability cookbook
Paths are relative to https://api.github.com. {owner}/{repo} and {number} are
placeholders.
Read
| Goal | Method & path |
|---|---|
| Identify the connected user | GET /user |
| List the user's repos | GET /user/repos?per_page=100&sort=updated |
| Get a repo | GET /repos/{owner}/{repo} |
| List branches | GET /repos/{owner}/{repo}/branches |
Read a file (base64 in .content) |
GET /repos/{owner}/{repo}/contents/{path}?ref={branch} |
| List commits | GET /repos/{owner}/{repo}/commits?sha={branch}&per_page=30 |
| List issues | GET /repos/{owner}/{repo}/issues?state=open |
| List pull requests | GET /repos/{owner}/{repo}/pulls?state=open |
| Search repos / issues / code | GET /search/repositories?q=... · GET /search/issues?q=... · GET /search/code?q=... |
| Check rate limit (free) | GET /rate_limit |
Write (needs the matching scope)
| Goal | Method & path | Minimal body |
|---|---|---|
| Open an issue | POST /repos/{owner}/{repo}/issues |
{"title":"...","body":"...","labels":[],"assignees":[]} |
| Comment on issue/PR | POST /repos/{owner}/{repo}/issues/{number}/comments |
{"body":"..."} |
| Create or update a file | PUT /repos/{owner}/{repo}/contents/{path} |
{"message":"...","content":"<base64>","branch":"main","sha":"<existing-sha-if-updating>"} |
| Create a branch (git ref) | POST /repos/{owner}/{repo}/git/refs |
{"ref":"refs/heads/<name>","sha":"<base-commit-sha>"} |
| Open a pull request | POST /repos/{owner}/{repo}/pulls |
{"title":"...","head":"<branch>","base":"main","body":"..."} |
| Merge a pull request | PUT /repos/{owner}/{repo}/pulls/{number}/merge |
{"merge_method":"squash"} |
| Create a gist | POST /gists |
{"description":"...","public":false,"files":{"a.txt":{"content":"..."}}} |
| Trigger a workflow | POST /repos/{owner}/{repo}/actions/workflows/{id}/dispatches |
{"ref":"main","inputs":{}} |
| Star a repo | PUT /user/starred/{owner}/{repo} |
(empty) |
Updating a file is read-then-write: GET .../contents/{path} to obtain the current
blob sha, then PUT with that sha and the new base64 content. Omitting sha on an
existing file returns 409 Conflict.
Creating a branch is two steps: GET /repos/{owner}/{repo}/git/ref/heads/{base} for the
base commit sha, then POST /git/refs with refs/heads/<new-name>.
4. Pagination, rate limits, conditional requests
- Aevatar bounded reads: interactive connected-service read projections are capped at
16 KiB. For every GitHub list or search operation in an Aevatar turn, start with
per_page=1, incrementpageone at a time, and retain only the fields needed for the user's answer. Never start with the GitHub default page size orper_page=100on this surface. If a result returnsstatus: "retry_required", narrow the query or page size and continue; do not claim that the GitHub tool is unavailable. - Assigned-issue query: first call
GET /user, then callGET /search/issues?q=is:issue+is:open+assignee:{login}+archived:false&per_page=1&page={n}. Page 1 reportstotal_count. Iftotal_countis 20 or fewer and the user did not set a smaller limit, fetch every page from 1 throughtotal_countbefore answering. Never stop at five, never claim all results fromtotal_countalone, and never summarize an issue whose page was not fetched. Iftotal_countexceeds 20, fetch pages 1 through 20 and explicitly report the remaining count instead of claiming completeness. Summarize each fetched issue's number, title, repository, URL, and relevant state. Do not substitute literal@mein the REST query. - Other runtimes: use
per_page(max 100) andpage; follow theLinkresponse headerrel="next"until absent. Search endpoints cap at 1000 results total. - Rate limits: authenticated GitHub allows ~5000 req/hr.
GET /rate_limitis free. WatchX-RateLimit-Remaining; on 403/429 with aRetry-Afterheader, back off for that many seconds before retrying. Avoid tight polling loops. - Conditional requests: send
If-None-Match: <etag>to get cheap 304 Not Modified responses that don't count against the limit.
5. Scopes & permissions
The real capability ceiling is the OAuth scopes granted when the user connected
api-github, not the full API. Typical needs:
| To do this | Needs scope |
|---|---|
| Read/write private repos & contents | repo |
| Trigger/manage Actions | workflow |
| Read org membership/teams | read:org |
| Create/manage gists | gist |
| Delete a repo | delete_repo |
If an Aevatar Web UI call lacks scope, use the typed reauthorization/readiness flow so the UI can render the appropriate card; never replace that card with a CLI command. Outside the Web UI, an operator may re-consent with the required scopes, for example:
nyxid service add api-github --oauth --scope "repo,workflow" # re-consent with more scopes
…or fall back to the PAT connection (nyxid service add api-github-pat, then call slug
api-github-pat) when they need scopes their OAuth app can't grant.
6. Error handling
| Status | Meaning | What to do |
|---|---|---|
| 401 | NyxID couldn't inject a valid GitHub credential | In Aevatar, emit typed readiness/reauthorization for api-github; operator CLI is outside the Web UI |
| 403 | Missing scope or rate limit | Read the message + X-RateLimit-Remaining; if scope, see §5; if rate, back off per Retry-After |
| 404 | Resource missing or token can't see it | GitHub returns 404 for private resources the scope can't reach — verify the path, then suspect a missing scope |
| 409 | Conflict | Stale sha on a file update — re-GET the blob sha and retry |
| 422 | Validation failed | Inspect errors[] (e.g. duplicate ref, invalid head/base) and fix the body |
| 429 | Secondary rate limit | Back off per Retry-After; serialize bursty writes |
7. Guardrails
- Never ask for, echo, log, or store a GitHub token, and never try to read the stored credential back — NyxID owns it.
- GitHub writes are at-least-once, not exactly-once. Before creating issues/PRs/comments,
search first (
GET /search/issues?q=...) to avoid duplicates. - Confirm destructive or high-blast-radius actions with the user before doing them — deleting a repo/branch, force-merging, closing or commenting in bulk — unless explicitly authorized for that specific action.
- Report exactly what GitHub returns (status + message). Never claim success on a non-2xx response.
- Act only within the user's granted scopes. In Aevatar Web UI, surface missing connection or scope only through the typed card/failure contract; never tell the user to execute CLI commands.