GitHub Synchronization

Freestyle provides seamless bidirectional synchronization between your Freestyle repositories and GitHub repositories. This integration allows you to maintain synchronized code across both platforms while leveraging Freestyle's infrastructure capabilities alongside GitHub's collaboration features.

Overview

The GitHub sync feature enables you to:

• Automatically sync changes between Freestyle and GitHub repositories
• Leverage GitHub workflows on the Github side while using Freestyle's infrastructure
• Collaborate on GitHub your users' teams can continue to use Github without interruption while you utilize Freestyle's infrastructure
• Avoid conflicts with intelligent conflict detection

How It Works

Freestyle's GitHub integration uses GitHub Apps to provide secure, repository-specific access. When you push code to either platform, changes are automatically synchronized to the other, ensuring both repositories stay in sync.

Architecture

1. GitHub App: You own the custom Github app with repository permissions for secure access to the repositories on Github
2. Webhook Processing: You get real-time notifications when code changes occur on Github or on Freestyle
3. Bidirectional Sync: When a change is made on the Github repository, its proactively synced to the Freestyle repository, and vice versa
4. Conflict Detection: We prevents data loss by detecting diverged branches before applying changes

Setup Process

Step 1: Create a GitHub App

1. Navigate to the Git > Sync section in your Freestyle Admin Dashboard
2. Click "Create GitHub App"
3. Choose a custom name for your GitHub App (this will be visible to users when they install it)
4. Click "Create App" - you'll be redirected to GitHub to confirm app creation
5. After confirming on GitHub, you'll be redirected back to Freestyle where your app credentials are automatically encrypted and stored

Step 2: Configure App Settings (Optional)

You can customize your GitHub App settings if needed:

1. From the sync page, click "Configure on GitHub" or navigate directly to your app on GitHub
2. Update App Name, Homepage URL, or Description as desired

Step 3: Install the App

To sync repositories, the GitHub App must be installed on the repositories you want to sync:

For App Builders: You'll need to have your users install your GitHub App on their repositories. Each user must install the app to enable sync with their own repos.

Installation Process:

1. From the sync page, click "Install on GitHub" or go to your GitHub App's page
2. Click "Install" (or "Configure", if already installed)
3. Choose which repositories or organizations to grant access to:
   • All repositories: Grants access to all current and future repos
   • Selected repositories: Choose specific repositories to sync

Sharing with Users: You can share your GitHub App's installation page with users by providing them with the app URL from your GitHub App settings.

Repository Configuration

Once your GitHub App is installed on the target repositories, you can configure repository synchronization:

Linking Repositories

Via Admin Dashboard

1. In your Freestyle admin dashboard, navigate to Git > Repositories
2. Select the Freestyle repository you want to sync
3. Click "Configure GitHub Sync"
4. Choose the corresponding GitHub repository from the repositories where your app is installed
5. Save the configuration

Via API

To configure sync programmatically, you can use the GitHub sync endpoint or our SDK.

const freestyle = new FreestyleSandboxes({
  apiKey: process.env.FREESTYLE_API_KEY!,
});

// Configure GitHub sync for a Freestyle repository
// The GitHub repository must have your GitHub App installed
await freestyle.configureGitRepoGitHubSync({
  repoId: "your-freestyle-repo-id", // The ID of the Freestyle repository to sync
  githubRepoName: "user/repo-name", // The full name of the GitHub repository (e.g., "user/repo")
});

Python SDK does not yet support GitHub sync configuration. Please use the JavaScript SDK or the API directly for now.

For complete API documentation on configuring GitHub sync, see the GitHub Sync Configuration API Reference.

Sync Behavior

When repositories are linked, synchronization happens automatically:

Automatic Sync Triggers

• GitHub → Freestyle: Triggered when you push to GitHub
• Freestyle → GitHub: Triggered when you push to your Freestyle repository
• Branch Operations: New branches, branch deletions, and updates

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

Sync Process Details

Bidirectional Synchronization

Freestyle's sync engine performs intelligent bidirectional synchronization:

1. Fetch Updates: Retrieves all changes from both repositories
2. Analyze Branches: Checks each branch for conflicts or divergence
3. Fast-Forward Merges: Applies updates where branches haven't diverged
4. Conflict Detection: Identifies branches that have conflicting changes
5. Safe Updates: Only applies changes that won't cause data loss

Conflict Handling

When conflicts are detected, Freestyle prioritizes data safety:

• No Automatic Merges: Conflicting branches are not automatically merged
• Conflict Detection: Conflicts can be viewed in the admin dashboard
• Manual Resolution: You can resolve conflicts manually in either repository
• Resume Sync: Once conflicts are resolved, sync resumes automatically

Branch Management

The sync engine handles various branch scenarios:

• New Branches: Created on both repositories when added to either side
• Updated Branches: Fast-forwarded when no conflicts exist
• Deleted Branches: Removed from both repositories when deleted from either side
• Diverged Branches: Requires manual resolution, we never force push or overwrite branches.