emulate

GitHub API

Every endpoint below is fully stateful. Creates, updates, and deletes persist in memory and affect related entities.

GitHub App keys

The programmatic createEmulator API can generate a GitHub App key when private_key is omitted:

const github = await createEmulator({
  service: 'github',
  seed: {
    github: {
      users: [{ login: 'octocat' }],
      apps: [{
        app_id: 12345,
        slug: 'my-github-app',
        name: 'My GitHub App',
        installations: [{ installation_id: 100, account: 'octocat' }],
      }],
    },
  },
})

const privateKey = github.generatedSecrets.find(
  secret => secret.kind === 'github.app_private_key' && secret.id === '12345',
)?.value

The generated RSA-2048 PKCS#1 key remains stable across reset() calls. Explicit keys are never included in generatedSecrets.

The Next.js and Nuxt adapters also generate omitted keys. Their returned server handlers expose generatedSecrets(), and persistence restores the same identity across cold starts. Keep persisted snapshots private because they contain the signing key. Custom persistence backends must implement atomic initialize() semantics when generated identities are used.

Installation token inspection

GET /_emulate/installation-tokens lists metadata for GitHub App installation tokens minted by the current emulator state. It includes App, installation, account, permissions, repository access, issuance, expiry, and lifecycle status without exposing token values or token-derived identifiers.

Expiry is informational and does not change authorization behavior. createEmulator().reset() clears minted installation-specific authorization and metadata while preserving seeded tokens, generated App keys, and existing fallback-token behavior. Persisted Next.js and Nuxt adapters restore the metadata with their private snapshot.

Installation access tokens act as the configured GitHub App bot for repository writes. Repository ownership, selected repository access, and requested App permissions remain enforced. Pull request merges require contents: write on the base repository. Pull request branch updates require pull_requests: write on the pull request repository and contents: write on the head repository.

The CLI can generate omitted keys when you request a private delivery file:

npx emulate start --service github --seed emulate.config.yaml \
  --generated-secrets-file .emulate-secrets.json

The destination must not exist. emulate removes inherited ACLs, verifies effective owner-only access, and publishes complete JSON before opening listeners or configuring portless. Handled startup failures remove the invocation-owned artifact. A hard termination can leave a complete artifact that must be removed manually after confirming no invocation is using it. Only generated keys appear in the artifact. Linux requires setfacl and getfacl from the acl package. The flag fails closed when access controls cannot be verified and is not supported on Windows. Without --generated-secrets-file, CLI seed files still require private_key. Direct seedFromConfig calls always require it.

Seed Config

github:
  users:
    - login: octocat
      name: The Octocat
  orgs:
    - login: my-org
      name: My Organization
      members:
        - login: octocat
          role: admin
  repos:
    - owner: my-org
      name: org-repo
      private: true

Organization members are optional. Each entry references a seeded user by login; role defaults to member, and admin creates an organization administrator. Unknown users are ignored. Seeded memberships use the synthetic members team and grant private organization repository access.

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
  • GET /repositories/:id - get repo by numeric ID
  • 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

Contents & Commit History

  • GET /repos/:owner/:repo/readme - get the repository README
  • GET /repos/:owner/:repo/contents/:path - get a file or list a directory at a ref
  • Send Accept: application/vnd.github.raw or application/vnd.github.raw+json to file Contents and README requests to receive raw bytes; directory and submodule responses remain JSON
  • GET /:owner/:repo/raw/:ref/:path - download file content from advertised raw URLs; this is separate from Accept negotiation
  • PUT/DELETE /repos/:owner/:repo/contents/:path - create, update, or delete a file and commit the change
  • GET /repos/:owner/:repo/commits - list commits with ref, path, author, and date filters
  • GET /repos/:owner/:repo/commits/:ref - get a commit with file diffs and stats
  • GET /repos/:owner/:repo/compare/:base...:head - compare two refs

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. Ref based lookups accept branch and tag refs containing slashes.
  • Check suites: create, get, preferences, rerequest, list by ref. Ref based lookups accept branch and tag refs containing slashes.
  • 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