Use Git with Figma Make and code layers

The best way to use your own code with code layers and Figma Make is by cloning repositories hosted on GitHub. After connecting Figma to one or more GitHub organizations or accounts, you can select a repository to clone for your code layer or Make. Figma stores the clone of your repository so you can make changes, utilize multiple branches so you can experiment, and then create pull requests to merge your improvements back into the original repository.

Get started

To get started, you need to:

1. Make sure Figma is connected to one or more GitHub organizations or accounts. Connecting Figma to GitHub is a step that must be performed by a Figma organization administrator.
2. Have a GitHub account. If you don’t already, you’ll need to create a GitHub account and make sure it belongs to one or more of the GitHub organizations connected to Figma.
3. Authorize your GitHub account with the Figma GitHub app. Authorizing your account lets you trigger actions in GitHub from Figma.
4. Clone a repository for a code layer or Figma Make file. When Figma is connected to GitHub, you’ll be able to select a repository you have access. The steps are slightly different depending on whether you start in Figma Design (code layers) or Figma Make.

After you’re set up to work with a cloned repository, you can:

1. Start working in a branch. After one of your repositories is cloned for a code layer or Figma Make file, you can create branches to work in. You can start experimenting and building in the default branch that you cloned, or create additional branches to try different variations.
2. When you’re happy with the improvements you made, you can push your changes or open a pull request to merge the code from the code layer or Make back into the original repository you cloned.

You can also clone a public repository via URL without connecting a Figma organization to or authorizing your account with GitHub.

Connect to GitHub

You connect to GitHub using the Figma GitHub app, which facilitates interactions between Figma and GitHub. There are two types of connections needed:

• A Figma organization or Professional team admin needs to connect Figma to a GitHub organization. Figma Organization and Enterprise plans can connect to more than one GitHub organization.
• You need to authorize the Figma GitHub app with your personal GitHub account so you can trigger actions in GitHub. This is different than the admin step, which is connecting Figma and GitHub on the organizational level.

Connect a Figma organization to GitHub

You can connect one or more GitHub organizations or accounts to Figma. Setting up the Figma GitHub app requires:

• A Figma organization administrator to initiate connecting the Figma GitHub app, select repositories, and enable those repositories for use with code layers and Figma Make.
• A GitHub organization administrator to review the authorization request for the Figma GitHub app and approve it.

A Figma organization administrator and GitHub organization administrator can be the same person, but it’s not a requirement. If the same individual is an admin for both a Figma organization and the GitHub organization that’s being connected, they can skip the request for authorization and go right to approving the Figma GitHub app for the organization.

The admin steps are detailed in Manage the Figma GitHub app for a team or organization.

Authorize your user account

To connect your account to GitHub and authorize the Figma GitHub app:

1. In the code editor for a code layer or in Figma Make, under the prompt box, click Clone repository.
2. Below the Clone remote repository modal, click Connect to GitHub. A new browser tab opens for GitHub.

3. In GitHub, click Authorize to connect your account. When you click Authorize, you’re sent back to Figma.

   Note: If you have multiple GitHub accounts you switch between, GitHub will ask you to choose the account you want to authorize. You can authorize only one of your user accounts.

4. In Figma, click Next.

Your account is now authorized and you’re ready to clone repositories.

Why could authorization fail?

If you can’t authorize your account, these issues might be related:

• You don’t have a GitHub account or you’re not logged into your account. To use git with code layers and Figma Make, you need to create a GitHub account.
• Your GitHub account isn’t included in any of the connected GitHub organizations. Talk to one of your GitHub administrators to have your GitHub account added to a GitHub organization.

Clone a repository

The exact steps you take to clone a repository depend on whether you’re working on a code layer in Figma Design or in Figma Make. Cloning is the act of getting a repository from GitHub and creating a copy of it in Figma. The copy is what backs your code layer or Make.

Visibility

When you clone a repository for a code layer or Make file, the source code you clone becomes visible to other users of the file. Anyone with permission to view a Figma Design file that contains a code layer can see the preview of that code layer and the preview’s source code. Anyone with permissions to edit the Figma Design file that contains a code layer or a Make file can see the underlying git-level source code, even if they don't have permissions in GitHub to do so.

Clone a repository for a code layer

Steps for code layers:

1. In Figma Design, press B or select Code in the toolbar.
2. In the properties panel on the right, in the Code layer section, click Clone repository.
3. Select the repository you want to use for your code layer.
4. Optionally, select a specific branch you want to clone from. By default, Figma selects the main branch of a repository. However, you may occasionally want to work on code in a different existing branch.
5. Click Clone. Wait while the code layer is configured. It may take several minutes depending on the size and complexity of the repository you selected.
6. Occasionally, the Figma agent may need to make small tweaks to the cloned code to ensure it can run in the code layer. The agent will prompt you when it needs permission to make the tweaks or if it has questions.

Clone a repository for a Make

Steps for code layers:

1. Create a Figma Make file and, below the initial prompt box, click Clone from GitHub.
2. Select the repository you want to use for your Make.
3. Optionally, select a specific branch you want to clone from. By default, Figma selects the main branch of a repository. However, you may occasionally want to work on code in a different existing branch.
4. Click Clone. Wait while the agent in Figma Make sets up the file. It may take several minutes depending on the size and complexity of the repository you selected.
5. Occasionally, the Figma agent may need to make small tweaks to the cloned code to ensure it can run in the code layer. The agent will prompt you when it needs permission to make the tweaks or if it has questions.

Why don’t I see any repositories?

There are several reasons why you might not see any repositories:

