spec: "https://dadl.ai/spec/dadl-spec-v0.1.md"

credits:
  - "Dunkel Cloud GmbH"
source_name: "GitHub REST API v3"
source_url: "https://docs.github.com/en/rest"
date: "2026-04-02"

backend:
  name: github
  type: rest
  # base_url: https://api.github.com — provide via backends.yaml url field
  description: "GitHub REST API — repositories, issues, pull requests, commits, and code search"

  coverage:
    endpoints: 205
    total_endpoints: 900
    percentage: 23
    focus: "repos (full CRUD + fork + collaborators + topics), orgs (members + teams), issues (full CRUD + comments + events + reactions), PRs (full CRUD + merge + reviews + review comments + requested reviewers), commits, branches (+ protection), git refs + objects (blobs, trees, commits), file management, labels, milestones, search (code + issues + repos + users + commits), releases (full CRUD), actions (workflows + runs + jobs + logs + secrets + artifacts + dispatch), users, tags, webhooks, deployments (+ statuses), environments, gists (full CRUD), notifications, check runs/suites, commit statuses, starring, watching, pages, code scanning, dependabot, secret scanning, packages (org + user: list, get, delete, restore, versions)"
    missing: "projects v2, codespaces, copilot, security advisories, rate limit API, git LFS, autolinks, repository rulesets"
    last_reviewed: "2026-04-02"

  setup:
    credential_steps:
      - "Navigate to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)"
      - "Click 'Generate new token (classic)'"
      - "Select scopes: repo (full access), read:org (list organizations), workflow (actions), admin:repo_hook (webhooks), delete_repo (delete repos), gist, notifications, read:packages, write:packages, delete:packages"
      - "Copy the token (starts with ghp_ or github_pat_)"
    env_var: CREDENTIAL_GITHUB_TOKEN
    backends_yaml: |
      - name: github
        transport: rest
        dadl: github.dadl
        url: "https://api.github.com"
    required_scopes:
      - repo
      - read:org
    optional_scopes:
      - read:user
      - workflow
      - admin:repo_hook
      - delete_repo
      - gist
      - notifications
      - read:packages
    docs_url: "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens"

  auth:
    type: bearer
    credential: github_token
    inject_into: header
    header_name: Authorization
    prefix: "Bearer "

  defaults:
    headers:
      Accept: application/vnd.github+json
      Content-Type: application/json
      X-GitHub-Api-Version: "2022-11-28"
    pagination: &default-pagination
      strategy: page
      request:
        page_param: page
        limit_param: per_page
        limit_default: 30
      response:
        # GitHub uses Link header for pagination
        next_link_header: Link
      behavior: manual
      max_pages: 10
    errors: &standard-errors
      format: json
      message_path: "$.message"
      retry_on: [429, 502, 503]
      terminal: [400, 401, 403, 404, 409, 422]
      retry_strategy:
        max_retries: 3
        backoff: exponential
        initial_delay: 1s

  # ──────────────────────────────────────────────────────────────
  # Domain notes (for LLM consumers of these tools)
  #
  # Owner/Repo pattern:
  #   Most endpoints require owner (user or org) and repo name.
  #   These are path parameters, not the full URL.
  #   Example: owner="DunkelCloud", repo="ToolMesh"
  #
  # Rate limiting:
  #   Authenticated: 5000 requests/hour. Check response headers
  #   X-RateLimit-Remaining and X-RateLimit-Reset.
  #
  # Issue vs PR:
  #   In GitHub's API, pull requests ARE issues with extra fields.
  #   list_issues may return PRs too — use filter or check for
  #   pull_request field in response.
  #
  # State values:
  #   Issues/PRs: "open", "closed", "all"
  #   For PRs also: "merged" (but query via is:merged in search)
  #
  # Labels:
  #   Passed as array of label name strings, not objects.
  #   Example: ["bug", "priority:high"]
  #
  # Markdown:
  #   Body fields (issues, PRs, comments) support GitHub-Flavored
  #   Markdown including task lists, code blocks, and @mentions.
  #
  # Permissions:
  #   Some endpoints require specific token scopes (e.g. delete_repo,
  #   admin:repo_hook). Check setup.optional_scopes for details.
  # ──────────────────────────────────────────────────────────────

  tools:

    # ── Repositories ──────────────────────────────────────────

    create_repo:
      method: POST
      path: /user/repos
      access: write
      description: "Create a new repository for the authenticated user. Set private=true for a private repo. auto_init=true creates an initial commit with a README."
      params:
        name: { type: string, in: body, required: true }
        description: { type: string, in: body }
        homepage: { type: string, in: body }
        private: { type: boolean, in: body, default: false }
        has_issues: { type: boolean, in: body, default: true }
        has_projects: { type: boolean, in: body, default: true }
        has_wiki: { type: boolean, in: body, default: true }
        has_discussions: { type: boolean, in: body }
        auto_init: { type: boolean, in: body }
        gitignore_template: { type: string, in: body }
        license_template: { type: string, in: body }
        allow_squash_merge: { type: boolean, in: body }
        allow_merge_commit: { type: boolean, in: body }
        allow_rebase_merge: { type: boolean, in: body }
        delete_branch_on_merge: { type: boolean, in: body }
        is_template: { type: boolean, in: body }
      pagination: none

    create_org_repo:
      method: POST
      path: /orgs/{org}/repos
      access: write
      description: "Create a new repository in an organization. Requires org admin or repo creation permissions."
      params:
        org: { type: string, in: path, required: true }
        name: { type: string, in: body, required: true }
        description: { type: string, in: body }
        homepage: { type: string, in: body }
        private: { type: boolean, in: body, default: false }
        visibility: { type: string, in: body }
        has_issues: { type: boolean, in: body, default: true }
        has_projects: { type: boolean, in: body, default: true }
        has_wiki: { type: boolean, in: body, default: true }
        has_discussions: { type: boolean, in: body }
        auto_init: { type: boolean, in: body }
        gitignore_template: { type: string, in: body }
        license_template: { type: string, in: body }
        allow_squash_merge: { type: boolean, in: body }
        allow_merge_commit: { type: boolean, in: body }
        allow_rebase_merge: { type: boolean, in: body }
        delete_branch_on_merge: { type: boolean, in: body }
        is_template: { type: boolean, in: body }
        team_id: { type: integer, in: body }
      pagination: none

    create_repo_from_template:
      method: POST
      path: /repos/{template_owner}/{template_repo}/generate
      access: write
      description: "Create a new repository from a template. The template must have is_template=true."
      params:
        template_owner: { type: string, in: path, required: true }
        template_repo: { type: string, in: path, required: true }
        owner: { type: string, in: body, required: true }
        name: { type: string, in: body, required: true }
        description: { type: string, in: body }
        include_all_branches: { type: boolean, in: body }
        private: { type: boolean, in: body }
      pagination: none

    list_user_repos:
      method: GET
      path: /user/repos
      access: read
      description: "List repositories for the authenticated user. Use type to filter (owner, member, all)."
      params:
        type: { type: string, in: query, default: "owner" }
        sort: { type: string, in: query, default: "updated" }
        direction: { type: string, in: query, default: "desc" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    list_user_repos_by_username:
      method: GET
      path: /users/{username}/repos
      access: read
      description: "List public repositories for a specific user."
      params:
        username: { type: string, in: path, required: true }
        type: { type: string, in: query, default: "owner" }
        sort: { type: string, in: query, default: "updated" }
        direction: { type: string, in: query, default: "desc" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_repo:
      method: GET
      path: /repos/{owner}/{repo}
      access: read
      description: "Get a single repository by owner and name."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
      pagination: none

    update_repo:
      method: PATCH
      path: /repos/{owner}/{repo}
      access: write
      description: "Update repository settings. Only include fields you want to change. Use for description, homepage, visibility, merge settings, etc."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        description: { type: string, in: body }
        homepage: { type: string, in: body }
        private: { type: boolean, in: body }
        has_issues: { type: boolean, in: body }
        has_projects: { type: boolean, in: body }
        has_wiki: { type: boolean, in: body }
        has_discussions: { type: boolean, in: body }
        allow_squash_merge: { type: boolean, in: body }
        allow_merge_commit: { type: boolean, in: body }
        allow_rebase_merge: { type: boolean, in: body }
        delete_branch_on_merge: { type: boolean, in: body }
        allow_forking: { type: boolean, in: body }
        allow_auto_merge: { type: boolean, in: body }
        allow_update_branch: { type: boolean, in: body }
        archived: { type: boolean, in: body }
        default_branch: { type: string, in: body }
      pagination: none

    delete_repo:
      method: DELETE
      path: /repos/{owner}/{repo}
      access: dangerous
      description: "Delete a repository. Requires delete_repo scope. This action is irreversible."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
      pagination: none

    replace_topics:
      method: PUT
      path: /repos/{owner}/{repo}/topics
      access: write
      description: "Replace all repository topics. Provide the full list of desired topics."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        names: { type: array, in: body, required: true }
      pagination: none

    list_repo_languages:
      method: GET
      path: /repos/{owner}/{repo}/languages
      access: read
      description: "List languages for a repository. Returns a map of language name to bytes of code."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
      pagination: none

    list_repo_contributors:
      method: GET
      path: /repos/{owner}/{repo}/contributors
      access: read
      description: "List contributors to a repository, sorted by number of commits."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        anon: { type: string, in: query }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_readme:
      method: GET
      path: /repos/{owner}/{repo}/readme
      access: read
      description: "Get the README file for a repository. Content is base64 encoded."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        ref: { type: string, in: query }
      pagination: none

    # ── Forks ────────────────────────────────────────────────

    list_forks:
      method: GET
      path: /repos/{owner}/{repo}/forks
      access: read
      description: "List forks of a repository."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        sort: { type: string, in: query, default: "newest" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    create_fork:
      method: POST
      path: /repos/{owner}/{repo}/forks
      access: write
      description: "Fork a repository. Optionally specify an organization to fork into. Forking is asynchronous — poll get_repo to check when complete."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        organization: { type: string, in: body }
        name: { type: string, in: body }
        default_branch_only: { type: boolean, in: body }
      pagination: none

    # ── Collaborators ────────────────────────────────────────

    list_collaborators:
      method: GET
      path: /repos/{owner}/{repo}/collaborators
      access: read
      description: "List collaborators for a repository. Affiliation: outside, direct, all."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        affiliation: { type: string, in: query, default: "all" }
        permission: { type: string, in: query }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    check_collaborator:
      method: GET
      path: /repos/{owner}/{repo}/collaborators/{username}
      access: read
      description: "Check if a user is a collaborator. Returns 204 if yes, 404 if no."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        username: { type: string, in: path, required: true }
      pagination: none

    add_collaborator:
      method: PUT
      path: /repos/{owner}/{repo}/collaborators/{username}
      access: admin
      description: "Add a collaborator to a repository. Permission: pull, triage, push, maintain, admin."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        username: { type: string, in: path, required: true }
        permission: { type: string, in: body, default: "push" }
      pagination: none

    remove_collaborator:
      method: DELETE
      path: /repos/{owner}/{repo}/collaborators/{username}
      access: dangerous
      description: "Remove a collaborator from a repository."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        username: { type: string, in: path, required: true }
      pagination: none

    # ── Organizations ──────────────────────────────────────

    list_orgs:
      method: GET
      path: /user/orgs
      access: read
      description: "List organizations the authenticated user belongs to."
      params:
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_org:
      method: GET
      path: /orgs/{org}
      access: read
      description: "Get an organization by name, including member count, repo count, and billing info."
      params:
        org: { type: string, in: path, required: true }
      pagination: none

    list_org_repos:
      method: GET
      path: /orgs/{org}/repos
      access: read
      description: "List repositories for an organization. Use list_orgs first to find org names."
      params:
        org: { type: string, in: path, required: true }
        type: { type: string, in: query, default: "all" }
        sort: { type: string, in: query, default: "updated" }
        direction: { type: string, in: query, default: "desc" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    list_org_members:
      method: GET
      path: /orgs/{org}/members
      access: read
      description: "List members of an organization. Filter by role: all, admin, member."
      params:
        org: { type: string, in: path, required: true }
        filter: { type: string, in: query, default: "all" }
        role: { type: string, in: query, default: "all" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    # ── Teams ────────────────────────────────────────────────

    list_org_teams:
      method: GET
      path: /orgs/{org}/teams
      access: read
      description: "List teams in an organization."
      params:
        org: { type: string, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_team:
      method: GET
      path: /orgs/{org}/teams/{team_slug}
      access: read
      description: "Get a team by its slug (URL-friendly name)."
      params:
        org: { type: string, in: path, required: true }
        team_slug: { type: string, in: path, required: true }
      pagination: none

    create_team:
      method: POST
      path: /orgs/{org}/teams
      access: write
      description: "Create a team in an organization. Privacy: secret (visible to org members) or closed (visible to org members, searchable)."
      params:
        org: { type: string, in: path, required: true }
        name: { type: string, in: body, required: true }
        description: { type: string, in: body }
        privacy: { type: string, in: body }
        notification_setting: { type: string, in: body }
        permission: { type: string, in: body }
        parent_team_id: { type: integer, in: body }
        repo_names: { type: array, in: body }
        maintainers: { type: array, in: body }
      pagination: none

    update_team:
      method: PATCH
      path: /orgs/{org}/teams/{team_slug}
      access: write
      description: "Update a team. Only include fields you want to change."
      params:
        org: { type: string, in: path, required: true }
        team_slug: { type: string, in: path, required: true }
        name: { type: string, in: body }
        description: { type: string, in: body }
        privacy: { type: string, in: body }
        notification_setting: { type: string, in: body }
        permission: { type: string, in: body }
        parent_team_id: { type: integer, in: body }
      pagination: none

    delete_team:
      method: DELETE
      path: /orgs/{org}/teams/{team_slug}
      access: dangerous
      description: "Delete a team from an organization."
      params:
        org: { type: string, in: path, required: true }
        team_slug: { type: string, in: path, required: true }
      pagination: none

    list_team_members:
      method: GET
      path: /orgs/{org}/teams/{team_slug}/members
      access: read
      description: "List members of a team. Role filter: all, member, maintainer."
      params:
        org: { type: string, in: path, required: true }
        team_slug: { type: string, in: path, required: true }
        role: { type: string, in: query, default: "all" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    add_team_member:
      method: PUT
      path: /orgs/{org}/teams/{team_slug}/memberships/{username}
      access: admin
      description: "Add or update a team member. Role: member or maintainer."
      params:
        org: { type: string, in: path, required: true }
        team_slug: { type: string, in: path, required: true }
        username: { type: string, in: path, required: true }
        role: { type: string, in: body, default: "member" }
      pagination: none

    remove_team_member:
      method: DELETE
      path: /orgs/{org}/teams/{team_slug}/memberships/{username}
      access: dangerous
      description: "Remove a member from a team."
      params:
        org: { type: string, in: path, required: true }
        team_slug: { type: string, in: path, required: true }
        username: { type: string, in: path, required: true }
      pagination: none

    list_team_repos:
      method: GET
      path: /orgs/{org}/teams/{team_slug}/repos
      access: read
      description: "List repositories a team has access to."
      params:
        org: { type: string, in: path, required: true }
        team_slug: { type: string, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    add_team_repo:
      method: PUT
      path: /orgs/{org}/teams/{team_slug}/repos/{owner}/{repo}
      access: admin
      description: "Add a repository to a team. Permission: pull, triage, push, maintain, admin."
      params:
        org: { type: string, in: path, required: true }
        team_slug: { type: string, in: path, required: true }
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        permission: { type: string, in: body }
      pagination: none

    remove_team_repo:
      method: DELETE
      path: /orgs/{org}/teams/{team_slug}/repos/{owner}/{repo}
      access: dangerous
      description: "Remove a repository from a team."
      params:
        org: { type: string, in: path, required: true }
        team_slug: { type: string, in: path, required: true }
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
      pagination: none

    # ── Issues ────────────────────────────────────────────────

    list_issues:
      method: GET
      path: /repos/{owner}/{repo}/issues
      access: read
      description: "List issues for a repository. Also returns PRs unless filtered. State: open, closed, all. Note: GitHub treats PRs as issues — check for pull_request field to distinguish."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        state: { type: string, in: query, default: "open" }
        labels: { type: string, in: query }
        assignee: { type: string, in: query }
        creator: { type: string, in: query }
        mentioned: { type: string, in: query }
        sort: { type: string, in: query, default: "created" }
        direction: { type: string, in: query, default: "desc" }
        since: { type: string, in: query }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_issue:
      method: GET
      path: /repos/{owner}/{repo}/issues/{issue_number}
      access: read
      description: "Get a single issue by number, including body, labels, assignees, and milestone."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        issue_number: { type: integer, in: path, required: true }
      pagination: none

    create_issue:
      method: POST
      path: /repos/{owner}/{repo}/issues
      access: write
      description: "Create a new issue. Labels are an array of label name strings."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        title: { type: string, in: body, required: true }
        body: { type: string, in: body }
        labels: { type: array, in: body }
        assignees: { type: array, in: body }
        milestone: { type: integer, in: body }
      pagination: none

    update_issue:
      method: PATCH
      path: /repos/{owner}/{repo}/issues/{issue_number}
      access: write
      description: "Update an issue. Set state to 'closed' to close it. Only include fields you want to change."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        issue_number: { type: integer, in: path, required: true }
        title: { type: string, in: body }
        body: { type: string, in: body }
        state: { type: string, in: body }
        state_reason: { type: string, in: body }
        labels: { type: array, in: body }
        assignees: { type: array, in: body }
        milestone: { type: integer, in: body }
      pagination: none

    lock_issue:
      method: PUT
      path: /repos/{owner}/{repo}/issues/{issue_number}/lock
      access: admin
      description: "Lock an issue. Lock reason: off-topic, too heated, resolved, spam."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        issue_number: { type: integer, in: path, required: true }
        lock_reason: { type: string, in: body }
      pagination: none

    unlock_issue:
      method: DELETE
      path: /repos/{owner}/{repo}/issues/{issue_number}/lock
      access: admin
      description: "Unlock an issue."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        issue_number: { type: integer, in: path, required: true }
      pagination: none

    list_issue_comments:
      method: GET
      path: /repos/{owner}/{repo}/issues/{issue_number}/comments
      access: read
      description: "List comments on an issue or pull request."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        issue_number: { type: integer, in: path, required: true }
        since: { type: string, in: query }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    create_issue_comment:
      method: POST
      path: /repos/{owner}/{repo}/issues/{issue_number}/comments
      access: write
      description: "Add a comment to an issue or pull request. Body supports GitHub-Flavored Markdown."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        issue_number: { type: integer, in: path, required: true }
        body: { type: string, in: body, required: true }
      pagination: none

    update_issue_comment:
      method: PATCH
      path: /repos/{owner}/{repo}/issues/comments/{comment_id}
      access: write
      description: "Update an issue comment."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        comment_id: { type: integer, in: path, required: true }
        body: { type: string, in: body, required: true }
      pagination: none

    delete_issue_comment:
      method: DELETE
      path: /repos/{owner}/{repo}/issues/comments/{comment_id}
      access: dangerous
      description: "Delete an issue comment."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        comment_id: { type: integer, in: path, required: true }
      pagination: none

    list_issue_events:
      method: GET
      path: /repos/{owner}/{repo}/issues/{issue_number}/events
      access: read
      description: "List events for an issue (labeled, assigned, closed, reopened, etc.)."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        issue_number: { type: integer, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    list_issue_assignees:
      method: GET
      path: /repos/{owner}/{repo}/assignees
      access: read
      description: "List available assignees for issues in a repository (users with push access)."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    # ── Issue Reactions ──────────────────────────────────────

    list_issue_reactions:
      method: GET
      path: /repos/{owner}/{repo}/issues/{issue_number}/reactions
      access: read
      description: "List reactions on an issue. Content: +1, -1, laugh, confused, heart, hooray, rocket, eyes."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        issue_number: { type: integer, in: path, required: true }
        content: { type: string, in: query }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    create_issue_reaction:
      method: POST
      path: /repos/{owner}/{repo}/issues/{issue_number}/reactions
      access: write
      description: "Create a reaction on an issue. Content: +1, -1, laugh, confused, heart, hooray, rocket, eyes."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        issue_number: { type: integer, in: path, required: true }
        content: { type: string, in: body, required: true }
      pagination: none

    create_issue_comment_reaction:
      method: POST
      path: /repos/{owner}/{repo}/issues/comments/{comment_id}/reactions
      access: write
      description: "Create a reaction on an issue comment."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        comment_id: { type: integer, in: path, required: true }
        content: { type: string, in: body, required: true }
      pagination: none

    # ── Pull Requests ─────────────────────────────────────────

    list_pulls:
      method: GET
      path: /repos/{owner}/{repo}/pulls
      access: read
      description: "List pull requests for a repository. State: open, closed, all."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        state: { type: string, in: query, default: "open" }
        sort: { type: string, in: query, default: "created" }
        direction: { type: string, in: query, default: "desc" }
        head: { type: string, in: query }
        base: { type: string, in: query }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_pull:
      method: GET
      path: /repos/{owner}/{repo}/pulls/{pull_number}
      access: read
      description: "Get a single pull request including diff stats, mergeable state, and review status."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        pull_number: { type: integer, in: path, required: true }
      pagination: none

    list_pull_files:
      method: GET
      path: /repos/{owner}/{repo}/pulls/{pull_number}/files
      access: read
      description: "List files changed in a pull request with patch diffs and stats."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        pull_number: { type: integer, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    list_pull_reviews:
      method: GET
      path: /repos/{owner}/{repo}/pulls/{pull_number}/reviews
      access: read
      description: "List reviews on a pull request (approved, changes_requested, commented)."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        pull_number: { type: integer, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    create_pull:
      method: POST
      path: /repos/{owner}/{repo}/pulls
      access: write
      description: "Create a new pull request. head is the branch with changes, base is the target branch (e.g. main). Set draft=true to create a draft PR."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        title: { type: string, in: body, required: true }
        head: { type: string, in: body, required: true }
        base: { type: string, in: body, required: true }
        body: { type: string, in: body }
        draft: { type: boolean, in: body }
        maintainer_can_modify: { type: boolean, in: body }
      pagination: none

    update_pull:
      method: PATCH
      path: /repos/{owner}/{repo}/pulls/{pull_number}
      access: write
      description: "Update a pull request. Set state to 'closed' to close it. Only include fields you want to change."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        pull_number: { type: integer, in: path, required: true }
        title: { type: string, in: body }
        body: { type: string, in: body }
        state: { type: string, in: body }
        base: { type: string, in: body }
        maintainer_can_modify: { type: boolean, in: body }
      pagination: none

    merge_pull:
      method: PUT
      path: /repos/{owner}/{repo}/pulls/{pull_number}/merge
      access: write
      description: "Merge a pull request. merge_method: merge, squash, or rebase. Optionally provide sha to ensure merging the expected head commit."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        pull_number: { type: integer, in: path, required: true }
        commit_title: { type: string, in: body }
        commit_message: { type: string, in: body }
        sha: { type: string, in: body }
        merge_method: { type: string, in: body }
      pagination: none

    list_pull_commits:
      method: GET
      path: /repos/{owner}/{repo}/pulls/{pull_number}/commits
      access: read
      description: "List commits on a pull request, ordered chronologically."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        pull_number: { type: integer, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    create_pull_review:
      method: POST
      path: /repos/{owner}/{repo}/pulls/{pull_number}/reviews
      access: write
      description: "Create a review on a pull request. event: APPROVE, REQUEST_CHANGES, or COMMENT. Body is the review summary."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        pull_number: { type: integer, in: path, required: true }
        body: { type: string, in: body }
        event: { type: string, in: body, required: true }
        comments: { type: array, in: body }
        commit_id: { type: string, in: body }
      pagination: none

    # ── PR Review Comments ───────────────────────────────────

    list_pull_review_comments:
      method: GET
      path: /repos/{owner}/{repo}/pulls/{pull_number}/comments
      access: read
      description: "List review comments on a pull request (inline code comments, not issue comments)."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        pull_number: { type: integer, in: path, required: true }
        sort: { type: string, in: query, default: "created" }
        direction: { type: string, in: query, default: "desc" }
        since: { type: string, in: query }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    create_pull_review_comment:
      method: POST
      path: /repos/{owner}/{repo}/pulls/{pull_number}/comments
      access: write
      description: "Create an inline review comment on a pull request. Specify path and line (or start_line + line for multi-line). side: LEFT or RIGHT for diff side."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        pull_number: { type: integer, in: path, required: true }
        body: { type: string, in: body, required: true }
        commit_id: { type: string, in: body, required: true }
        path: { type: string, in: body, required: true }
        line: { type: integer, in: body }
        side: { type: string, in: body }
        start_line: { type: integer, in: body }
        start_side: { type: string, in: body }
        subject_type: { type: string, in: body }
      pagination: none

    # ── PR Requested Reviewers ───────────────────────────────

    list_requested_reviewers:
      method: GET
      path: /repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers
      access: read
      description: "List users and teams requested to review a pull request."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        pull_number: { type: integer, in: path, required: true }
      pagination: none

    request_reviewers:
      method: POST
      path: /repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers
      access: write
      description: "Request review from users or teams on a pull request."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        pull_number: { type: integer, in: path, required: true }
        reviewers: { type: array, in: body }
        team_reviewers: { type: array, in: body }
      pagination: none

    remove_requested_reviewers:
      method: DELETE
      path: /repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers
      access: dangerous
      description: "Remove requested reviewers from a pull request."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        pull_number: { type: integer, in: path, required: true }
        reviewers: { type: array, in: body }
        team_reviewers: { type: array, in: body }
      pagination: none

    # ── Commits & Branches ────────────────────────────────────

    list_commits:
      method: GET
      path: /repos/{owner}/{repo}/commits
      access: read
      description: "List commits on a repository. Filter by sha (branch), path, author, or date range."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        sha: { type: string, in: query }
        path: { type: string, in: query }
        author: { type: string, in: query }
        committer: { type: string, in: query }
        since: { type: string, in: query }
        until: { type: string, in: query }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_commit:
      method: GET
      path: /repos/{owner}/{repo}/commits/{ref}
      access: read
      description: "Get a single commit by SHA or ref, including full diff stats and file changes."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        ref: { type: string, in: path, required: true }
      pagination: none

    compare_commits:
      method: GET
      path: /repos/{owner}/{repo}/compare/{basehead}
      access: read
      description: "Compare two commits. basehead format: 'base...head' (e.g. 'main...feature-branch'). Returns diff stats, commits, and file changes."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        basehead: { type: string, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    list_branches:
      method: GET
      path: /repos/{owner}/{repo}/branches
      access: read
      description: "List branches for a repository."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        protected: { type: boolean, in: query }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_branch:
      method: GET
      path: /repos/{owner}/{repo}/branches/{branch}
      access: read
      description: "Get a single branch including its latest commit SHA and protection status."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        branch: { type: string, in: path, required: true }
      pagination: none

    # ── Branch Protection ────────────────────────────────────

    get_branch_protection:
      method: GET
      path: /repos/{owner}/{repo}/branches/{branch}/protection
      access: read
      description: "Get branch protection rules for a branch."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        branch: { type: string, in: path, required: true }
      pagination: none

    update_branch_protection:
      method: PUT
      path: /repos/{owner}/{repo}/branches/{branch}/protection
      access: admin
      description: "Update branch protection rules. Set required_status_checks, enforce_admins, required_pull_request_reviews, and restrictions."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        branch: { type: string, in: path, required: true }
        required_status_checks: { type: object, in: body, required: true }
        enforce_admins: { type: boolean, in: body, required: true }
        required_pull_request_reviews: { type: object, in: body, required: true }
        restrictions: { type: object, in: body, required: true }
        required_linear_history: { type: boolean, in: body }
        allow_force_pushes: { type: boolean, in: body }
        allow_deletions: { type: boolean, in: body }
        required_conversation_resolution: { type: boolean, in: body }
      pagination: none

    delete_branch_protection:
      method: DELETE
      path: /repos/{owner}/{repo}/branches/{branch}/protection
      access: dangerous
      description: "Delete branch protection rules for a branch."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        branch: { type: string, in: path, required: true }
      pagination: none

    # ── Git Refs ─────────────────────────────────────────────

    create_ref:
      method: POST
      path: /repos/{owner}/{repo}/git/refs
      access: write
      description: "Create a git reference (branch or tag). For branches use ref='refs/heads/branch-name'. sha is the commit to point to."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        ref: { type: string, in: body, required: true }
        sha: { type: string, in: body, required: true }
      pagination: none

    update_ref:
      method: PATCH
      path: /repos/{owner}/{repo}/git/refs/{ref}
      access: write
      description: "Update a git reference to point to a new SHA. ref is without 'refs/' prefix (e.g. 'heads/main'). Set force=true to do a non-fast-forward update."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        ref: { type: string, in: path, required: true }
        sha: { type: string, in: body, required: true }
        force: { type: boolean, in: body }
      pagination: none

    delete_ref:
      method: DELETE
      path: /repos/{owner}/{repo}/git/refs/{ref}
      access: dangerous
      description: "Delete a git reference. For branches use ref='heads/branch-name' (without refs/ prefix). For tags use ref='tags/tag-name'."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        ref: { type: string, in: path, required: true }
      pagination: none

    # ── Git Objects ──────────────────────────────────────────

    get_tree:
      method: GET
      path: /repos/{owner}/{repo}/git/trees/{tree_sha}
      access: read
      description: "Get a git tree by SHA. Set recursive=true to get the full tree (all nested directories). Returns tree entries with path, mode, type, sha."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        tree_sha: { type: string, in: path, required: true }
        recursive: { type: string, in: query }
      pagination: none

    create_tree:
      method: POST
      path: /repos/{owner}/{repo}/git/trees
      access: write
      description: "Create a git tree. Each tree entry has path, mode (100644=file, 100755=executable, 040000=directory, 160000=submodule, 120000=symlink), type (blob/tree/commit), and sha or content."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        tree: { type: array, in: body, required: true }
        base_tree: { type: string, in: body }
      pagination: none

    create_blob:
      method: POST
      path: /repos/{owner}/{repo}/git/blobs
      access: write
      description: "Create a git blob. Content can be utf-8 or base64 encoded (set encoding accordingly)."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        content: { type: string, in: body, required: true }
        encoding: { type: string, in: body, default: "utf-8" }
      pagination: none

    create_git_commit:
      method: POST
      path: /repos/{owner}/{repo}/git/commits
      access: write
      description: "Create a git commit object. tree is the SHA of the tree, parents is an array of parent commit SHAs. Use with create_tree and update_ref for programmatic commits."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        message: { type: string, in: body, required: true }
        tree: { type: string, in: body, required: true }
        parents: { type: array, in: body, required: true }
        author: { type: object, in: body }
        committer: { type: object, in: body }
      pagination: none

    create_tag_object:
      method: POST
      path: /repos/{owner}/{repo}/git/tags
      access: write
      description: "Create an annotated tag object. object is the SHA to tag. type is the object type (commit, tree, blob). Use create_ref to create the tag ref afterwards."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        tag: { type: string, in: body, required: true }
        message: { type: string, in: body, required: true }
        object: { type: string, in: body, required: true }
        type: { type: string, in: body, required: true }
        tagger: { type: object, in: body }
      pagination: none

    # ── File Contents ─────────────────────────────────────────

    get_content:
      method: GET
      path: /repos/{owner}/{repo}/contents/{path}
      access: read
      description: "Get file or directory contents. Files are base64 encoded. Directories return a listing. Use ref for a specific branch/tag/SHA."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        path: { type: string, in: path, required: true }
        ref: { type: string, in: query }
      pagination: none

    create_or_update_file:
      method: PUT
      path: /repos/{owner}/{repo}/contents/{path}
      access: write
      description: "Create or update a file. Content must be base64 encoded. To update an existing file, provide the current blob sha (from get_content). Creates a commit."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        path: { type: string, in: path, required: true }
        message: { type: string, in: body, required: true }
        content: { type: string, in: body, required: true }
        sha: { type: string, in: body }
        branch: { type: string, in: body }
        committer: { type: object, in: body }
        author: { type: object, in: body }
      pagination: none

    delete_file:
      method: DELETE
      path: /repos/{owner}/{repo}/contents/{path}
      access: dangerous
      description: "Delete a file from the repository. Requires the current blob sha (from get_content). Creates a commit."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        path: { type: string, in: path, required: true }
        message: { type: string, in: body, required: true }
        sha: { type: string, in: body, required: true }
        branch: { type: string, in: body }
      pagination: none

    # ── Search ────────────────────────────────────────────────

    search_code:
      method: GET
      path: /search/code
      access: read
      description: "Search for code across repositories. Query syntax: 'keyword repo:owner/repo language:go path:internal'. Results include file path, repo, and text matches."
      params:
        q: { type: string, in: query, required: true }
        sort: { type: string, in: query }
        order: { type: string, in: query, default: "desc" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    search_issues:
      method: GET
      path: /search/issues
      access: read
      description: "Search issues and PRs across repositories. Query syntax: 'bug repo:owner/repo is:open label:bug'. Use is:pr or is:issue to filter."
      params:
        q: { type: string, in: query, required: true }
        sort: { type: string, in: query }
        order: { type: string, in: query, default: "desc" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    search_repos:
      method: GET
      path: /search/repositories
      access: read
      description: "Search repositories. Query syntax: 'keyword language:go stars:>100 topic:cli'. Sort: stars, forks, help-wanted-issues, updated."
      params:
        q: { type: string, in: query, required: true }
        sort: { type: string, in: query }
        order: { type: string, in: query, default: "desc" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    search_users:
      method: GET
      path: /search/users
      access: read
      description: "Search users. Query syntax: 'username type:user location:germany language:go followers:>100'."
      params:
        q: { type: string, in: query, required: true }
        sort: { type: string, in: query }
        order: { type: string, in: query, default: "desc" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    search_commits:
      method: GET
      path: /search/commits
      access: read
      description: "Search commits. Query syntax: 'fix repo:owner/repo author:username committer-date:>2026-01-01'. Sort: author-date, committer-date."
      params:
        q: { type: string, in: query, required: true }
        sort: { type: string, in: query }
        order: { type: string, in: query, default: "desc" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    search_topics:
      method: GET
      path: /search/topics
      access: read
      description: "Search topics by name. Returns matching topic names with descriptions and related info."
      params:
        q: { type: string, in: query, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    # ── Releases ──────────────────────────────────────────────

    list_releases:
      method: GET
      path: /repos/{owner}/{repo}/releases
      access: read
      description: "List releases for a repository, newest first."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_latest_release:
      method: GET
      path: /repos/{owner}/{repo}/releases/latest
      access: read
      description: "Get the latest published release (not draft/prerelease)."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
      pagination: none

    get_release:
      method: GET
      path: /repos/{owner}/{repo}/releases/{release_id}
      access: read
      description: "Get a single release by its numeric ID."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        release_id: { type: integer, in: path, required: true }
      pagination: none

    get_release_by_tag:
      method: GET
      path: /repos/{owner}/{repo}/releases/tags/{tag}
      access: read
      description: "Get a release by tag name (e.g. 'v1.0.0')."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        tag: { type: string, in: path, required: true }
      pagination: none

    create_release:
      method: POST
      path: /repos/{owner}/{repo}/releases
      access: write
      description: "Create a release. tag_name is required. If the tag does not exist, target_commitish (branch or SHA) is used to create it. Set draft=true for unpublished releases."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        tag_name: { type: string, in: body, required: true }
        target_commitish: { type: string, in: body }
        name: { type: string, in: body }
        body: { type: string, in: body }
        draft: { type: boolean, in: body }
        prerelease: { type: boolean, in: body }
        generate_release_notes: { type: boolean, in: body }
      pagination: none

    update_release:
      method: PATCH
      path: /repos/{owner}/{repo}/releases/{release_id}
      access: write
      description: "Update a release. Only include fields you want to change."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        release_id: { type: integer, in: path, required: true }
        tag_name: { type: string, in: body }
        target_commitish: { type: string, in: body }
        name: { type: string, in: body }
        body: { type: string, in: body }
        draft: { type: boolean, in: body }
        prerelease: { type: boolean, in: body }
      pagination: none

    delete_release:
      method: DELETE
      path: /repos/{owner}/{repo}/releases/{release_id}
      access: dangerous
      description: "Delete a release. Does not delete the associated git tag."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        release_id: { type: integer, in: path, required: true }
      pagination: none

    list_release_assets:
      method: GET
      path: /repos/{owner}/{repo}/releases/{release_id}/assets
      access: read
      description: "List assets (attached files) for a release."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        release_id: { type: integer, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    delete_release_asset:
      method: DELETE
      path: /repos/{owner}/{repo}/releases/assets/{asset_id}
      access: dangerous
      description: "Delete a release asset."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        asset_id: { type: integer, in: path, required: true }
      pagination: none

    # ── Actions (CI/CD) ───────────────────────────────────────

    list_workflows:
      method: GET
      path: /repos/{owner}/{repo}/actions/workflows
      access: read
      description: "List all workflows in a repository. Returns workflow ID, name, path, and state."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_workflow:
      method: GET
      path: /repos/{owner}/{repo}/actions/workflows/{workflow_id}
      access: read
      description: "Get a specific workflow by ID or filename (e.g. 'ci.yml')."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        workflow_id: { type: string, in: path, required: true }
      pagination: none

    dispatch_workflow:
      method: POST
      path: /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches
      access: write
      description: "Trigger a workflow_dispatch event. ref is the branch/tag to run on. inputs is a map of workflow input values."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        workflow_id: { type: string, in: path, required: true }
        ref: { type: string, in: body, required: true }
        inputs: { type: object, in: body }
      pagination: none

    list_workflow_runs:
      method: GET
      path: /repos/{owner}/{repo}/actions/runs
      access: read
      description: "List workflow runs for a repository. Filter by branch, status (queued, in_progress, completed), or event (push, pull_request)."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        branch: { type: string, in: query }
        status: { type: string, in: query }
        event: { type: string, in: query }
        actor: { type: string, in: query }
        workflow_id: { type: integer, in: query }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_workflow_run:
      method: GET
      path: /repos/{owner}/{repo}/actions/runs/{run_id}
      access: read
      description: "Get a single workflow run including status, conclusion, and timing."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        run_id: { type: integer, in: path, required: true }
      pagination: none

    list_workflow_run_jobs:
      method: GET
      path: /repos/{owner}/{repo}/actions/runs/{run_id}/jobs
      access: read
      description: "List jobs for a workflow run. Filter by latest attempt or all attempts."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        run_id: { type: integer, in: path, required: true }
        filter: { type: string, in: query, default: "latest" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_job:
      method: GET
      path: /repos/{owner}/{repo}/actions/jobs/{job_id}
      access: read
      description: "Get a single workflow job by ID, including steps with status and timing."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        job_id: { type: integer, in: path, required: true }
      pagination: none

    get_job_log:
      method: GET
      path: /repos/{owner}/{repo}/actions/jobs/{job_id}/logs
      access: read
      description: "Download the log output of a workflow job. Returns plain text with timestamps. The API responds with a 302 redirect to a temporary download URL which is followed automatically."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        job_id: { type: integer, in: path, required: true }
      pagination: none

    cancel_workflow_run:
      method: POST
      path: /repos/{owner}/{repo}/actions/runs/{run_id}/cancel
      access: write
      description: "Cancel a workflow run that is in progress or queued."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        run_id: { type: integer, in: path, required: true }
      pagination: none

    rerun_workflow:
      method: POST
      path: /repos/{owner}/{repo}/actions/runs/{run_id}/rerun
      access: write
      description: "Re-run an entire workflow run. Only works for completed runs."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        run_id: { type: integer, in: path, required: true }
      pagination: none

    rerun_failed_jobs:
      method: POST
      path: /repos/{owner}/{repo}/actions/runs/{run_id}/rerun-failed-jobs
      access: write
      description: "Re-run only the failed jobs in a workflow run."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        run_id: { type: integer, in: path, required: true }
      pagination: none

    delete_workflow_run:
      method: DELETE
      path: /repos/{owner}/{repo}/actions/runs/{run_id}
      access: dangerous
      description: "Delete a workflow run. The run must be completed."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        run_id: { type: integer, in: path, required: true }
      pagination: none

    list_workflow_run_artifacts:
      method: GET
      path: /repos/{owner}/{repo}/actions/runs/{run_id}/artifacts
      access: read
      description: "List artifacts for a workflow run. Artifacts are files produced during a run (logs, binaries, test results)."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        run_id: { type: integer, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    list_repo_secrets:
      method: GET
      path: /repos/{owner}/{repo}/actions/secrets
      access: read
      description: "List repository secrets for GitHub Actions. Only returns secret names, not values."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_repo_public_key:
      method: GET
      path: /repos/{owner}/{repo}/actions/secrets/public-key
      access: read
      description: "Get the public key for encrypting secrets. Required before creating or updating a secret."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
      pagination: none

    create_or_update_repo_secret:
      method: PUT
      path: /repos/{owner}/{repo}/actions/secrets/{secret_name}
      access: admin
      description: "Create or update a repository secret. The encrypted_value must be encrypted with the repo's public key (from get_repo_public_key) using libsodium."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        secret_name: { type: string, in: path, required: true }
        encrypted_value: { type: string, in: body, required: true }
        key_id: { type: string, in: body, required: true }
      pagination: none

    delete_repo_secret:
      method: DELETE
      path: /repos/{owner}/{repo}/actions/secrets/{secret_name}
      access: dangerous
      description: "Delete a repository secret."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        secret_name: { type: string, in: path, required: true }
      pagination: none

    list_repo_variables:
      method: GET
      path: /repos/{owner}/{repo}/actions/variables
      access: read
      description: "List repository variables for GitHub Actions."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    create_repo_variable:
      method: POST
      path: /repos/{owner}/{repo}/actions/variables
      access: write
      description: "Create a repository variable for GitHub Actions."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        name: { type: string, in: body, required: true }
        value: { type: string, in: body, required: true }
      pagination: none

    update_repo_variable:
      method: PATCH
      path: /repos/{owner}/{repo}/actions/variables/{name}
      access: write
      description: "Update a repository variable."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        name: { type: string, in: path, required: true }
        value: { type: string, in: body, required: true }
      pagination: none

    delete_repo_variable:
      method: DELETE
      path: /repos/{owner}/{repo}/actions/variables/{name}
      access: dangerous
      description: "Delete a repository variable."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        name: { type: string, in: path, required: true }
      pagination: none

    # ── Webhooks ──────────────────────────────────────────────

    list_repo_webhooks:
      method: GET
      path: /repos/{owner}/{repo}/hooks
      access: read
      description: "List webhooks for a repository."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_repo_webhook:
      method: GET
      path: /repos/{owner}/{repo}/hooks/{hook_id}
      access: read
      description: "Get a single webhook by ID."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        hook_id: { type: integer, in: path, required: true }
      pagination: none

    create_repo_webhook:
      method: POST
      path: /repos/{owner}/{repo}/hooks
      access: admin
      description: "Create a webhook for a repository. config.url is the payload URL. events is an array of event names (e.g. ['push', 'pull_request'])."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        name: { type: string, in: body, default: "web" }
        config: { type: object, in: body, required: true }
        events: { type: array, in: body }
        active: { type: boolean, in: body, default: true }
      pagination: none

    update_repo_webhook:
      method: PATCH
      path: /repos/{owner}/{repo}/hooks/{hook_id}
      access: admin
      description: "Update a webhook. Only include fields you want to change."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        hook_id: { type: integer, in: path, required: true }
        config: { type: object, in: body }
        events: { type: array, in: body }
        active: { type: boolean, in: body }
      pagination: none

    delete_repo_webhook:
      method: DELETE
      path: /repos/{owner}/{repo}/hooks/{hook_id}
      access: dangerous
      description: "Delete a webhook from a repository."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        hook_id: { type: integer, in: path, required: true }
      pagination: none

    ping_repo_webhook:
      method: POST
      path: /repos/{owner}/{repo}/hooks/{hook_id}/pings
      access: write
      description: "Send a ping event to a webhook to test its configuration."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        hook_id: { type: integer, in: path, required: true }
      pagination: none

    # ── Deployments ──────────────────────────────────────────

    list_deployments:
      method: GET
      path: /repos/{owner}/{repo}/deployments
      access: read
      description: "List deployments for a repository. Filter by sha, ref, task, or environment."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        sha: { type: string, in: query }
        ref: { type: string, in: query }
        task: { type: string, in: query }
        environment: { type: string, in: query }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_deployment:
      method: GET
      path: /repos/{owner}/{repo}/deployments/{deployment_id}
      access: read
      description: "Get a single deployment."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        deployment_id: { type: integer, in: path, required: true }
      pagination: none

    create_deployment:
      method: POST
      path: /repos/{owner}/{repo}/deployments
      access: write
      description: "Create a deployment. ref is the branch/tag/SHA to deploy. environment defaults to 'production'."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        ref: { type: string, in: body, required: true }
        task: { type: string, in: body, default: "deploy" }
        auto_merge: { type: boolean, in: body }
        required_contexts: { type: array, in: body }
        payload: { type: object, in: body }
        environment: { type: string, in: body, default: "production" }
        description: { type: string, in: body }
        transient_environment: { type: boolean, in: body }
        production_environment: { type: boolean, in: body }
      pagination: none

    delete_deployment:
      method: DELETE
      path: /repos/{owner}/{repo}/deployments/{deployment_id}
      access: dangerous
      description: "Delete a deployment. Only inactive deployments can be deleted."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        deployment_id: { type: integer, in: path, required: true }
      pagination: none

    list_deployment_statuses:
      method: GET
      path: /repos/{owner}/{repo}/deployments/{deployment_id}/statuses
      access: read
      description: "List statuses for a deployment. States: error, failure, inactive, in_progress, queued, pending, success."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        deployment_id: { type: integer, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    create_deployment_status:
      method: POST
      path: /repos/{owner}/{repo}/deployments/{deployment_id}/statuses
      access: write
      description: "Create a deployment status. state: error, failure, inactive, in_progress, queued, pending, success."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        deployment_id: { type: integer, in: path, required: true }
        state: { type: string, in: body, required: true }
        target_url: { type: string, in: body }
        log_url: { type: string, in: body }
        description: { type: string, in: body }
        environment: { type: string, in: body }
        environment_url: { type: string, in: body }
        auto_inactive: { type: boolean, in: body }
      pagination: none

    # ── Environments ─────────────────────────────────────────

    list_environments:
      method: GET
      path: /repos/{owner}/{repo}/environments
      access: read
      description: "List deployment environments for a repository."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_environment:
      method: GET
      path: /repos/{owner}/{repo}/environments/{environment_name}
      access: read
      description: "Get a deployment environment by name."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        environment_name: { type: string, in: path, required: true }
      pagination: none

    create_or_update_environment:
      method: PUT
      path: /repos/{owner}/{repo}/environments/{environment_name}
      access: admin
      description: "Create or update a deployment environment. Configure wait_timer (minutes), reviewers, and deployment_branch_policy."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        environment_name: { type: string, in: path, required: true }
        wait_timer: { type: integer, in: body }
        reviewers: { type: array, in: body }
        deployment_branch_policy: { type: object, in: body }
      pagination: none

    delete_environment:
      method: DELETE
      path: /repos/{owner}/{repo}/environments/{environment_name}
      access: dangerous
      description: "Delete a deployment environment."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        environment_name: { type: string, in: path, required: true }
      pagination: none

    # ── Labels ───────────────────────────────────────────────

    list_labels:
      method: GET
      path: /repos/{owner}/{repo}/labels
      access: read
      description: "List all labels for a repository."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_label:
      method: GET
      path: /repos/{owner}/{repo}/labels/{name}
      access: read
      description: "Get a single label by name."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        name: { type: string, in: path, required: true }
      pagination: none

    create_label:
      method: POST
      path: /repos/{owner}/{repo}/labels
      access: write
      description: "Create a label. Color is a 6-character hex code without '#' prefix (e.g. 'ff0000' for red)."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        name: { type: string, in: body, required: true }
        color: { type: string, in: body, required: true }
        description: { type: string, in: body }
      pagination: none

    update_label:
      method: PATCH
      path: /repos/{owner}/{repo}/labels/{name}
      access: write
      description: "Update a label. Only include fields you want to change. Use new_name to rename."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        name: { type: string, in: path, required: true }
        new_name: { type: string, in: body }
        color: { type: string, in: body }
        description: { type: string, in: body }
      pagination: none

    delete_label:
      method: DELETE
      path: /repos/{owner}/{repo}/labels/{name}
      access: dangerous
      description: "Delete a label from the repository."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        name: { type: string, in: path, required: true }
      pagination: none

    # ── Milestones ───────────────────────────────────────────

    list_milestones:
      method: GET
      path: /repos/{owner}/{repo}/milestones
      access: read
      description: "List milestones for a repository. State: open, closed, all."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        state: { type: string, in: query, default: "open" }
        sort: { type: string, in: query, default: "due_on" }
        direction: { type: string, in: query, default: "asc" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_milestone:
      method: GET
      path: /repos/{owner}/{repo}/milestones/{milestone_number}
      access: read
      description: "Get a single milestone by its number, including open/closed issue counts."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        milestone_number: { type: integer, in: path, required: true }
      pagination: none

    create_milestone:
      method: POST
      path: /repos/{owner}/{repo}/milestones
      access: write
      description: "Create a milestone. due_on is an ISO 8601 timestamp (e.g. '2026-04-01T00:00:00Z')."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        title: { type: string, in: body, required: true }
        description: { type: string, in: body }
        due_on: { type: string, in: body }
        state: { type: string, in: body, default: "open" }
      pagination: none

    update_milestone:
      method: PATCH
      path: /repos/{owner}/{repo}/milestones/{milestone_number}
      access: write
      description: "Update a milestone. Set state to 'closed' to close it. Only include fields you want to change."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        milestone_number: { type: integer, in: path, required: true }
        title: { type: string, in: body }
        description: { type: string, in: body }
        due_on: { type: string, in: body }
        state: { type: string, in: body }
      pagination: none

    delete_milestone:
      method: DELETE
      path: /repos/{owner}/{repo}/milestones/{milestone_number}
      access: dangerous
      description: "Delete a milestone."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        milestone_number: { type: integer, in: path, required: true }
      pagination: none

    # ── Users ────────────────────────────────────────────────

    get_authenticated_user:
      method: GET
      path: /user
      access: read
      description: "Get the currently authenticated user's profile including login, name, email, and bio."
      params: {}
      pagination: none

    get_user:
      method: GET
      path: /users/{username}
      access: read
      description: "Get a public user profile by username."
      params:
        username: { type: string, in: path, required: true }
      pagination: none

    list_followers:
      method: GET
      path: /users/{username}/followers
      access: read
      description: "List followers of a user."
      params:
        username: { type: string, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    list_following:
      method: GET
      path: /users/{username}/following
      access: read
      description: "List users that a user is following."
      params:
        username: { type: string, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    # ── Tags ─────────────────────────────────────────────────

    list_tags:
      method: GET
      path: /repos/{owner}/{repo}/tags
      access: read
      description: "List tags for a repository, newest first. Each tag includes name and commit SHA."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    # ── Starring ─────────────────────────────────────────────

    list_stargazers:
      method: GET
      path: /repos/{owner}/{repo}/stargazers
      access: read
      description: "List users who have starred a repository."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    list_starred_repos:
      method: GET
      path: /user/starred
      access: read
      description: "List repositories starred by the authenticated user."
      params:
        sort: { type: string, in: query, default: "created" }
        direction: { type: string, in: query, default: "desc" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    check_starred:
      method: GET
      path: /user/starred/{owner}/{repo}
      access: read
      description: "Check if the authenticated user has starred a repo. Returns 204 if yes, 404 if no."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
      pagination: none

    star_repo:
      method: PUT
      path: /user/starred/{owner}/{repo}
      access: write
      description: "Star a repository for the authenticated user."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
      pagination: none

    unstar_repo:
      method: DELETE
      path: /user/starred/{owner}/{repo}
      access: dangerous
      description: "Unstar a repository for the authenticated user."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
      pagination: none

    # ── Watching ──────────────────────────────────────────────

    list_watchers:
      method: GET
      path: /repos/{owner}/{repo}/subscribers
      access: read
      description: "List users watching (subscribed to) a repository."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_repo_subscription:
      method: GET
      path: /repos/{owner}/{repo}/subscription
      access: read
      description: "Get the authenticated user's subscription (watch status) for a repository."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
      pagination: none

    watch_repo:
      method: PUT
      path: /repos/{owner}/{repo}/subscription
      access: write
      description: "Watch a repository. Set subscribed=true to receive notifications, ignored=true to mute."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        subscribed: { type: boolean, in: body }
        ignored: { type: boolean, in: body }
      pagination: none

    unwatch_repo:
      method: DELETE
      path: /repos/{owner}/{repo}/subscription
      access: dangerous
      description: "Stop watching a repository."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
      pagination: none

    # ── Gists ────────────────────────────────────────────────

    list_gists:
      method: GET
      path: /gists
      access: read
      description: "List gists for the authenticated user."
      params:
        since: { type: string, in: query }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    list_public_gists:
      method: GET
      path: /gists/public
      access: read
      description: "List public gists, newest first."
      params:
        since: { type: string, in: query }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    list_starred_gists:
      method: GET
      path: /gists/starred
      access: read
      description: "List gists starred by the authenticated user."
      params:
        since: { type: string, in: query }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_gist:
      method: GET
      path: /gists/{gist_id}
      access: read
      description: "Get a single gist by ID, including all files and their content."
      params:
        gist_id: { type: string, in: path, required: true }
      pagination: none

    create_gist:
      method: POST
      path: /gists
      access: write
      description: "Create a gist. files is a map of filename to {content: string}. Set public=true for a public gist."
      params:
        description: { type: string, in: body }
        files: { type: object, in: body, required: true }
        public: { type: boolean, in: body, default: false }
      pagination: none

    update_gist:
      method: PATCH
      path: /gists/{gist_id}
      access: write
      description: "Update a gist. To delete a file, set its value to null. To rename, delete the old name and create a new one."
      params:
        gist_id: { type: string, in: path, required: true }
        description: { type: string, in: body }
        files: { type: object, in: body }
      pagination: none

    delete_gist:
      method: DELETE
      path: /gists/{gist_id}
      access: dangerous
      description: "Delete a gist."
      params:
        gist_id: { type: string, in: path, required: true }
      pagination: none

    # ── Notifications ────────────────────────────────────────

    list_notifications:
      method: GET
      path: /notifications
      access: read
      description: "List notifications for the authenticated user. Set all=true to include read notifications."
      params:
        all: { type: boolean, in: query, default: false }
        participating: { type: boolean, in: query }
        since: { type: string, in: query }
        before: { type: string, in: query }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    mark_notifications_read:
      method: PUT
      path: /notifications
      access: write
      description: "Mark all notifications as read. Optionally provide last_read_at (ISO 8601) to only mark notifications before that time."
      params:
        last_read_at: { type: string, in: body }
      pagination: none

    list_repo_notifications:
      method: GET
      path: /repos/{owner}/{repo}/notifications
      access: read
      description: "List notifications for a repository."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        all: { type: boolean, in: query, default: false }
        participating: { type: boolean, in: query }
        since: { type: string, in: query }
        before: { type: string, in: query }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    mark_repo_notifications_read:
      method: PUT
      path: /repos/{owner}/{repo}/notifications
      access: write
      description: "Mark all notifications in a repository as read."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        last_read_at: { type: string, in: body }
      pagination: none

    get_notification_thread:
      method: GET
      path: /notifications/threads/{thread_id}
      access: read
      description: "Get a single notification thread."
      params:
        thread_id: { type: integer, in: path, required: true }
      pagination: none

    mark_thread_read:
      method: PATCH
      path: /notifications/threads/{thread_id}
      access: write
      description: "Mark a notification thread as read."
      params:
        thread_id: { type: integer, in: path, required: true }
      pagination: none

    # ── Check Runs & Commit Status ───────────────────────────

    list_check_runs_for_ref:
      method: GET
      path: /repos/{owner}/{repo}/commits/{ref}/check-runs
      access: read
      description: "List check runs for a commit SHA, branch name, or tag. Filter by check_name, status, or filter (latest, all)."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        ref: { type: string, in: path, required: true }
        check_name: { type: string, in: query }
        status: { type: string, in: query }
        filter: { type: string, in: query, default: "latest" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    list_check_run_annotations:
      method: GET
      path: /repos/{owner}/{repo}/check-runs/{check_run_id}/annotations
      access: read
      description: "List annotations for a check run. Returns inline lint/test errors with file path, line number, and message. Use this to inspect CI failure details programmatically."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        check_run_id: { type: integer, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    list_check_suites_for_ref:
      method: GET
      path: /repos/{owner}/{repo}/commits/{ref}/check-suites
      access: read
      description: "List check suites for a commit SHA, branch name, or tag."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        ref: { type: string, in: path, required: true }
        app_id: { type: integer, in: query }
        check_name: { type: string, in: query }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_combined_status:
      method: GET
      path: /repos/{owner}/{repo}/commits/{ref}/status
      access: read
      description: "Get the combined status for a commit (aggregates all status checks). Returns state: success, failure, pending."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        ref: { type: string, in: path, required: true }
      pagination: none

    list_commit_statuses:
      method: GET
      path: /repos/{owner}/{repo}/commits/{ref}/statuses
      access: read
      description: "List individual status checks for a commit ref."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        ref: { type: string, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    create_commit_status:
      method: POST
      path: /repos/{owner}/{repo}/statuses/{sha}
      access: write
      description: "Create a commit status. state: error, failure, pending, success. Provide target_url for linking to CI details."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        sha: { type: string, in: path, required: true }
        state: { type: string, in: body, required: true }
        target_url: { type: string, in: body }
        description: { type: string, in: body }
        context: { type: string, in: body, default: "default" }
      pagination: none

    # ── Pages ────────────────────────────────────────────────

    get_pages:
      method: GET
      path: /repos/{owner}/{repo}/pages
      access: read
      description: "Get GitHub Pages configuration for a repository."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
      pagination: none

    create_pages_site:
      method: POST
      path: /repos/{owner}/{repo}/pages
      access: admin
      description: "Enable GitHub Pages for a repository. source.branch is the branch to publish from, source.path is '/' or '/docs'."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        source: { type: object, in: body, required: true }
        build_type: { type: string, in: body }
      pagination: none

    update_pages_info:
      method: PUT
      path: /repos/{owner}/{repo}/pages
      access: admin
      description: "Update GitHub Pages configuration."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        source: { type: object, in: body }
        cname: { type: string, in: body }
        build_type: { type: string, in: body }
      pagination: none

    delete_pages_site:
      method: DELETE
      path: /repos/{owner}/{repo}/pages
      access: dangerous
      description: "Disable GitHub Pages for a repository."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
      pagination: none

    list_pages_builds:
      method: GET
      path: /repos/{owner}/{repo}/pages/builds
      access: read
      description: "List GitHub Pages builds."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    # ── Code Scanning & Security ─────────────────────────────

    list_code_scanning_alerts:
      method: GET
      path: /repos/{owner}/{repo}/code-scanning/alerts
      access: read
      description: "List code scanning alerts for a repository. State: open, closed, dismissed, fixed."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        state: { type: string, in: query }
        severity: { type: string, in: query }
        tool_name: { type: string, in: query }
        ref: { type: string, in: query }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_code_scanning_alert:
      method: GET
      path: /repos/{owner}/{repo}/code-scanning/alerts/{alert_number}
      access: read
      description: "Get a single code scanning alert."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        alert_number: { type: integer, in: path, required: true }
      pagination: none

    update_code_scanning_alert:
      method: PATCH
      path: /repos/{owner}/{repo}/code-scanning/alerts/{alert_number}
      access: write
      description: "Update a code scanning alert. Set state to 'dismissed' with a dismissed_reason, or 'open' to reopen."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        alert_number: { type: integer, in: path, required: true }
        state: { type: string, in: body, required: true }
        dismissed_reason: { type: string, in: body }
        dismissed_comment: { type: string, in: body }
      pagination: none

    list_dependabot_alerts:
      method: GET
      path: /repos/{owner}/{repo}/dependabot/alerts
      access: read
      description: "List Dependabot alerts for a repository. State: auto_dismissed, dismissed, fixed, open."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        state: { type: string, in: query }
        severity: { type: string, in: query }
        ecosystem: { type: string, in: query }
        package: { type: string, in: query }
        scope: { type: string, in: query }
        sort: { type: string, in: query, default: "created" }
        direction: { type: string, in: query, default: "desc" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_dependabot_alert:
      method: GET
      path: /repos/{owner}/{repo}/dependabot/alerts/{alert_number}
      access: read
      description: "Get a single Dependabot alert."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        alert_number: { type: integer, in: path, required: true }
      pagination: none

    update_dependabot_alert:
      method: PATCH
      path: /repos/{owner}/{repo}/dependabot/alerts/{alert_number}
      access: write
      description: "Update a Dependabot alert. Set state to 'dismissed' with a dismissed_reason, or 'open' to reopen."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        alert_number: { type: integer, in: path, required: true }
        state: { type: string, in: body, required: true }
        dismissed_reason: { type: string, in: body }
        dismissed_comment: { type: string, in: body }
      pagination: none

    list_secret_scanning_alerts:
      method: GET
      path: /repos/{owner}/{repo}/secret-scanning/alerts
      access: read
      description: "List secret scanning alerts for a repository. State: open, resolved."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        state: { type: string, in: query }
        secret_type: { type: string, in: query }
        resolution: { type: string, in: query }
        sort: { type: string, in: query, default: "created" }
        direction: { type: string, in: query, default: "desc" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_secret_scanning_alert:
      method: GET
      path: /repos/{owner}/{repo}/secret-scanning/alerts/{alert_number}
      access: read
      description: "Get a single secret scanning alert."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        alert_number: { type: integer, in: path, required: true }
      pagination: none

    update_secret_scanning_alert:
      method: PATCH
      path: /repos/{owner}/{repo}/secret-scanning/alerts/{alert_number}
      access: write
      description: "Update a secret scanning alert. Set state to 'resolved' with a resolution (false_positive, wont_fix, revoked, used_in_tests, pattern_edited, pattern_deleted)."
      params:
        owner: { type: string, in: path, required: true }
        repo: { type: string, in: path, required: true }
        alert_number: { type: integer, in: path, required: true }
        state: { type: string, in: body, required: true }
        resolution: { type: string, in: body }
        resolution_comment: { type: string, in: body }
      pagination: none

    # ── Packages (Organization) ───────────────────────────────────

    list_org_packages:
      method: GET
      path: /orgs/{org}/packages
      access: read
      description: "List packages in an organization. package_type is required: npm, maven, rubygems, docker, nuget, container."
      params:
        org: { type: string, in: path, required: true }
        package_type: { type: string, in: query, required: true, description: "npm, maven, rubygems, docker, nuget, container" }
        visibility: { type: string, in: query, description: "public, private, internal" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_org_package:
      method: GET
      path: /orgs/{org}/packages/{package_type}/{package_name}
      access: read
      description: "Get a specific package in an organization."
      params:
        org: { type: string, in: path, required: true }
        package_type: { type: string, in: path, required: true }
        package_name: { type: string, in: path, required: true }
      pagination: none

    delete_org_package:
      method: DELETE
      path: /orgs/{org}/packages/{package_type}/{package_name}
      access: dangerous
      description: "Delete an entire package in an organization. Requires admin permissions. Cannot be undone after 30 days."
      params:
        org: { type: string, in: path, required: true }
        package_type: { type: string, in: path, required: true }
        package_name: { type: string, in: path, required: true }
      pagination: none

    restore_org_package:
      method: POST
      path: /orgs/{org}/packages/{package_type}/{package_name}/restore
      access: admin
      description: "Restore a deleted organization package. Only works within 30 days of deletion."
      params:
        org: { type: string, in: path, required: true }
        package_type: { type: string, in: path, required: true }
        package_name: { type: string, in: path, required: true }
        token: { type: string, in: query, description: "Package token from delete response" }
      pagination: none

    list_org_package_versions:
      method: GET
      path: /orgs/{org}/packages/{package_type}/{package_name}/versions
      access: read
      description: "List all versions of an organization package. Filter by state: active (default), deleted."
      params:
        org: { type: string, in: path, required: true }
        package_type: { type: string, in: path, required: true }
        package_name: { type: string, in: path, required: true }
        state: { type: string, in: query, description: "active (default), deleted" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_org_package_version:
      method: GET
      path: /orgs/{org}/packages/{package_type}/{package_name}/versions/{package_version_id}
      access: read
      description: "Get a specific version of an organization package."
      params:
        org: { type: string, in: path, required: true }
        package_type: { type: string, in: path, required: true }
        package_name: { type: string, in: path, required: true }
        package_version_id: { type: integer, in: path, required: true }
      pagination: none

    delete_org_package_version:
      method: DELETE
      path: /orgs/{org}/packages/{package_type}/{package_name}/versions/{package_version_id}
      access: dangerous
      description: "Delete a specific version of an organization package. Cannot be undone after 30 days."
      params:
        org: { type: string, in: path, required: true }
        package_type: { type: string, in: path, required: true }
        package_name: { type: string, in: path, required: true }
        package_version_id: { type: integer, in: path, required: true }
      pagination: none

    restore_org_package_version:
      method: POST
      path: /orgs/{org}/packages/{package_type}/{package_name}/versions/{package_version_id}/restore
      access: admin
      description: "Restore a deleted version of an organization package. Only works within 30 days."
      params:
        org: { type: string, in: path, required: true }
        package_type: { type: string, in: path, required: true }
        package_name: { type: string, in: path, required: true }
        package_version_id: { type: integer, in: path, required: true }
      pagination: none

    # ── Packages (Authenticated User) ─────────────────────────────

    list_user_packages:
      method: GET
      path: /user/packages
      access: read
      description: "List packages owned by the authenticated user. package_type is required: npm, maven, rubygems, docker, nuget, container."
      params:
        package_type: { type: string, in: query, required: true, description: "npm, maven, rubygems, docker, nuget, container" }
        visibility: { type: string, in: query, description: "public, private, internal" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    get_user_package:
      method: GET
      path: /user/packages/{package_type}/{package_name}
      access: read
      description: "Get a package owned by the authenticated user."
      params:
        package_type: { type: string, in: path, required: true }
        package_name: { type: string, in: path, required: true }
      pagination: none

    delete_user_package:
      method: DELETE
      path: /user/packages/{package_type}/{package_name}
      access: dangerous
      description: "Delete a package owned by the authenticated user. Cannot be undone after 30 days."
      params:
        package_type: { type: string, in: path, required: true }
        package_name: { type: string, in: path, required: true }
      pagination: none

    list_user_package_versions:
      method: GET
      path: /user/packages/{package_type}/{package_name}/versions
      access: read
      description: "List all versions of a package owned by the authenticated user."
      params:
        package_type: { type: string, in: path, required: true }
        package_name: { type: string, in: path, required: true }
        state: { type: string, in: query, description: "active (default), deleted" }
        page: { type: integer, in: query }
        per_page: { type: integer, in: query, default: 30 }

    delete_user_package_version:
      method: DELETE
      path: /user/packages/{package_type}/{package_name}/versions/{package_version_id}
      access: dangerous
      description: "Delete a specific version of a package owned by the authenticated user."
      params:
        package_type: { type: string, in: path, required: true }
        package_name: { type: string, in: path, required: true }
        package_version_id: { type: integer, in: path, required: true }
      pagination: none