> ## Documentation Index > Fetch the complete documentation index at: https://docs.r28.ai/charter/llms.txt > Use this file to discover all available pages before exploring further. # GitHub > Read a failing CI log, comment on a line of a diff, and commit across files in one commit.
139 tools OAuth bearer
```python github_example.py {7} theme={null} from charter.auth import EnvTokenProvider from charter.packs import github credentials = EnvTokenProvider("GITHUB_TOKEN") github.configure(credentials) issues = await github.issues_list_for_repo.ainvoke(owner="octocat", repo="hello-world") ``` Most of the REST API an agent working in a repository reaches for: issues and their labels, assignees, milestones and history; pull requests down to a comment on one line of a diff; CI, from listing runs to reading the failing job's log; the Git object store, which is how a change across six files becomes one commit rather than six; releases; repositories, commits, file contents and search; and the notification and security-alert feeds an always-on agent wakes up on. Two boundaries worth knowing before you look for them. **Projects v2 and resolving a review thread are GraphQL-only** — there is no REST equivalent, so neither is here. And **the Actions secrets write endpoints are not carried**: they take a libsodium-sealed box, which is a dependency this library does not have. `actions_list_repo_secrets` reads the names, which is the part an agent debugging a workflow actually needs, and it is an endpoint that cannot return a value. ## Authenticating This pack takes a GitHub OAuth bearer token, and [`configure()`](/charter/charter/reference/configuration#configure) is optional when `$GITHUB_TOKEN` is set. Which credential provider you hand it depends on whose account the calls run as. Refer to [GitHub's provider page](/charter/charter/auth/providers/github) for the "GITHUB" constant the snippets below name, the scopes these 139 tools ask for, and this server's refresh behaviour. ### A token you hold For a script, or a notebook. [`EnvTokenProvider`](/charter/charter/reference/credentials#envtokenprovider) re-reads the variable on every call, so a token rotated beside the process is picked up without a restart; [`StaticTokenProvider`](/charter/charter/reference/credentials#statictokenprovider) takes one you already hold as a string. Neither renews anything, so the calls stop when the token expires. ```python github_script.py {4} theme={null} from charter.auth import EnvTokenProvider from charter.packs import github credentials = EnvTokenProvider("GITHUB_TOKEN") github.configure(credentials) ``` ### One account, refreshed For an agent or a server acting as you. [`OAuth2Client`](/charter/charter/reference/oauth#oauth2client) turns a client registration and a stored refresh token into an access token, and [renews it](/charter/charter/auth/authorization-servers#what-the-cache-does-precisely) before it lapses. ```python github_agent.py {8} theme={null} from charter.auth import OAuth2Client from charter.packs import github credentials = OAuth2Client( GITHUB, client_id=os.environ["GITHUB_CLIENT_ID"], client_secret=os.environ["GITHUB_CLIENT_SECRET"], refresh_token=os.environ["GITHUB_REFRESH_TOKEN"], ) github.configure(credentials) ``` No refresh token yet? [Getting the first grant](/charter/charter/auth/providers/github#getting-the-first-grant) is the one-time consent flow that hands you one. ### Many end users For a product whose users each connect their own account. [`SubjectProvider`](/charter/charter/reference/credentials#subjectprovider) builds one credential per user through a factory you write, and [`use_subject`](/charter/charter/reference/credentials#use_subject) names the user a call acts for. [Your users' accounts](/charter/charter/auth/oauth-flow) is the consent route inside your app; [serving many users](/charter/charter/auth/authorization-servers#serving-many-users) is the per-subject cache and its eviction. ```python github_server.py {17,21} theme={null} from functools import partial from charter.auth import OAuth2Client, SubjectProvider, use_subject from charter.packs import github # Yours to write: a user id in, that user's credential out. async def for_user(user_id: str) -> OAuth2Client: grant = await db.grants.get(user_id, "github") return OAuth2Client( GITHUB, client_id=os.environ["GITHUB_CLIENT_ID"], client_secret=os.environ["GITHUB_CLIENT_SECRET"], refresh_token=grant.refresh_token, on_refresh=partial(save_to_db, user_id), ) credentials = SubjectProvider(for_user) github.configure(credentials) # Per request: whose grant the tools use. with use_subject(request.user_id): ... # your agent runs here ``` A classic PAT, a fine-grained token and a GitHub App installation token all work. The declared scopes are what a classic PAT needs; a fine-grained token instead wants read/write on Issues, Pull requests, Contents and Metadata. ## The client [`oauth_tool_factory`](/charter/charter/reference/factories#oauth_tool_factory) is the whole client: a thin wrapper over `httpx` that attaches your token and these endpoint constants to each request. `PyGithub` does not enter your dependency tree.
```python Without the pack theme={null} from charter import oauth_tool_factory github_api_client = oauth_tool_factory( # except releases_upload_asset, which uses a different host base_url="https://api.github.com/", provider="github", credential_provider=credentials, scopes=["repo", "read:user"], # except releases_upload_asset body_format="json", query_format="repeat", body_case="snake", query_case="snake", path_case="snake", # Accept and Content-Type differ on pulls_get_diff and releases_upload_asset static_headers={ "Accept": "application/vnd.github+json", "User-Agent": "charter", "X-GitHub-Api-Version": "2022-11-28", }, # this API reports failure with an HTTP status code envelope=None, ) ``` ```python With the pack theme={null} from charter.packs import github github.configure(credentials) # The base URL, the casing, the envelope and the pagination are # already declared. 139 tools, ready to hand to a model: tools = github.TOOLS ```
`credentials` is whichever of the three you built in [Authenticating](#authenticating). A pack takes it through [`configure()`](/charter/charter/reference/configuration#configure); a client you build takes the same object as `credential_provider`, and has no `configure()` of its own. ### Paging through a list A cursor belongs to the tool that returns it, so it is declared on that tool's builder call: ```python github_pagination.py theme={null} # On issues_list_for_repo, issues_list_comments, pulls_list, # pulls_list_files, repos_list_for_authenticated_user, # repos_list_commits, pulls_list_reviews, branches_list, # actions_list_workflow_runs, search_code, # actions_list_jobs_for_run, actions_list_workflows, # actions_list_runs_for_workflow, actions_list_run_artifacts, # actions_list_repo_secrets, checks_list_for_ref, # checks_list_annotations, checks_list_suites_for_ref, # repos_get_combined_status, pulls_list_review_comments, # pulls_list_review_comments_for_repo, # pulls_list_comments_for_review, pulls_list_commits, # repos_get_commit, repos_compare_commits, repos_list_tags, # issues_list_labels_for_repo, issues_list_milestones, # issues_list_timeline, issues_list_events, # issues_list_for_authenticated_user, issues_list_sub_issues, # releases_list, releases_list_assets, notifications_list, # code_scanning_list_alerts, secret_scanning_list_alerts, # repos_list_for_org and repos_list_contributors. issues_list_for_repo = github_api_client( name="issues_list_for_repo", args_schema=IssuesListForRepoRequest, method="GET", url_template="repos/{owner}/{repo}/issues", pagination=Pagination( page_param="page", per_page_param="per_page", ), ) # On search_issues, search_repositories, search_commits and # search_users. search_issues = github_api_client( name="search_issues", args_schema=SearchIssuesRequest, method="GET", url_template="search/issues", pagination=Pagination( page_param="page", per_page_param="per_page", items_field="items", ), ) ``` Pagination is declared on `issues_list_for_repo`, `issues_list_comments`, `pulls_list`, `pulls_list_files`, `repos_list_for_authenticated_user`, `repos_list_commits`, `pulls_list_reviews`, `branches_list`, `actions_list_workflow_runs`, `search_code`, `actions_list_jobs_for_run`, `actions_list_workflows`, `actions_list_runs_for_workflow`, `actions_list_run_artifacts`, `actions_list_repo_secrets`, `checks_list_for_ref`, `checks_list_annotations`, `checks_list_suites_for_ref`, `repos_get_combined_status`, `pulls_list_review_comments`, `pulls_list_review_comments_for_repo`, `pulls_list_comments_for_review`, `pulls_list_commits`, `repos_get_commit`, `repos_compare_commits`, `repos_list_tags`, `issues_list_labels_for_repo`, `issues_list_milestones`, `issues_list_timeline`, `issues_list_events`, `issues_list_for_authenticated_user`, `issues_list_sub_issues`, `releases_list`, `releases_list_assets`, `notifications_list`, `code_scanning_list_alerts`, `secret_scanning_list_alerts`, `repos_list_for_org`, `repos_list_contributors`, `search_issues`, `search_repositories`, `search_commits` and `search_users`. The other 96 take no cursor. ## Tools Each is a [`Tool`](/charter/charter/reference/tool), called with [`ainvoke`](/charter/charter/reference/tool#tool-ainvoke) as in the snippet above. The name links to its parameters, its response and what it costs.
Issues issues\_list\_for\_repoGET List issues in a repository. issues\_getGET Get a single issue by its number, including the full body text. issues\_createPOST Open an issue. issues\_updatePATCH Update an issue. issues\_create\_commentPOST Post a comment on an issue or pull request. issues\_list\_commentsGET List the comments on an issue or pull request, oldest first. issues\_list\_labels\_for\_repoGET List the labels a repository defines, with their colours and descriptions. issues\_add\_labelsPOST Add labels to an issue, keeping the ones already on it. issues\_set\_labelsPUT Replace an issue's labels with exactly this set, dropping any others. issues\_remove\_labelDELETE Take one label off an issue, leaving the others in place. issues\_create\_labelPOST Define a new label on the repository. issues\_update\_labelPATCH Rename a label or change its colour, description, or archived state. issues\_delete\_labelDELETE Delete a label, removing it from every issue that carries it. issues\_add\_assigneesPOST Assign people to an issue, keeping whoever is already assigned. issues\_remove\_assigneesDELETE Unassign people from an issue. issues\_list\_milestonesGET List a repository's milestones, with how many issues in each are open and closed. issues\_create\_milestonePOST Create a milestone. issues\_update\_milestonePATCH Update a milestone. issues\_get\_commentGET Get one issue comment by its id — the id from issues\_list\_comments, not the issue number. issues\_update\_commentPATCH Edit an issue comment's text. issues\_delete\_commentDELETE Delete an issue comment. issues\_list\_timelineGET List everything that has happened to an issue in order — comments, labels, assignments, cross-references, the commits that mentioned it. issues\_list\_eventsGET List an issue's state changes — labelled, assigned, closed, renamed — without the comments. issues\_lockPUT Lock an issue or pull request's conversation. issues\_unlockDELETE Unlock a conversation that was locked. issues\_list\_for\_authenticated\_userGET List the authenticated user's issues across every repository they can see — the agent's own queue. issues\_list\_sub\_issuesGET List the sub-issues of an issue — how a tracking issue's pieces are found. issues\_add\_sub\_issuePOST Attach an existing issue to this one as a sub-issue. Pulls pulls\_listGET List pull requests. pulls\_getGET Get a single pull request, including its mergeability and the counts of changed files, additions and deletions. pulls\_createPOST Open a pull request from head into base. pulls\_list\_filesGET List the files a pull request changes, with per-file additions, deletions and patch text. pulls\_updatePATCH Update a pull request's title, body, state or base branch. pulls\_mergePUT Merge a pull request. pulls\_create\_reviewPOST Approve a pull request, request changes on it, or leave a comment. pulls\_list\_reviewsGET List the reviews left on a pull request, oldest first. pulls\_request\_reviewersPOST Ask users or teams to review a pull request. pulls\_create\_review\_commentPOST Leave a comment on a specific line of a pull request's diff — the thing reviewing is made of. pulls\_list\_review\_commentsGET List the line comments on a pull request, each with the file and line it sits on. pulls\_reply\_to\_review\_commentPOST Reply to an existing review comment, continuing its thread. pulls\_update\_review\_commentPATCH Edit the text of a review comment. pulls\_delete\_review\_commentDELETE Delete a review comment. pulls\_list\_review\_comments\_for\_repoGET List the line comments across every pull request in a repository. pulls\_get\_reviewGET Get one review of a pull request, with its state and summary text. pulls\_submit\_reviewPOST Submit a pending review as an approval, a request for changes, or a comment. pulls\_update\_reviewPUT Edit a review's summary text. pulls\_dismiss\_reviewPUT Dismiss a review so it stops blocking the pull request, with a message saying why. pulls\_delete\_pending\_reviewDELETE Discard a review that was never submitted. pulls\_list\_comments\_for\_reviewGET List the line comments that belong to one review, rather than to the pull request as a whole. pulls\_get\_diffGET Get a pull request's whole change as a unified diff, in one call. pulls\_list\_commitsGET List the commits on a pull request. pulls\_update\_branchPUT Bring a pull request's branch up to date by merging the base branch into it — the fix for a 'this branch is out of date' block. pulls\_check\_mergedGET Ask whether a pull request has been merged. pulls\_list\_requested\_reviewersGET List who has been asked to review and has not answered yet. pulls\_remove\_requested\_reviewersDELETE Withdraw a review request from users or teams. Repos repos\_getGET Get a repository's metadata, including its default branch and topics. repos\_list\_for\_authenticated\_userGET List repositories the authenticated user can access. repos\_get\_contentGET Read a file, or list a directory. repos\_list\_commitsGET List commits, newest first. repos\_create\_or\_update\_filePUT Create a file or replace an existing one, in a single commit. branches\_listGET List a repository's branches and the commit each one points at. git\_refs\_createPOST Create a branch or tag pointing at an existing commit. repos\_get\_commitGET Get one commit with its diff and per-file line counts. repos\_compare\_commitsGET Compare two refs and get what is in one and not the other: the status, how far ahead or behind, the commits and the changed files. repos\_delete\_fileDELETE Delete a file in a commit of its own. repos\_merge\_branchesPOST Merge one branch into another directly, without opening a pull request. repos\_get\_branchGET Get one branch: its head commit and whether it is protected. repos\_rename\_branchPOST Rename a branch. repos\_get\_branch\_protectionGET Read a branch's protection rules — required checks, required reviews, linear history — before attempting a write that they would refuse. repos\_list\_branches\_for\_head\_commitGET List the branches whose head is this exact commit — 'has this landed, and where', asked from the commit's side. repos\_get\_readmeGET Get the repository's README, decoded to text. repos\_list\_tagsGET List a repository's tags with the commit each points at, newest first. repos\_create\_forkPOST Fork a repository, optionally into an organization or under a new name. repos\_list\_for\_orgGET List an organization's repositories. repos\_list\_languagesGET List a repository's languages with bytes of code each — the quickest way to find out what a repository is written in before reading any of it. repos\_list\_contributorsGET List contributors, most commits first — who to ask about a repository. Search search\_issuesGET Search issues and pull requests across GitHub with qualifiers, e.g. 'repo:owner/name is:issue is:open label:bug'. search\_repositoriesGET Search repositories with qualifiers, e.g. 'topic:cli language:go stars:>500'. search\_codeGET Search code across GitHub. search\_commitsGET Search commits by message, author or date across GitHub — 'repo:owner/name fix flaky test'. search\_usersGET Search users and organizations — 'type:org language:rust'. Users users\_get\_authenticatedGET Get the authenticated user. Actions actions\_list\_workflow\_runsGET List CI runs, most recent first. actions\_rerun\_workflowPOST Run a workflow again from the start, including jobs that passed. actions\_cancel\_workflow\_runPOST Ask GitHub to cancel a running workflow. actions\_get\_workflow\_runGET Get one workflow run: its status, conclusion, branch, commit and attempt number. actions\_list\_jobs\_for\_runGET List a run's jobs, each with its conclusion and its failing steps named. actions\_get\_jobGET Get one job of a workflow run, with the steps that did not pass named individually and the runner it ran on. actions\_download\_job\_logsGET Read a failing job's log. actions\_download\_run\_logsGET Read a whole run's logs in one call. actions\_rerun\_failed\_jobsPOST Re-run only the failed jobs of a run, and the jobs that depend on them. actions\_list\_workflowsGET List the repository's workflows, with the file each one is defined in and whether it is active or disabled. actions\_get\_workflowGET Get one workflow. actions\_create\_workflow\_dispatchPOST Trigger a workflow by hand on a branch or tag. actions\_list\_runs\_for\_workflowGET List the runs of one workflow, most recent first — 'is this pipeline green', rather than 'is anything red'. actions\_list\_run\_artifactsGET List what a run uploaded, with each artifact's size and whether it has expired. actions\_get\_artifactGET Get one artifact's name, size, expiry and digest. actions\_download\_artifactGET Download an artifact and report what is in it: every entry's name and size, plus the contents of the small text files — a JUnit report or a coverage summary comes back readable. actions\_get\_run\_usageGET Get a run's total run time and its billable milliseconds per runner operating system. actions\_list\_pending\_deploymentsGET List the environments a run is waiting on for approval, and who can approve them. actions\_review\_pending\_deploymentsPOST Approve or reject a run's pending deployments. actions\_list\_repo\_secretsGET List the names of the repository's Actions secrets, with when each was created and last changed. Checks checks\_list\_for\_refGET List the check runs reported against a commit, branch or tag — every CI provider that reports as a GitHub App, Actions included. checks\_get\_runGET Get one check run, with its summary text and how many annotations it produced. checks\_list\_annotationsGET List a check run's annotations: each failure with the file, the line range, a level and a message, already extracted by whoever ran the check. checks\_list\_suites\_for\_refGET List the check suites for a commit, branch or tag — one suite per app that reported. repos\_get\_combined\_statusGET Get the single rolled-up state of a commit — 'success', 'failure', 'pending' or 'error' — plus one line per reporting context. Git git\_refs\_getGET Get a reference and the commit SHA it points at — how you read a branch's current head before building on it. git\_refs\_updatePATCH Point a branch or tag at a different commit — the step that makes a commit built with git\_trees\_create and git\_commits\_create visible. git\_refs\_deleteDELETE Delete a branch or tag, by reference. git\_refs\_list\_matchingGET List every reference under a prefix — heads/ for all branches, tags/v2 for the v2 tags. git\_blobs\_createPOST Write a file's content into the object store and get its SHA back, without committing anything. git\_blobs\_getGET Read a blob by SHA, decoded to text. git\_trees\_createPOST Build one commit's worth of changes across any number of files. git\_trees\_getGET Read a tree: every path in it with its mode and object SHA. git\_commits\_createPOST Create a commit pointing at a tree. git\_commits\_getGET Read a commit object: its message, its tree SHA and its parents. git\_tags\_createPOST Create an annotated tag object. Releases releases\_listGET List a repository's releases, newest first. releases\_getGET Get one release by its numeric id, with its notes and its assets. releases\_get\_latestGET Get the latest published release — GitHub's definition, meaning the most recent release that is neither a draft nor a prerelease. releases\_get\_by\_tagGET Get a release by its tag name, such as 'v1.4.0'. releases\_createPOST Publish a release, creating its tag if it does not exist. releases\_updatePATCH Update a release; anything omitted is left unchanged. releases\_deleteDELETE Delete a release. releases\_generate\_notesPOST Generate release-note text from the pull requests merged since a previous tag. releases\_list\_assetsGET List the files attached to a release, with sizes and download counts. releases\_upload\_assetPOST Attach a file to a release. Monitoring notifications\_listGET List your unread notifications — mentions, review requests, assignments — most recently updated first. notifications\_mark\_readPUT Mark notifications as read — all of them, or everything up to last\_read\_at. notifications\_get\_threadGET Get one notification thread: what it concerns, and the reason you were notified. notifications\_mark\_thread\_readPATCH Mark one notification thread as read — how an agent takes a handled item off its own queue. dependabot\_list\_alertsGET List a repository's Dependabot alerts: which dependency, how severe, and the first version that fixes it. dependabot\_get\_alertGET Get one Dependabot alert, with its advisory summary and the patched version. dependabot\_update\_alertPATCH Dismiss a Dependabot alert or reopen one. code\_scanning\_list\_alertsGET List code scanning alerts, each with the rule that fired and the file and line it fired on. code\_scanning\_get\_alertGET Get one code scanning alert, with the rule's description and the most recent place it was seen. secret\_scanning\_list\_alertsGET List secret scanning alerts: which pattern matched, which provider, and whether the credential is still valid. rate\_limit\_getGET Check how much API budget is left, per resource.
## Constant headers beside a bearer token GitHub wants three headers on every request that have nothing to do with the model: an `Accept` naming the media type, an `X-GitHub-Api-Version`, and a `User-Agent` — GitHub answers 403 to a request without one. They are declared once as `static_headers` on the factory and sent verbatim. None of them appears in any tool's LLM schema, so they cost nothing in context and a model has no path to setting them. This is the OAuth-plus-constant-headers shape that [`static_headers`](/charter/charter/tools/wire-contract) exists for. Pinning the version is the point of the exercise: an unpinned integration is one that breaks on GitHub's schedule rather than on yours. `github.API_VERSION` is the version these schemas were written against. ## Paging by number There is no cursor. You ask for page 1, 2, 3 and stop when a page comes back shorter than `per_page`, which is why both parameters are required on a page-number `Pagination` — without the page size there is no way to tell a full page from the last one. Both are real fields on the schemas that declare it. ```python github_page_through_issues.py theme={null} args = {"owner": "octocat", "repo": "hello-world", "per_page": 30} while args is not None: page = await github.issues_list_for_repo.ainvoke(args) handle(page) args = github.issues_list_for_repo.pagination.next_page_args(page, args) ``` The search endpoints wrap their results in `items` rather than returning a bare array, so they declare the same style with `items_field="items"`. That is the only difference between `GITHUB_PAGINATION` and `SEARCH_PAGINATION`. ## Response trimming One issue is 4–6KB of nested user objects, reaction counts and twenty `*_url` fields; a page of thirty is a quarter of a million characters, almost none of it actionable. Twenty-four of the twenty-nine tools carry a response handler. The handlers **project rather than filter** — they narrow each object but never drop one, because dropping an item would corrupt the page-length signal that page-number pagination depends on. `issues_create_comment`, `issues_list_comments` and `pulls_list_files` have no handler and return GitHub's payload as it arrived. `pulls_list_files` in particular carries full patch text, which is the point of calling it and also the largest response in the pack. ## Gotchas That is GitHub's model, not a quirk of this pack: `issues_list_for_repo` returns both. GitHub's own signal for it is the presence of a `pull_request` key, which does not survive trimming, so the handler sets `is_pull_request` on the ones that are. GitHub also advertises the next page in a `Link` header (RFC 8288). A Charter response is the parsed body, so the page number is the marker this pack declares. In practice the two agree; where they differ is a repository mutating under you mid-walk, and neither marker is reliable then. 30 requests per minute, against 5,000 per hour for the rest of the REST API. A search-heavy agent hits that long before it hits the general limit. When it does, `APIError.retry_after` carries GitHub's own answer to "when?" — see [the wire contract](/charter/charter/tools/wire-contract). `labels` and `assignees` on `issues_update` overwrite what is there. To add one label, read the current set with `issues_get` and send the union. Closing an issue is `state="closed"`, with `state_reason` saying why. Passing `type` together with `visibility` or `affiliation` is a 422 from GitHub. Use one or the other; a request carrying both is refused locally, before the round trip. All three carry a documented default, and none of them is set on the schema. That is deliberate. GitHub's defaults describe what it applies to a request that *omits* the parameter, so copying them onto the fields put all three on the wire for every call and made the 422 the normal case rather than the edge one. A default you send is not a default. Pass a file path and it returns that file with its contents decoded as text; pass a directory path and it returns a listing. Pass an empty `path` for the repository root. The shape of the response depends on what the path pointed at, which is GitHub's design. A binary file and a file over 1MB both come back as a `content` string saying which of the two happened, plus the `download_url` to fetch it with. Neither is an error, and both are silent if you do not look for them: a binary file base64-decodes to replacement characters, which reads as content until you try to use it, and GitHub answers a file between 1MB and 100MB with `encoding: "none"` and an empty string. Over 100MB it does not serve this endpoint at all. GitHub serves only the first 1,000 matches of any query. `total_count` reports the real size of the match set, so a page-number walk has every reason to keep going and gets a 422 when `page × per_page` passes 1,000. The search schemas check that pair locally and say to narrow the query instead — a date range, a repository, a label. ## Related * [GitHub](/charter/charter/auth/providers/github) — OAuth app flow and token types * [The wire contract](/charter/charter/tools/wire-contract) — `static_headers` and page-number pagination * [Observability](/charter/charter/running/observability) — what a call records