> ## Documentation Index
> Fetch the complete documentation index at: https://agents.nanonets.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Commit Files

> Creates, updates or deletes files as one commit on an agent/ branch of a GitHub repository.

Creates, updates or deletes up to 100 text files as one commit on an existing `agent/` branch: create one with `github_create_branch`, commit there, then open a pull request with `github_open_pull_request` for a person to review and merge.

## Authentication and enablement

Requires a connected native GitHub integration (`mcp:github`) — a first-party GitHub App connection, not Composio. The connector is shown on Trail and to Nanonets superadmins; it is hidden from Nanonets customers during rollout.

Connecting opens GitHub's install page for the Trail GitHub App, where the user picks the account and either all repositories or only selected ones. Tools act as the app's bot account through short-lived installation tokens — not as the connecting user — and reach only the repositories of that installation. To change which repositories are included, edit the installation on GitHub (the account's or organization's installed GitHub Apps settings) or reconnect. If an organization owner still has to approve the app, calls fail until they do; if the app was uninstalled or suspended, calls fail until GitHub is reconnected.

Relies on the app's Contents (write) permission.

This tool changes code or runs CI, so it works only after someone with permission to update connections turns on **Allow code changes** for the GitHub connection on the connectors page. It is off for every new connection, because code an agent pushes can run in the repository's CI with the repository's secrets. Until it is on, calls fail with an error that says so.

## Inputs

* `owner` (required): repository owner (user or organization).
* `repo` (required): repository name.
* `branch` (required): existing branch to commit to; must start with `agent/`.
* `message` (required): commit message.
* `files` (required): changes, each with:
  * `path` (required): file path from the repository root.
  * `content`: full new file content (UTF-8 text). Ignored when `delete` is true.
  * `delete` (optional): delete this path instead of writing it.

## Output

* `branch`: the branch committed to.
* `sha`: the new commit's SHA.
* `url`: the commit on GitHub.
* `files`: how many changes the commit contains.

## Limits and side effects

* **Writes**: adds one commit to `branch`, authored by the app's bot. Not idempotent — repeating it adds another commit (an empty one if nothing differs).
* Atomic: all changes land in a single commit or none do. The branch update is never forced — if someone pushed to the branch since it was read, GitHub rejects the commit and nothing changes; retry to commit on top of the new head.
* Writes only to branches starting with `agent/`, and never to the default branch (compared case-insensitively), refusing anything else before calling GitHub.
* `owner`/`repo` must be plain GitHub names (letters, numbers, `.`, `_`, `-`); anything else is rejected before any API call.
* `branch` must be a valid branch name (git's ref-name rules: letters, numbers, `.`, `_`, `/`, `-`; no `..`, no empty part (`a//b`, leading or trailing `/`), no part starting or ending with `.` (so `./main` is refused), no `.lock` suffix, no leading `-`).
* 1–100 changes per commit, each `path` at most once, no empty, `.` or `..` segments; content must be UTF-8 text and total at most 5 MB.
* Refuses any path under `.github/workflows/` or `.github/actions/` (case-insensitive): a workflow pushed to any branch runs with the repository's secrets, so CI definitions are left to people. Other files can still be run by an existing push workflow (scripts, a `Makefile`), which is why code changes must be turned on for the connection.
* Each `content` replaces the whole file. An existing file keeps its mode (an executable script stays executable); a new file is a regular file. Paths that are symlinks or submodules are refused.
* Branch protection or rulesets on `branch` still apply and can reject the commit.

## Expected errors

* No GitHub connection, a connection still waiting for an organization owner to approve the app, or an app that was uninstalled or suspended (reconnect GitHub).
* Invalid `owner`/`repo` format.
* Missing `message`, invalid `branch` name, or invalid `files` (empty, more than 100, duplicate or invalid path, a path under `.github/workflows/` or `.github/actions/`, non-UTF-8 content, over 5 MB).
* A path that is a symlink or a submodule.
* Code changes are not turned on for the connection.
* `branch` does not start with `agent/`, or is the repository's default branch.
* `branch` does not exist (404).
* The commit was rejected and nothing changed — the branch moved meanwhile, or a path is invalid (e.g. deleting a file that does not exist).
* Not allowed (403): a protected branch or ruleset.
* GitHub API errors surface as the tool's error, rewritten to say what to fix: not found or no access to that repository (404), not allowed — missing app permission, protected branch or org policy (403), GitHub refused the change (409/422, with GitHub's message), the repository is empty (no commits yet, HTTP 409), rate limit reached with the retry time (including GitHub's secondary limits, which ask for a one-minute wait), rejected app credentials (reconnect).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.