Bitbucket sync setup guide

Bitbucket is a Git-based source code repository hosting service popular among teams using Atlassian tools.

You can use the Tokens Studio plugin native integration with Bitbucket to sync your design tokens to a repository of your choice.

We support bi-directional sync, meaning you can use the plugin to:

• push JSON files full of design tokens to Bitbucket
• pull the tokens stored in Bitbucket into any Figma file

This means the design tokens living in code are the source of truth for our design decisions, which can be shared between design and development teams.

This document outlines how to set up a Bitbucket repository and add it as a Sync provider in the plugin.

How it works#

• Set up a repository and an app password in Bitbucket.
• Configure Bitbucket as a sync provider within the Tokens Studio plugin.
• Seamlessly sync your design tokens between Figma and Bitbucket to maintain consistency across design and development workflows.

Bitbucket setup instructions#

If you haven't already, sign up for a Bitbucket account at https://bitbucket.org/

1. Create a new repository#

Sign into your account and select the Create button, and select Repository.

• Choose a specific and memorable repository name which will be used in the plugin as the destination for your design tokens.
• Review the options, learn more about those in the Bitbucket docs.
  • Add a README file needs to be checked
    • This is mandatory because the plugin can not sync to an empty repository.
  • The other options are up to you.

You are now looking at your new repository! Well done!

2. Generate an app password#

Navigate to your Bitbucket account settings.

• Locate the Personal settings section, select Personal Bitbucket settings
• Select App passwords.
• Select Create app passwords
• Add a Name of what the app password is for
  • Example: test-token repo sync to tokens studio
• Select the permissions for app passwords
  • Account = Read
  • Repositories = Write
• Select the Create button
• The page will display the New app password dialog

Copy the generated token and store it securely, as you will need it to configure the connection with the Tokens Studio plugin.

• Copy your Bitbucket username alongside the app password, as it's required to authenticate your Bitbucket account.

Plugin settings for Bitbucket#

In Figma, open up the Tokens Studio plugin and navigate to the Settings page using the navigation tab.

• Under the Sync providers section, select the Add new button to see a list of all token storage providers.
• Select Bitbucket

3. Add new credentials for Bitbucket#

You'll need the information saved from the steps above to complete the sync configuration form.

Name#

This is a nickname that shows up in the plugin settings page later on to identify this specific sync provider configuration.

• Choose something memorable to you and your project.
• Example: radix ui components

Bitbucket username#

The username of your Bitbucket account is used as a part of the authentication process between the plugin and Bitbucket.

App password#

The App password you created and saved from the steps above.

Repository (owner/repo)#

When you created the repository from the steps above you chose a certain name. It's now time to fill this in.

• The owner/repository details for this input it in the URL after the bitbucket.org/
• For example, if my URL says https://butbucket.org/amazingdesigner/radixtokens I am going to enter:
  • amazingdesigner/radixtokens

Branch#

Your engineers might tell you what respository branch to add here, but if you followed the steps above exactly, your repository was created with main as the "primary branch".

• So you will enter main (unless you need a different branch specified by your engineers)
• You can create additional branches using the plugin later

File Path or Folder#

Here, we are telling the plugin how to organize our tokens in Bitbucket.

• While this does not impact how we work in the plugin, it makes a difference for engineers consuming our tokens.

File Path#

• file would take all our tokens sets and combine them into a single JSON file.
  • If we enter tokens.json
    • a file called "tokens.json" would be created in our Bitbucket repository
    • all tokens we create in the plugin will be synced in this one file.

Folder Path#

• folder would have each token set in its own JSON file saved to this folder.
  • If we enter tokens
    • a folder called "tokens" would be created in our Bitbucket repository
    • each token set we create in the plugin would live in that folder.
  • This "multi-file sync" option is a Pro feature and requires a paid licence to Tokens Studio.
  • If you are using the Themes feature, and your engineers will transform your tokens with Style Dictionary to use in code, you want this option.

This setting also has some impact on teams using Tokens Studio where not all team members are on the Pro licence. If someone does not have a Pro licence, they will only be able to read from your tokens, not write changes back.

4. Save and do the initial sync#