GitHub Sync

Freestyle provides bidirectional synchronization between your repositories and GitHub, allowing you to maintain synchronized code across both platforms.

How It Works

When you push code to either platform, changes are automatically synchronized to the other. Freestyle uses GitHub Apps to provide secure, repository-specific access and prevents data loss by detecting diverged branches before applying changes.

Setup Process

Step 1: Create a GitHub App

Navigate to the Git > Sync section in your Freestyle Admin Dashboard and click "Create GitHub App".

Choose a custom name for your app and click "Create App". You'll be redirected to GitHub to confirm, then back to Freestyle where your credentials are automatically stored.

You can also bring your own GitHub App by clicking the dropdown and selecting "Use Existing App". You'll need to provide the App ID and Private Key.

Step 2: Install the App

The GitHub App must be installed on repositories you want to sync.

From the sync page, click "Install on GitHub" and choose which repositories to grant access to. You can grant access to all repositories or select specific ones.

For app builders: Share your GitHub App's installation page URL with users so they can install it on their repositories.

Linking Repositories

Once your GitHub App is installed, you can configure repository synchronization.

Via Admin Dashboard

1. Navigate to Git > Repositories
2. Select the Freestyle repository
3. Click "Configure GitHub Sync"
4. Choose the corresponding GitHub repository
5. Save the configuration

Via SDK

Configure sync programmatically using the repository instance.

import { freestyle } from "freestyle-sandboxes";

const { repo } = await freestyle.git.repos.create();

// Note: GitHub sync configuration is done via the API endpoint directly
// The GitHub repository must have your GitHub App installed

Currently, GitHub sync configuration is done via the API endpoint. See the GitHub Sync Configuration API Reference for details.

Getting Sync Configuration

Check if a repository has GitHub sync configured.

const syncConfig = await repo.getGitHubSyncConfig();
if (syncConfig) {
  console.log(`Synced with GitHub: ${syncConfig.githubRepoName}`);
}

Sync Behavior

Automatic Triggers

Synchronization happens automatically when you push to either repository, including branch operations like creation, updates, and deletions.

What Gets Synced

• All branches: Including main, feature branches, and release branches
• Commit history: Complete Git history is preserved
• Tags: Git tags are synchronized between repositories
• Branch deletions: Removing branches on one side removes them on the other

Conflict Handling

When conflicts are detected, Freestyle prioritizes data safety and will not automatically merge conflicting branches. Conflicts can be viewed in the admin dashboard and must be resolved manually in either repository. Once resolved, sync resumes automatically.

Freestyle never force pushes or overwrites branches to prevent data loss.