VX Agents

OpenAPI Marketplace · Developer Tools

GitHub Branches & File Commits

v1.0.0 · 8 endpoints · 0 connections · shared by vx.ai

Lets an agent change code in a GitHub repository without git: read the repository and its branches, create a new branch from a base commit, read files and commit new or updated files one at a time. Pair it with the GitHub Pull Requests spec to open a pull request for the changes. Curated from GitHub's official OpenAPI specification.

Connect this API to an AI agent Browse all specs

What you can do with GitHub Branches & File Commits via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
GET /repos/{owner}/{repo} getRepository Get a repository's details, including its default branch
GET /repos/{owner}/{repo}/branches listBranches List the branches of a repository
GET /repos/{owner}/{repo}/branches/{branch} getBranch Get a branch and the SHA of its latest commit
GET /repos/{owner}/{repo}/git/ref/{ref} getGitRef Get a git reference (e.g. heads/main) and the commit SHA it points to
POST /repos/{owner}/{repo}/git/refs createBranchRef Create a new branch from a commit SHA
GET /repos/{owner}/{repo}/contents/{path} getFileContent Read a file (base64 content and its sha) or list a folder
PUT /repos/{owner}/{repo}/contents/{path} createOrUpdateFile Commit one new or changed file to a branch
GET /repos/{owner}/{repo}/commits/{ref} getCommit Get a commit with its message and changed files

Authentication

githubToken

Bearer token — sent as Authorization: Bearer <token>

GitHub fine-grained personal access token sent as Authorization: Bearer <token>.

How to get a credential

  1. In GitHub open Settings > Developer settings > Personal access tokens > Fine-grained tokens and click Generate new token.
  2. Pick the resource owner (your user or organization) and set an expiry.
  3. Under Repository access choose Only select repositories and pick the repositories the agent may change.
  4. Under Repository permissions set Contents: Read and write (Metadata: Read-only is added automatically).
  5. Generate the token and copy it (it starts with github_pat_). Organization-owned repositories may need an owner to approve the token.

Permissions used

Permission Operations
Metadata: read getRepository, listBranches, getBranch
Contents: read getGitRef, getFileContent, getCommit
Contents: write createBranchRef, createOrUpdateFile

Common errors

  • 401 Bad credentials: the token is wrong, expired or revoked; generate a new one.
  • 403 Resource not accessible by personal access token: Contents write is missing, the repository is not selected on the token, or branch protection blocks the push; edit the token or use another branch. A 403 with X-RateLimit-Remaining: 0 means the hourly limit is used up.
  • 404 Not Found: private repository the token cannot see, or wrong owner/repo/path/branch.
  • 409 Conflict: the sha sent with a file update is not the file's current sha; read the file again and retry.
  • 422 Reference already exists / Invalid request: the branch name is taken, or sha is missing when updating an existing file.

Store the token as a VX Agents credential for this connector; never paste it into chat.

Usage guide

Setup

  • Add a GitHub fine-grained token as the credential with Contents: Read and write on the repositories the agent may change.
  • Preset owner and repo if the agent always works on one repository. X-GitHub-Api-Version is pinned to 2022-11-28.

Push changes on a new branch

  1. getRepository — note default_branch (the base, usually main).
  2. getBranch with that base (or getGitRef with ref=heads/main) — note the latest commit SHA.
  3. createBranchRef with ref = refs/heads/<new-branch> and sha = that SHA. Pick a descriptive, unused name (e.g. agent/fix-typo-readme).
  4. For each file to change:
    • Existing file: getFileContent with path and ref = the new branch; keep its sha.
    • createOrUpdateFile with path, branch = the new branch, message = commit message, content = the FULL new file content base64-encoded, and sha = the file's current sha (omit only for new files).
  5. getCommit to verify the last commit, then open a pull request with the "GitHub Pull Requests & Code Review" spec (head = new branch, base = default branch).

Rules

  • NEVER commit to the default branch or any branch you did not create in this task; always create a new branch first.
  • Show the user the planned changes (files and commit messages) and get confirmation before creating the branch and committing.
  • One createOrUpdateFile call = one commit = one file. After each commit the file's sha changes; re-read it before editing the same file again.

Good to know

  • content in requests and responses is base64 (responses may contain line breaks; strip them before decoding).
  • getFileContent on a folder path returns a list of entries; files over 1 MB return no inline content.
  • getCommit accepts a SHA, branch or tag as ref.
  • 409 = stale sha (re-read the file); 422 on createBranchRef = branch already exists (choose another name).

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “GitHub Branches & File Commits” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.

Related APIs