# Github Via Nyxid

> Operate a user's GitHub account through NyxID's credential-brokering proxy (service slug api-github) — read and write repositories, files, issues, pull requests, commits, branches, Actions, gists and anything else the GitHub REST API exposes, all on the user's behalf and without ever handling a raw token. NyxID injects the user's GitHub credential server-side. Use when an agent needs to read from or act on GitHub for a user who has connected their GitHub account in NyxID.

- Skill: `chronoaiproject/github-via-nyxid` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add chronoaiproject/github-via-nyxid`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chronoaiproject/github-via-nyxid/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: ChronoAIProject (https://skillmd.com/u/chronoaiproject)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/chronoaiproject/github-via-nyxid

---


# 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-github` connection permit. The ceiling is the
> granted scopes, not the entire API surface (see [Scopes & permissions](#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:

```json
{
  "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:

```json
{
  "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`:

```yaml
- 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:**

```bash
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`, increment `page` one at a time, and retain only the fields needed for the
  user's answer. Never start with the GitHub default page size or `per_page=100` on this
  surface. If a result returns `status: "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 call
  `GET /search/issues?q=is:issue+is:open+assignee:{login}+archived:false&per_page=1&page={n}`.
  Page 1 reports `total_count`. If `total_count` is 20 or fewer and the user did not set a
  smaller limit, fetch every page from 1 through `total_count` before answering. Never stop at
  five, never claim all results from `total_count` alone, and never summarize an issue whose page
  was not fetched. If `total_count` exceeds 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 `@me` in the REST query.
- **Other runtimes:** use `per_page` (max **100**) and `page`; follow the `Link` response header
  `rel="next"` until absent. Search endpoints cap at **1000** results total.
- **Rate limits:** authenticated GitHub allows ~**5000 req/hr**. `GET /rate_limit` is free.
  Watch `X-RateLimit-Remaining`; on **403/429** with a `Retry-After` header, 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:

```bash
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.

