GitHub's REST surface is large; focus on the operational patterns you need to complete user requests. Most work ties back to repositories, organizations, users, issues, pull requests, and Actions (workflows/runners/secrets). Understand which identifier each operation needs and where to fetch it first.

How the domain is organized

• Resources are primarily scoped to repository (owner + repo) or organization (org). Many operations require one or the other; some organization-level features require both org and a repository_id (numeric ID) rather than owner/repo.
• Common resource IDs you’ll use repeatedly:
  • Repository: owner + repo (string pair) and the repository numeric id (returned by repo list/get operations).
  • Issue / Pull Request: issue_number or pull_number (per-repo integers).
  • Workflows: workflow_id — can be the numeric workflow id or the workflow filename string (use whichever you have).
  • Workflow runs / jobs: run_id, job_id, attempt_number.
  • Runners: runner_id, hosted_runner_id, and runner_group_id at org level.
  • Secrets / variables: secret_name or name, often paired with scope (repo, org, environment).

Knowing which of these you need and how to get it is the single biggest practical difference between succeeding and getting stuck.

Entry points — what to call first

Start by asking what scope the user means: repository or organization. Then obtain the identifying objects you’ll need for downstream calls.

• If the user names a repo (owner/repo), you usually already have what you need. If you need the numeric repository ID, call repos.get or a repo list operation for the account that owns it — the response includes id.
• If the user asks about multiple repositories or you need to discover a repository, use repos.list-for-authenticated-user, repos.list-for-org, or search/repos to find repositories and their id fields.
• For issues and PRs:
  • To enumerate: issues.list-for-repo (issues) or pulls.list (pull requests). Those responses include issue_number / pull_number you’ll use for get/update operations.
  • To get a single item: issues.get or pulls.get.
• For workflows and runs:
  • Discover workflows with actions.list-repo-workflows (returns workflow objects and file names).
  • Discover runs with actions.list-workflow-runs or actions.list-workflow-runs-for-repo and extract run_id (then use actions.get-workflow-run).
• For self-hosted runners and runner groups (organization scope): list with actions/list-self-hosted-runners-for-org and actions/list-self-hosted-runner-groups-for-org to obtain runner_id and runner_group_id.
• For repository vs organization secrets/variables: use the appropriate list/get operation (actions/list-repo-secrets, actions/get-org-secret, codespaces/get-repo-public-key, etc.) to obtain the names and any public key objects required by secret-related endpoints.

Fetch the specific ID or name you need with the listing/get operation before calling the action-oriented operation (create/update/delete/trigger) that requires it.

Common capabilities and the call sequence you’ll use

Below are the common user requests agents receive and the minimal sequence of operations you typically invoke to fulfill them.

• Create, update, or read repository content (files, README, topics)

  • To inspect: repos.get, repos/get-readme, or repos/get-content.
  • To create/update files: call repos.create-or-update-file-contents with the repo and path.
  • To change repo metadata: repos.update or repos/replace-all-topics.

• Work with issues

  • List or search to find the issue: issues.list-for-repo or search/issues-and-pull-requests.
  • Get details: issues.get.
  • Create or edit: issues.create and issues.update.
  • Labels/assignees: issues/add-labels, issues/set-labels, issues/add-assignees, issues/remove-assignees.

• Pull requests, reviews, and merges

  • Find PRs: pulls.list or repos/list-pull-requests-associated-with-commit.
  • Get and operate on a single PR: pulls.get.
  • Create: pulls.create.
  • Reviews: pulls.create-review, pulls/submit-review, pulls/dismiss-review.
  • Merge: pulls/merge (use the PR’s pull_number).

• Workflows (Actions): triggering, inspecting, reruns

  • Discover workflows: actions.list-repo-workflows (obtain workflow_id or filename).
  • Trigger: actions.create-workflow-dispatch (requires workflow_id/filename and ref).
  • List runs: actions.list-workflow-runs / actions.list-workflow-runs-for-repo (obtain run_id).
  • Inspect run: actions.get-workflow-run and jobs with actions/list-jobs-for-workflow-run.
  • Rerun or cancel: actions/re-run-workflow, actions/re-run-workflow-failed-jobs, actions/cancel-workflow-run.
  • Download logs/artifacts: actions/download-workflow-run-logs, actions/list-workflow-run-artifacts, actions/download-artifact.

• Self-hosted runners and runner groups

  • List runners/groups: actions/list-self-hosted-runners-for-org and actions/list-self-hosted-runner-groups-for-org.
  • To register a runner you will call actions/create-registration-token-for-repo or actions/create-registration-token-for-org to obtain the token value used by the runner registration process.
  • Group operations (add/remove runners, set repositories) require runner_group_id and runner_id values discovered from list endpoints.

• Secrets and variables

  • To list secrets/variables: actions/list-repo-secrets, actions/list-org-secrets, codespaces/list-repo-secrets, etc.
  • For repository secrets you often need the repository public key first (actions/get-repo-public-key, codespaces/get-repo-public-key, or the org equivalent) — the secret-related APIs require working with that key.
  • Use create-or-update-repo-secret / create-or-update-org-secret / codespaces equivalents to create secrets (see gotchas below).

• Search and discovery

  • Use search/repos, search/issues-and-pull-requests, search/code to find target repositories, issues, or code snippets and then pivot to concrete operations that return the IDs you need.

