GitHub tool

The GitHub tool lets an agent work in your repositories - reading and writing files, creating branches, filing and answering issues, opening and merging pull requests, cutting releases, and running workflows. It has 30 actions, and one tool configuration maps to one personal access token.

What it can do

The agent chooses one action per call. The 30 actions, by area:

• Repositories - get_me, list_repos, get_repo, list_branches, create_branch, list_commits.
• Files - get_file, create_file, update_file, delete_file.
• Issues - list_issues, get_issue, create_issue, update_issue, comment_issue, list_issue_comments.
• Pull requests - list_pull_requests, get_pull_request, create_pull_request, update_pull_request, merge_pull_request, list_pull_request_files.
• Releases - list_releases, create_release.
• Workflows - list_workflows, list_workflow_runs, trigger_workflow.
• Search - search_repositories, search_code, search_issues.

Four things worth knowing:

• There is no delete-a-repository action, deliberately. Nothing the agent can do removes a repository.
• File edits just work. GitHub requires the current blob SHA to change a file, and stores content base64-encoded. The tool handles both, so the agent reads and writes ordinary text.
• A pinned repository wins. If the configuration sets an owner and repository, the agent cannot be redirected to a different one, whatever it is asked to do. See Locking a configuration.
• Triggering a workflow needs the workflow to allow it. trigger_workflow works only on workflows whose file declares workflow_dispatch. Without it GitHub refuses the run.

Because the tool runs outside the model's turn, a GitHub configuration can also be wired as a post-call action hook - filing an issue after every call, for instance, with fields taken from the call's analysis.

Creating the token

Both kinds of personal access token work, and both start in the same place: Settings → Developer settings → Personal access tokens on GitHub.

Prefer fine-grained tokens. You grant them named repositories rather than everything your account can reach, which makes the blast radius a thing you choose rather than a thing you inherit.

1. Choose Generate new token.
2. Set Resource owner to your account, or to the organization that owns the repositories.
3. Set Repository access to Only select repositories and pick the ones the agent should work in.
4. Under Permissions, set Contents, Issues, Pull requests and Actions to Read and write. Metadata read access is added automatically.
5. Generate the token, copy it, and paste it into the Hania form.

For a classic token instead: Generate new token (classic), select the repo and workflow scopes, generate, and copy it. GitHub shows the value once.

Which permissions map to what: Contents covers files, branches, commits and releases; Issues and Pull requests cover their own areas; Actions covers listing and triggering workflow runs. On a classic token, repo covers the first three and workflow is what lets the agent edit workflow files.

Locking a configuration to one repository

The Repository owner and Repository name fields are optional, and they do one thing: pin this configuration to a single repository. Set both, and the agent can only ever touch that repository - the pinned values take precedence over anything it is told or asked. Leave them blank and the agent works across whatever the token can reach, choosing a repository per action.

If you start from the GitHub preset, both fields sit under Show advanced in the form, since neither is required.

Field reference

• Personal Access Token (required, secret) - a GitHub personal access token. Classic tokens need the repo and workflow scopes; fine-grained tokens need Contents, Issues, Pull requests and Actions at read and write on the repositories you want the agent to use. Stored encrypted and never returned.
• Repository owner (optional) - a GitHub username or organization to lock this configuration to. Blank means the agent works across repositories.
• Repository name (optional) - a repository name to lock this configuration to. Only has an effect alongside the owner.

Troubleshooting

• "Bad credentials" (401) - the token is wrong, was truncated when pasted, or has been revoked or expired. Generate a new one and retype it; editing the configuration without retyping keeps the old value.
• "Not Found" (404) on a repository you can see - the token doesn't have access. On fine-grained tokens this usually means the repository wasn't selected under repository access. GitHub answers with a 404 rather than a permission error for private repositories, so treat this as a permissions message.
• Workflow file edits are rejected - a classic token needs the workflow scope on top of repo to change anything under .github/workflows.
• A fine-grained token for an organization's repositories doesn't work - organizations can require an owner to approve fine-grained tokens before they do anything. This one comes from GitHub's documented organization policy rather than our own testing, so if a token looks correct and still sees nothing in an org, ask an owner whether it needs approving.
• "Reference already exists" (422) - create_branch on a branch name that's already there. The agent normally recovers by reusing or renaming.
• "Pull Request has merge conflicts" (405) - the branch can't be merged cleanly. Nobody can resolve that through the API; the conflict has to be settled in the branch first.
• "Validation Failed" (422) - GitHub rejected the request body, usually a missing or malformed field. The agent tends to correct these itself, so they may flash past in a trace before the call succeeds.
• A release you just created isn't in the list - releases can take a few seconds to appear. Waiting and listing again is enough.

Safety in autonomous runs

Like any tool, the GitHub tool carries a safety classification (read-only / destructive / sends-data-externally) that governs scheduled or triggered (autonomous) runs. Because it writes to an external code host, a new configuration is created with Read-only switched off and Sends data externally switched on.

Destructive is left off, which is a deliberate difference from tools like Stripe or Notion. The flag gates the whole configuration, and most of what an agent does here - opening an issue, pushing a file, raising a pull request - is an ordinary write that git keeps history for. Two actions are worth more caution: merge_pull_request and delete_file. If you want a human in the loop before those run unattended, switch Destructive on for the configuration; scheduled and triggered runs will then be gated unless the agent's "Allow destructive actions in autonomous runs" setting is enabled. Interactive chat is never gated by these flags.

If you'd rather gate one action than the whole tool, the other lever is per-tool approval on the agent itself: assign the tool with Approval set to Always, and every call pauses for a person to approve, edit or deny it.

Security

The token is stored AES-encrypted at rest and is never returned by the API - the console shows only whether a token is set. Editing a configuration without retyping the token preserves the stored one, so you must retype it to replace it. To revoke access, delete the token in GitHub under Settings → Developer settings → Personal access tokens; it stops working everywhere at once. Fine-grained tokens also expire on a date you choose, which is a reasonable habit for an agent that only needs access for a while.