Clone a repository, inspect changes, commit work, push a branch, or open a pull request from inside a box.
Configure Git Access#
If you want to work with private repositories, push changes, or create pull requests, create the box with a GitHub token.
For a fine-grained token, the following permissions are sufficient for basic usage:
- Contents — Read and write
- Pull requests — Read and write
Git identity#
You can also set the git author identity that will be used for commits made inside the box. Both fields are optional and applied to the container's global git config on creation.
| Field | Type | Default | Description |
|---|---|---|---|
token | string | — | GitHub token for private repos and push |
userName | string | "Upstash Box" | Value written to git config user.name |
userEmail | string | "box@upstash.com" | Value written to git config user.email |
If userName or userEmail are omitted, the box uses the defaults ("Upstash Box" / "box@upstash.com"). Omitting token is fine for public repositories where push access is not required.
Quickstart#
Clone a repository#
Inspect what changed#
Use status() for a compact summary and diff() to diff the repo's uncommitted changes against the initial state.
Commit and push#
After your code changes are ready, create a commit and push the branch.
Open a pull request#
Create a PR once your branch is pushed.
API#
Clone#
Clones a repository into the current working directory in the box.
Status#
Returns the Git status output for the repository in the current working directory.
- See what files changed
- See if there are there untracked files
Diff#
Returns the current Git diff as a string.
- Useful to display a patch in your UI
- Review what an agent changed
Commit#
Creates a commit and returns commit information including the SHA and message.
You can optionally override the commit author for a single commit using authorName and authorEmail. When omitted, the box's configured git identity is used (either the values set at creation via config.git or the latest updateConfig values).
| Option | Type | Required | Description |
|---|---|---|---|
message | string | Yes | Commit message |
authorName | string | No | Override --author name for this commit only |
authorEmail | string | No | Override --author email for this commit only |
Push#
Pushes the current branch. You can also provide a branch name explicitly.
Create a PR#
Creates a pull request and returns the PR URL and metadata.
Checkout#
Switches to another branch in the current repository.
Run a custom Git command#
Runs a raw Git command and returns the command output. Useful escape hatch if the built-in helpers don't cover a use case.
Update Git Config#
Updates the git author identity in the running container. At least one field must be provided; the other field retains its current value.
Returns the effective identity values after the update.
You can update a single field — the other will not change:
If the box is in Running or Idle state, the new config is applied immediately inside the container (equivalent to running git config --global for the updated fields). Changes take effect for all subsequent commits.
| Option | Type | Required | Description |
|---|---|---|---|
userName | string | No | New value for user.name |
userEmail | string | No | New value for user.email |
Return value: { git_user_name: string; git_user_email: string }
Examples#
Use Git with an agent#
If you configured a box agent, it also has full git access.
This is especially useful when the exact git steps are not known ahead of time. For example, if the user sends an open-ended request, you may not know in advance what branch name, commit message, or final push flow makes sense.
In that case, you can let the agent inspect the repository, decide what changes are needed, and handle the git workflow itself.