• Figma isn’t connected to GitHub yet: Ask a Figma organization admin to confirm Figma is connected to GitHub
• No repositories are enabled for cloning in Figma: Make sure the Figma org admin enables cloning for the repositories you need
• You don’t have access to any repositories in the GitHub organization that have been enabled for cloning: Talk to one of your GitHub administrators to get access to repositories in GitHub. Once you have access, those repositories should show up in Figma.
• You need to switch GitHub organizations: If your Figma organization is connected to multiple GitHub organizations, you may need to switch to a different GitHub organization. You may not have access to all repositories in all connected GitHub organizations. To switch GitHub organizations:
  1. After you click Clone repository, in the Clone from GitHub tab of the modal that appears, click Change organization.
  2. Select a different organization from the list.
• Figma is connected to a GitHub user account instead of a GitHub organization, and all the repositories enabled for cloning are private: Repositories in a GitHub user account can be public or private. If a repository is private, that means it can only be accessed by the user it belongs to. If Figma is connected to a GitHub user account and the repositories that are enabled for cloning are set to private in that user’s GitHub account, they won’t show up for you in Figma because you don’t have access.

Work in branches

When you’re working with code, it’s good practice to work in branches. Branches let you maintain different versions or states of your code layer or Make without overwriting previous work you’ve done or work that’s happening outside of Figma.

Your code layer or Make starts on the branch you selected when you cloned a repository. You can continue to work in this branch, but it means changes you make can get applied directly back to the source repository you cloned from when you push.

A safer way to work is to create a branch before you start making changes. That keeps the original branch you cloned unchanged while you experiment and iterate. When you’re ready, you can then merge your changes back into the original branch.

Create a branch

To create a branch:

1. In the code editor, under the prompt box, click the current branch.
2. Click Create branch.
3. Enter a name for the branch. It’s good practice to name these branches based on the feature you’re working on (login-flow/new-sign-up-modal) or with a username (mwilliams/login-flow-sign-up-modal). The latter is helpful if multiple people are creating branches in the same code layer or Make.
4. Select the existing branch you want to base the new branch on. You can base new branches on other branches you previously created.

Switch branches

To switch to a different branch:

1. In the code editor, under the prompt box, click the current branch.
2. Select the branch you want to switch to.

Depending on the complexity and scope of differences between your current working branch and the one you select, it may take a short time to switch and rebuild the preview.

Merge your code

When you’re done making changes in your code layer or Make, you can merge those changes back to the repository you originally cloned. There are a couple ways to do this:

• If you’re working in the branch you selected when you first cloned the repository, you can push the changes directly back to the same branch in the original repository
• If you’re working in a different branch than the original, you can create a pull request to merge the code

Push your changes

To push changes from your branch to the original repository:

1. In the code editor, above the prompt box, click next to Create branch.
2. Click Push changes.

Depending on the complexity of the code, it may take up to a couple minutes to push your changes to the original repository.

Why can a push fail?

A push to a branch can fail for a couple reasons:

• You don’t have permission to push to the original repository. If this happens, try bringing your changes to a new branch and then create a pull request.
• The code in the corresponding branch of the original repository has changed since you cloned it. If that occurs, ask the Figma agent to pull those changes into your code layer or Make and resolve any conflicts.

Create a PR

A pull request (PR) is used to show the changes you want to bring from one branch into another. The PR can be reviewed in GitHub by you or another user. After it’s reviewed and the PR is approved, you can then finish merging your code to the original repository.

To create a PR:

1. In the code editor, above the prompt box, click Create PR. The agent creates the PR for you and GitHub opens in a new browser tab.

   Note: The Create PR button only appears if you’re working in a branch that’s different from the one you selected when you initially cloned the repository.

2. In GitHub, look over the draft PR and confirm the description and changes are what you expect. For detailed instructions about how to work in GitHub, see the GitHub documentation.

   Note: This is a basic explanation of the steps you need to take using a default repository configuration. Depending on the settings and automation for the repository in GitHub and the organization it’s in, the steps may be quite different. If you have any issues, reach out to a developer in your organization who’s familiar with the source repository.

3. Below the description of your draft PR, click Ready for review.
4. Assign reviewers for your PR.
5. When your code is reviewed, click Merge pull request at the bottom of your PR, then Confirm merge.
6. Back in Figma, confirm the PR has merged. Above the prompt box, the icon next to the PR number should now be purple.

Once you’ve merged, you can continue working in the current branch and create more PRs, switch to a different branch, or create a new branch to work in.

Clone a public repository via URL

You can clone a public repository without needing to connect Figma to GitHub or authorizing your GitHub account. If your Figma organization isn’t connected to a GitHub organization or if you’re a guest in a Figma organization or team, this is default experience.

When you’re working with a clone of public repository, you can’t push changes back to branches or create PRs.

The exact steps you take to clone a repository depend on whether you’re working on a code layer in Figma Design or in Figma Make.

Clone a public repository for a code layer

Steps for code layers:

1. In Figma Design, press B or select Code in the toolbar.
2. In the properties panel on the right, in the Code layer section, click Clone repository.
3. Under Clone remote repository, paste a URL for a public repository.
4. Click Clone. Wait while the code layer is configured. It may take several minutes depending on the size and complexity of the repository you selected.
5. Occasionally, the Figma agent may need to do make small tweaks to the cloned code to ensure it can run in the code layer. The agent will prompt you when it needs permission to make the tweaks or if it has questions.

Clone a public repository for a Make

Steps for code layers:

1. Create a Figma Make file and, below the initial prompt box, click Clone repository.
2. Under Clone remote repository, paste a URL for a public repository.
3. Click Clone. Wait while the agent in Figma Make sets up the file. It may take several minutes depending on the size and complexity of the repository you selected.
4. Occasionally, the Figma agent may need to do make small tweaks to the cloned code to ensure it can run in the code layer. The agent will prompt you when it needs permission to make the tweaks or if it has questions.