GitHub Sync

Code Storage ships with a first-class GitHub sync engine. The engine maintains read/write parity between GitHub and your Code Storage repositories.

TypeScript

const repo = await store.createRepo({
  baseRepo: {
    owner: 'your-github-org',
    name: 'repository-name',
    defaultBranch: 'main', // Optional, defaults to 'main'
  },
  defaultBranch: 'main', // Optional, defaults to 'main' for the Code Storage repo
});

// Optional: trigger initial sync from GitHub
await repo.pullUpstream();

// Now you can work with the synced content
const files = await repo.listFiles();
const commits = await repo.listCommits();

How it works:

• When you create a repo with baseRepo, Code Storage links it to the specified GitHub repository
• The pullUpstream() method fetches the latest changes from GitHub
• You can then use all SDK features (diffs, commits, file access) on the synced content
• The provider is automatically set to “github” when using baseRepo

Note: GitHub-backed repositories treat GitHub as the source of truth. This means all pushes to Code Storage are forwarded to GitHub and all changes are mirrored back to Code Storage.

Setup GitHub App

To enable GitHub sync, you’ll need to create a GitHub App:

1. Create the app

   • Go to Settings → Developer settings → GitHub Apps
2. Set permissions

   Repository permissions:

   • Contents: Read
   • Metadata: Read

   Webhook events:

   • Push
   • Create
   • Pull Request (optional, if you want PR sync)

   Webhook callback URL:

   • Let Code Storage handle callbacks for you:

   • Or use your own handler

3. Record credentials

   • GitHub App ID
   • Private Key
   • Webhook Secret

Automatic Sync with Webhooks

Your GitHub App can emit webhook events to automatically sync changes. You can either handle them yourself or let Code Storage manage them.

Option A: Handle Webhooks Yourself

If you already have a webhook handler or want more control:

• Set the Webhook callback URL to point to your handler.
• Your handler should process GitHub events and call Code Storage as needed.

Example:

// Your webhook handler
app.post('/github-webhook', async (req, res) => {
  // Verify GitHub webhook signature
  const signature = req.headers['x-hub-signature-256'];
  if (!verifyGitHubSignature(req.body, signature, webhookSecret)) {
    return res.status(401).send('Invalid signature');
  }

  // When you receive a push event, trigger Code Storage sync
  if (req.headers['x-github-event'] === 'push') {
    const repo = await store.findOne({
      id: mapGitHubRepoToStorageId(req.body.repository.full_name),
    });

    // Manually trigger a pull from GitHub
    await repo.pullUpstream();
  }
  res.status(200).send('OK');
});

Note: Use repo.pullUpstream() to trigger a sync from GitHub when handling events manually.

For more on webhook verification and validation, see Webhooks.

Option B: Let Code Storage Handle Webhooks

If you don’t want to run your own webhook handler:

• In your GitHub App settings, set the webhook URL to: https://[your-organization].code.storage/webhook/github
• Generate a webhook secret and save it.
• In the Code Storage dashboard → Integrations tab, enter your secret and save.

Support

Need help integrating? Please reach out directly to [e-mail]