Skip to main content

Connecting a Repository

This guide shows how to connect a GitHub repository to your Figma file for Design Sync.

Time: 3 minutes Difficulty: Beginner

Connect Existing Repository​

Step 1: Enter Repository​

In the GitFig panel, enter your repository in the format owner/repo:

  • myusername/design-tokens - Personal repository
  • myorg/design-system - Organization repository

Enter Repository

note

Enter just owner/repo, not the full GitHub URL.

Step 2: Select Branch​

Choose which branch to sync with:

Select Branch

  • main - Recommended for production tokens
  • develop - For in-progress work
  • Or select any other branch

Step 3: Click Connect​

Click "Connect" to establish the connection.

GitFig will verify access and save the connection. You'll see a success message and the repository info in the panel.

Create New Repository​

Don't have a repository yet? Create one directly from GitFig:

Step 1: Switch to "Create New" Tab​

Click the "Create New" tab in the connection dialog.

Create New Tab

Step 2: Configure Repository​

FieldDescription
Repository nameName for the new repo (e.g., design-tokens)
DescriptionOptional description
VisibilityPublic or Private

Step 3: Create & Connect​

Click "Create & Connect". GitFig will:

  1. Create the repository on GitHub
  2. Initialize it with a README
  3. Connect it to your Figma file

Repository Requirements​

For GitFig to work properly, your repository needs:

Minimum Requirements​

  • ✅ Read access (to pull tokens)
  • ✅ Write access (to push tokens)
  • ✅ At least one branch (usually main)
your-repo/
├── tokens/
│   ├── colors.json
│   ├── typography.json
│   └── spacing.json
├── README.md
└── package.json (optional)

One Connection Per File​

Each Figma file can connect to one repository at a time. The connection is stored per-file, so different Figma files can connect to different repositories.

To change the connected repository:

  1. Click the settings icon (⚙️)
  2. Click "Disconnect"
  3. Connect to a different repository

Permissions​

GitFig needs these GitHub permissions:

PermissionWhy
repoRead/write files, create branches, create PRs
user:emailIdentify commits with your email

If you're connecting to an organization repository, you may need:

  • Organization membership
  • Repository access granted by an admin

Troubleshooting​

"Repository not found"​

  • Check the format is owner/repo (no .git, no full URL)
  • Verify you have access to the repository
  • For private repos, ensure your token has repo scope

"No branches found"​

  • The repository might be empty
  • Create an initial commit with a README

"Permission denied"​

  • You may need write access to the repository
  • Ask a repository admin to grant access
  • For organization repos, check if SSO is required

Next Steps​

After connecting, configure your file mappings to define which JSON files sync with which Figma elements.