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 a Repository​

The Connect Repository screen is one form with three rows: Owner, Repository, and Branch. It handles both an existing repository and a new one; there is nothing to choose up front.

Step 1: Check the Owner​

The Owner row is prefilled with your GitHub account. Open it to pick an organization instead; avatars help you tell them apart. Changing the owner clears the Repository field and loads that owner's repositories.

Step 2: Pick or Type the Repository​

The Repository field is focused when the screen opens. Start typing, or open the list with the down arrow:

  • The list shows every repository the owner has (most recently updated first), filtered as you type. It fills in while GitHub is still sending pages, so you never have to wait to start typing.
  • Choose a repository with the mouse, or use the arrow keys and Enter. Escape closes the list without clearing what you typed.
  • Enter just the repository name, not owner/repo:
    • design-tokens ✓
    • myusername/design-tokens ✗

When the name matches a repository, GitFig checks it and the Branch row appears with the default branch selected. Pick another branch if you like.

Step 3: Connect​

Click Connect. GitFig saves the connection and shows the repository in the panel. The button stays gray until a repository has been checked.

Create a New Repository​

Don't have a repository yet? Type the name you want in the Repository field. If no repository has that name, the last row of the list reads Create "your-name" (when the field is empty it reads Create a new repository). Choose it and the form switches to create mode in place:

FieldDescription
VisibilityPrivate (default) or Public
Will createA preview of owner/name as GitHub will store it; spaces and other disallowed characters become hyphens

Press Cancel to go back to connecting an existing repository; the name you typed stays in the field.

Create and connect​

Click Create and connect. The button reports each step (Creating repository, Adding starter files, Connecting) while GitFig:

  1. Creates the repository on GitHub under the selected owner
  2. Adds four starter files: tokens/primitives.json, a light/dark tokens/semantic.json, tokens/color-styles.json, and tokens/text-styles.json (the variable-modes example)
  3. Connects the repository to your Figma file
  4. Configures a mapping for each file (Variables for the first two, Semantic as All modes; Color styles and Text styles for the others)
  5. Pulls all four to create the Primitives and Semantic collections and the six styles

If the repository is created but connecting fails, the form switches to Connect with the new repository already selected, so trying again never creates a second repository.

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 Repository in the header
  2. Choose Disconnect and confirm
  3. Connect 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​

"No repository named ..."​

  • The list shows only repositories this GitHub account can see under the selected owner. Check the owner, or ask for access.
  • Enter just the name (no owner/, no .git, no full URL)
  • For private repos, ensure your token has repo scope
  • If the repository does not exist yet, choose Create at the bottom of the list

"This repository has no branches yet"​

  • The repository is empty
  • Push a first commit (a README is enough), then connect

"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.