Work with Git

import { TypeScriptExample, Render } from "~/components";

<Render file="sdk-0x-note" product="sandbox" params={{ href: "/sandbox/commands/run-tests-from-a-git-repository/", title: "Run tests from a Git repository" }} />

This guide shows you how to clone repositories, manage branches, and automate Git operations in the sandbox.

Clone repositories

const sandbox = getSandbox(env.Sandbox, 'my-sandbox');

// Basic clone await sandbox.gitCheckout('https://github.com/user/repo');

// Clone specific branch await sandbox.gitCheckout('https://github.com/user/repo', { branch: 'develop' });

// Shallow clone (faster for large repos) await sandbox.gitCheckout('https://github.com/user/large-repo', { depth: 1 });

// Clone to specific directory await sandbox.gitCheckout('https://github.com/user/my-app', { targetDir: '/workspace/project' });

</TypeScriptExample>

## Clone private repositories

Use a personal access token in the URL:

<TypeScriptExample>

const token = env.GITHUB_TOKEN; const repoUrl = https://${token}@github.com/user/private-repo.git;

await sandbox.gitCheckout(repoUrl);

</TypeScriptExample>

:::note[More secure alternative]
Embedding a token in the URL passes the credential directly into the sandbox. For better access control, use an outbound handler that injects the real token at request time — the sandbox never holds the credential. Refer to [Handle outbound traffic](/sandbox/sdk/guides/outbound-traffic/).
:::

## Clone and build

Clone a repository and run build steps:

<TypeScriptExample>

await sandbox.gitCheckout('https://github.com/user/my-app');

const repoName = 'my-app';

// Install and build await sandbox.exec(cd ${repoName} && npm install); await sandbox.exec(cd ${repoName} && npm run build);

console.log('Build complete');

</TypeScriptExample>

## Work with branches

<TypeScriptExample>

await sandbox.gitCheckout('https://github.com/user/repo');

// Switch branches await sandbox.exec('cd repo && git checkout feature-branch');

// Create new branch await sandbox.exec('cd repo && git checkout -b new-feature');

</TypeScriptExample>

## Make changes and commit

<TypeScriptExample>

await sandbox.gitCheckout('https://github.com/user/repo');

// Modify a file const readme = await sandbox.readFile('/workspace/repo/README.md'); await sandbox.writeFile('/workspace/repo/README.md', readme.content + '\n\n## New Section');

// Commit changes await sandbox.exec('cd repo && git config user.name "Sandbox Bot"'); await sandbox.exec('cd repo && git config user.email "bot@example.com"'); await sandbox.exec('cd repo && git add README.md'); await sandbox.exec('cd repo && git commit -m "Update README"');

</TypeScriptExample>

## Best practices

- **Use shallow clones** - Faster for large repos with `depth: 1`
- **Store credentials securely** - Use environment variables for tokens
- **Clean up** - Delete unused repositories to save space

## Troubleshooting

### Authentication fails

Verify your token is set:

<TypeScriptExample>

if (!env.GITHUB_TOKEN) { throw new Error('GITHUB_TOKEN not configured'); }

const repoUrl = https://${env.GITHUB_TOKEN}@github.com/user/private-repo.git; await sandbox.gitCheckout(repoUrl);

</TypeScriptExample>

### Large repository timeout

Use shallow clone:

<TypeScriptExample>

await sandbox.gitCheckout('https://github.com/user/large-repo', { depth: 1 });

</TypeScriptExample>

## Related resources

- [Files API reference](/sandbox/sdk/api/files/) - File operations after cloning
- [Execute commands guide](/sandbox/sdk/guides/execute-commands/) - Run git commands
- [Manage files guide](/sandbox/sdk/guides/manage-files/) - Work with cloned files