Skip to content

Work with Git

Last updated View as MarkdownAgent setup

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

Clone repositories

import { getSandbox } from "@cloudflare/sandbox";

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",
});
import { getSandbox } from '@cloudflare/sandbox';

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'
});

Clone private repositories

Use a personal access token in the URL:

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

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

await sandbox.gitCheckout(repoUrl);

Clone and build

Clone a repository and run build steps:

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");
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');

Work with branches

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");
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');

Make changes and commit

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"');
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"');

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:

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);
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);

Large repository timeout

Use shallow clone:

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

Was this helpful?