Non-obvious patterns and gotchas

• owner/repo vs repository_id: many organization-level "selected repositories" endpoints expect a numeric repository_id. To get that numeric ID, call repos.get, one of the repo list endpoints, or any endpoint that returns repository objects. Never assume the string owner/repo will be accepted where repository_id is documented.

• Workflow identifiers: workflow_id accepts either the numeric ID or the workflow file name (e.g., ci.yml). If a user references a filename, pass it directly. If you need the numeric id, use actions/list-repo-workflows to retrieve it.

• Secrets require a repository/org public key and an encrypted payload: secret creation endpoints expect an encrypted value paired with the repository/org public key object returned by the appropriate public-key endpoint. The API surface exposes both the public key and the secret operations — you will typically list/get the public key, then provide the encrypted value when creating/updating the secret. If the user cannot supply an already-encrypted secret value, explain they must provide it (or provide instructions outside the API for how to encrypt using the public key) because the API expects the encrypted payload.

• Runner registration tokens and ephemeral credentials: registration tokens from actions/create-registration-token-for-repo or ...for-org are short-lived; they are produced on demand and used by the runner registration flow. Create a token only when you need to register a runner and treat it as ephemeral.

• Distinguish repository-scoped and organization-scoped features:

  • Organization-level runner groups, organization secrets, organization variables, and many billing or enterprise endpoints require org and sometimes numeric repository ids.
  • Repository-level operations use owner + repo. Confirm the requested scope before calling.

• Some endpoints return binary content (artifacts, logs, archive downloads). The response body will be the artifact/archive; treat those as download operations rather than JSON resources.

• Many list endpoints are paginated. Use the page and per_page parameters to request specific pages. If a user asks for more results than the default page, call the same list operation with an adjusted page/per_page.

• Asynchronous or long-running behaviors are surfaced by status codes or by separate status endpoints. When an operation returns a 202 or an operation documentation comment indicates processing, check the related status/list endpoint (for example, migration and import endpoints expose status endpoints you should call to observe completion).

• Rate limit visibility: you can query rate-limit/get to see current rate-limit buckets for the authenticated token; behavior differs by authentication type (user token, app, installation), so check it when you need to reason about limits.

Practical tips for typical user requests

• "Create a PR from branch X into branch Y in repo owner/repo": ensure you have owner, repo, the branch names, then call pulls.create with head, base, and title (and optionally body). If you need to find the branch or confirm it exists, call repos/get-branch first.

• "Merge PR #N": call pulls.merge with owner, repo, and pull_number. If the merge fails (mergeable state), return the full pulls.get response to the user so they can resolve conflicts.

• "Run workflow Z on branch B": find workflow_id with actions.list-repo-workflows (if user gave a name, you can pass the filename). Then call actions.create-workflow-dispatch with the ref set to the branch or commit SHA and any required inputs.

• "Add an org repo to an org secret": confirm you have the org's secret_name and the target repository numeric repository_id. Use the org secret selected-repos endpoints (actions/add-selected-repo-to-org-secret / actions/set-selected-repos-for-org-secret) as appropriate.

• "Download artifact from run": list artifacts for the run with actions/list-workflow-run-artifacts (or actions/list-artifacts-for-repo), pick the artifact artifact_id, then call actions/download-artifact (or the artifact download endpoint) with the chosen archive_format.

What to check in responses

• When you fetch a list, look for the total_count and item arrays (repositories, workflow_runs, artifacts, etc.). Those objects contain the IDs you’ll need for next steps.
• For any operation that returns a token (registration tokens, installation access tokens), the token is typically short-lived and meant for immediate use in a separate flow.
• For operations that return resources updated/created, the response body usually contains the canonical ID fields to use in later calls (e.g., id, issue_number, run_id). Use those instead of guessing.

When you can’t complete an action

• If a secret must be created but the user cannot provide an encrypted value, explain the requirement: the API expects an encrypted secret payload tied to the repo/org public key. Ask the user to supply the encrypted value or to perform encryption outside the API flow.
• If the user refers to resources that are ambiguous (e.g., "workflow X" but multiple workflows share that name), return the list of matching workflows (actions.list-repo-workflows) and ask which exact workflow (filename or numeric id) to act on.

Short operation hints (where to look first)

• Get repository metadata and numeric ID: repos.get or repos.list-for-authenticated-user / repos/list-for-org.
• Discover workflows and workflow IDs: actions.list-repo-workflows.
• Get workflow runs and run_id: actions/list-workflow-runs / actions/list-workflow-runs-for-repo.
• Get repository public key (for secrets): actions/get-repo-public-key (or codespaces/org equivalents).
• Registration token for runners: actions/create-registration-token-for-repo / ...-for-org.
• Find issues/pull requests: issues.list-for-repo, pulls.list, or search/issues-and-pull-requests.
• Check rate limits: rate-limit/get.

Use these patterns as recipes: list/discover → extract the ID(s) required → call the create/update/delete/trigger operation that requires those IDs. When a required value cannot be produced by the API (for example an encrypted secret value), ask the user for it or explain how to get it.

This approach—discover identifiers first, then call the operation that needs them—lets you move through the API reliably without guessing IDs or operation scope.