@emulators/github

Fully stateful GitHub API emulation. Creates, updates, and deletes persist in memory and affect related entities.

Part of emulate — local drop-in replacement services for CI and no-network sandboxes.

Install

npm install @emulators/github

Endpoints

Users

• GET /user — authenticated user
• PATCH /user — update profile
• GET /users/:username — get user
• GET /users — list users
• GET /users/:username/repos — list user repos
• GET /users/:username/orgs — list user orgs
• GET /users/:username/followers — list followers
• GET /users/:username/following — list following

Repositories

• GET /repos/:owner/:repo — get repo
• POST /user/repos — create user repo
• POST /orgs/:org/repos — create org repo
• PATCH /repos/:owner/:repo — update repo
• DELETE /repos/:owner/:repo — delete repo (cascades)
• GET/PUT /repos/:owner/:repo/topics — get/replace topics
• GET /repos/:owner/:repo/languages — languages
• GET /repos/:owner/:repo/contributors — contributors
• GET /repos/:owner/:repo/forks — list forks
• POST /repos/:owner/:repo/forks — create fork
• GET/PUT/DELETE /repos/:owner/:repo/collaborators/:username — collaborators
• GET /repos/:owner/:repo/collaborators/:username/permission
• POST /repos/:owner/:repo/transfer — transfer repo
• GET /repos/:owner/:repo/tags — list tags

Issues

• GET /repos/:owner/:repo/issues — list (filter by state, labels, assignee, milestone, creator, since)
• POST /repos/:owner/:repo/issues — create
• GET /repos/:owner/:repo/issues/:number — get
• PATCH /repos/:owner/:repo/issues/:number — update (state transitions, events)
• PUT/DELETE /repos/:owner/:repo/issues/:number/lock — lock/unlock
• GET /repos/:owner/:repo/issues/:number/timeline — timeline events
• GET /repos/:owner/:repo/issues/:number/events — events
• POST/DELETE /repos/:owner/:repo/issues/:number/assignees — manage assignees

Pull Requests

• GET /repos/:owner/:repo/pulls — list (filter by state, head, base)
• POST /repos/:owner/:repo/pulls — create
• GET /repos/:owner/:repo/pulls/:number — get
• PATCH /repos/:owner/:repo/pulls/:number — update
• PUT /repos/:owner/:repo/pulls/:number/merge — merge (with branch protection enforcement)
• GET /repos/:owner/:repo/pulls/:number/commits — list commits
• GET /repos/:owner/:repo/pulls/:number/files — list files
• POST/DELETE /repos/:owner/:repo/pulls/:number/requested_reviewers — manage reviewers
• PUT /repos/:owner/:repo/pulls/:number/update-branch — update branch

Comments

• Issue comments: full CRUD on /repos/:owner/:repo/issues/:number/comments
• Review comments: full CRUD on /repos/:owner/:repo/pulls/:number/comments
• Commit comments: full CRUD on /repos/:owner/:repo/commits/:sha/comments
• Repo-wide listings for each type

Reviews

• GET /repos/:owner/:repo/pulls/:number/reviews — list
• POST /repos/:owner/:repo/pulls/:number/reviews — create (with inline comments)
• GET/PUT /repos/:owner/:repo/pulls/:number/reviews/:id — get/update
• POST /repos/:owner/:repo/pulls/:number/reviews/:id/events — submit
• PUT /repos/:owner/:repo/pulls/:number/reviews/:id/dismissals — dismiss

Labels & Milestones

• Labels: full CRUD, add/remove from issues, replace all
• Milestones: full CRUD, state transitions, issue counts

Branches & Git Data

• Branches: list, get, protection CRUD (status checks, PR reviews, enforce admins)
• Refs: get, match, create, update, delete
• Commits: get, create
• Trees: get (with recursive), create (with inline content)
• Blobs: get, create
• Tags: get, create

Organizations & Teams

• Orgs: get, update, list
• Org members: list, check, remove, get/set membership
• Teams: full CRUD, members, repos

Releases

• Releases: full CRUD, latest, by tag
• Release assets: full CRUD, upload
• Generate release notes

Webhooks

• Repo webhooks: full CRUD, ping, test, deliveries
• Org webhooks: full CRUD, ping
• Real HTTP delivery to registered URLs on all state changes

Search

• GET /search/repositories — full query syntax (user, org, language, topic, stars, forks, etc.)
• GET /search/issues — issues + PRs (repo, is, author, label, milestone, state, etc.)
• GET /search/users — users + orgs
• GET /search/code — blob content search
• GET /search/commits — commit message search
• GET /search/topics — topic search
• GET /search/labels — label search

Actions

• Workflows: list, get, enable/disable, dispatch
• Workflow runs: list, get, cancel, rerun, delete, logs
• Jobs: list, get, logs
• Artifacts: list, get, delete
• Secrets: repo + org CRUD

Checks

• Check runs: create, update, get, annotations, rerequest, list by ref/suite
• Check suites: create, get, preferences, rerequest, list by ref
• Automatic suite status rollup from check run results

Misc

• GET /rate_limit — rate limit status
• GET /meta — server metadata
• GET /octocat — ASCII art
• GET /emojis — emoji URLs
• GET /zen — random zen phrase
• GET /versions — API versions

Auth

Public repo endpoints work without auth. Private repos and write operations require a valid token. Pagination uses page/per_page with Link headers.

Seed Configuration

github:
  users:
    - login: octocat
      name: The Octocat
      email: [email protected]
  orgs:
    - login: my-org
      name: My Organization
  repos:
    - owner: octocat
      name: hello-world
      language: JavaScript
      auto_init: true
  oauth_apps:
    - client_id: "Iv1.abc123"
      client_secret: "secret_abc123"
      name: "My Web App"
      redirect_uris:
        - "http://localhost:3000/api/auth/callback/github"
  apps:
    - app_id: 12345
      slug: "my-github-app"
      name: "My GitHub App"
      private_key: |
        -----BEGIN RSA PRIVATE KEY-----
        ...your PEM key...
        -----END RSA PRIVATE KEY-----
      permissions:
        contents: read
        issues: write
      events: [push, pull_request]
      installations:
        - installation_id: 100
          account: my-org
          repository_selection: all

Links

• Full documentation
• GitHub