Skip to content
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 42 additions & 3 deletions box/overall/git.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,11 @@ Clone a repository, inspect changes, commit work, push a branch, or open a pull

## Configure Git Access

If you want to work with private repositories, push changes, or create pull requests, create the box with a GitHub token.
Pass a `git` config to `Box.create` to configure Git access. All fields are optional.

- **`token`** — GitHub token. Required for private repositories, pushing, and creating pull requests.
- **`userName`** — Git user name written to the container's global git config on creation. Defaults to `"Upstash Box"`.
- **`userEmail`** — Git user email written to the container's global git config on creation. Defaults to `"box@upstash.com"`.

<Note>
For a fine-grained token, the following permissions are sufficient for basic usage:
Expand All @@ -21,13 +25,15 @@ UPSTASH_BOX_API_KEY=abx_xxxxxxxxxxxxxxxxxxxxxxxx
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxx
```

```tsx {5-7}
```tsx {5-10}
import { Box } from "@upstash/box"

const box = await Box.create({
runtime: "node",
git: {
token: process.env.GITHUB_TOKEN,
token: process.env.GITHUB_TOKEN, // optional — required for private repos / push / PRs
userName: "release-bot", // optional — defaults to "Upstash Box"
userEmail: "bot@acme.com", // optional — defaults to "box@upstash.com"
},
})
```
Expand Down Expand Up @@ -144,6 +150,39 @@ const commit = await box.git.commit({
})
```

Use `authorName` and `authorEmail` to override the git identity for this commit only. If omitted, the identity configured on the box (via `Box.create` or `updateConfig`) is used.

```tsx
const commit = await box.git.commit({
message: "feat: add onboarding checklist",
authorName: "Alice", // optional — overrides git identity for this commit only
authorEmail: "alice@acme.com", // optional — overrides git identity for this commit only
})
```

### Update Git Config

Updates the git identity (`userName` and/or `userEmail`) applied to the container. Partial updates are supported — you can update either field independently. At least one field is required.

Returns the effective identity values after the update. If the box is running or idle, the new config is applied immediately inside the container.

```tsx
const config = await box.git.updateConfig({
userName: "release-bot",
userEmail: "release@acme.com",
})

console.log(config.git_user_name) // "release-bot"
console.log(config.git_user_email) // "release@acme.com"
```

```tsx
// 👇 partial update — change only one field
const config = await box.git.updateConfig({
userEmail: "ci@acme.com",
})
```

### Push

Pushes the current branch. You can also provide a branch name explicitly.
Expand Down