Skip to main content

Connecting a Repository

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

Time: 3 minutes Difficulty: Beginner

Connect Existing Repository​

Step 1: Select Owner​

Choose the owner of the repository from the dropdown:

  • Your GitHub username (personal repositories)
  • Organizations you belong to

The dropdown shows avatars for easy identification.

Step 2: Enter Repository Name​

Enter just the repository name (not the full owner/repo format):

  • design-tokens ✓
  • myusername/design-tokens ✗

GitFig will validate the repository when you move to the next field.

Step 3: Select Branch​

Choose which branch to sync with:

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

Step 4: 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.

Step 2: Select Owner​

Choose where to create the repository:

  • Your GitHub username (personal account)
  • An organization you belong to

Step 3: Configure Repository​

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

Step 4: Create & Connect​

Click "Create & Connect". GitFig will:

  1. Create the repository on GitHub under the selected owner
  2. Add a sample-tokens.json file with example design tokens
  3. Connect the repository to your Figma file
  4. Auto-configure a mapping for the sample tokens
  5. Pull the sample tokens to create Figma Variables

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 repository dropdown (shows current repo name)
  2. Click "Disconnect"
  3. Confirm disconnection
  4. Connect to a different repository

Permissions​

GitFig needs these GitHub permissions:

PermissionWhy
repoRead/write files, create branches, create PRs
read:userRead your GitHub profile
read:orgList your organization memberships

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

Organizations not appearing in the owner dropdown​

  • Sign out and sign back in. GitFig v1.2.0 added the read:org permission. If you authenticated before this change, your token may not include this scope. Signing out and back in will request the updated permissions.
  • Ensure you have approved GitFig for your organization in GitHub Settings > Applications
  • If your organization uses SSO, you may need to authorize the token for SSO access

Next Steps​

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