Syncing with a repository
Syntope Tokens links a Figma file to a Git repository on GitHub, GitLab or Bitbucket Cloud. The repository is the source of truth. The plugin pulls the complete project as DTCG files and pushes it back as a commit. It talks to your Git host directly, with no Syntope server in between (Data and storage).
Partial: the plugin does not merge, and cancelling or undoing a pull weakens the check that protects the repository from being overwritten.
Connect
Open Settings in the footer, go to sync provider, and choose add sync provider. A file has one connection. Change it later with edit, or remove it with disconnect.
| Field | Value |
|---|---|
| provider | GitHub, GitLab or Bitbucket |
| display name | Any label |
| Repository | The format in the table below |
| branch | Default main. It must exist, unless the repository is empty |
| storage | project JSON file or project folder, see Storage |
| file path or folder path | From the top of the repository, with no / at the start or end. A file path must end in .json, a folder path must not |
| personal access token | See the table below |
| Provider | Repository field | Example | Token |
|---|---|---|---|
| GitHub | repository (owner/name) | organization/design-tokens |
Fine-grained personal access token with Contents read and write on that repository |
| GitLab | project ID or namespace/path | group/design-tokens |
Personal access token with the api scope |
| Bitbucket Cloud | repository (workspace/name) | workspace/design-tokens |
API token with scopes for the app Bitbucket: read:repository:bitbucket and write:repository:bitbucket |
save connection checks the repository, branch and path before it saves. If that place already holds a project when you first connect, the plugin offers pull now.
Self-hosted Git servers are not reachable, because the plugin may only connect to these three services. Use an export and commit the files yourself.
Storage
| storage | What the repository holds |
|---|---|
| project JSON file | One bundled DTCG Resolver file at the path. Default design-tokens.resolver.json |
| project folder | The Resolver file in the folder, plus one file per token set. Default folder tokens. An empty path means the top of the repository, which works only if the repository holds no other .json file |
With the folder design/tokens and a token set primitives/color:
design/tokens/design-tokens.resolver.jsondesign/tokens/tokens/primitives/color.tokens.jsonIn a project folder, a push changes only the Resolver file and the .tokens.json files below that tokens folder, and deletes any .tokens.json file there that is not a set of the project. Other files stay untouched. A pull reads every .json file in the folder and below it and stops if one is not part of the project, so use a folder that holds only token files.
If the place holds a Tokens Studio export, pull converts it as import does. Push refuses to write into it, leaves it as it is, and tells you where to connect instead.
First push into an empty repository
The connection shows Ready to create. Choose push.
- GitHub: the first commit goes to the repository’s default branch. If branch names another branch, the plugin creates it at that commit and adds the remaining files there.
- GitLab and Bitbucket Cloud: the commit creates the named branch.
A place that is empty in a repository with commits also shows Ready to create. There, the branch must already exist.
Pull
Choose pull, or the refresh icon in the footer. The plugin reads the complete project from the branch and opens the import review. Nothing is saved until you confirm.
Pull replaces, it does not merge
Importing replaces your current tokens and themes with this file. If that removes tokens, sets or themes, the plugin lists them, counts the affected layers and asks you to confirm with replace. Layers bound to a removed token keep a broken link. Undo in the plugin header restores the previous project while the plugin stays open. Export first if the file holds work you want to keep.
Bindings stay connected for tokens that still exist at the same set and path.
Push
push writes the saved project to the branch as one commit with the message Update design tokens via Syntope Tokens. On GitHub, the very first push into an empty repository can make two. The plugin never force-pushes. Unsaved JSON drafts are not included.
Token sets you deleted are removed from the repository. Broken references are pushed as written, and the notice says so. Repair them first: another Figma file cannot pull or import these files until the references resolve. If nothing differs you get The remote project already matches your tokens.
A push is an ordinary commit. To take it back, revert it in Git.
When the repository has changed
| Situation | What happens | What to do |
|---|---|---|
| The place holds a project you have not pulled into this file (Remote project found) | overwrite remote project? | pull first, or overwrite remote to replace it with your tokens |
| The branch has a new commit since your last pull or push | Push stops: Someone changed … since your last pull. Pull to get their changes, then push again. | pull latest |
| The connection dropped during a push | The plugin cannot tell whether it arrived | retry. It checks the repository first and won’t push twice |
Once a project has been pulled or pushed, the check covers the whole branch, so an unrelated commit, such as a README change, also stops a push.
The plugin does not merge. After pull latest, your project equals the repository’s. To combine work, redo your edits after the pull, or export your project first and merge the files in Git.
Cancelling or undoing a pull
Pull records the remote revision before you confirm the review. If you cancel the review, if the review refuses the file, or if you undo the pull, the next push replaces the remote project without the overwrite dialog. Do not push until a pull has been imported, or stay on a working branch.
If your team reviews changes through pull requests, point the connection at a working branch and merge it in your Git host.
Credentials
The token stays on this computer, in Figma’s client storage, stored per connection. It is never written to the Figma file or to the repository, and it is sent only to the provider, over HTTPS. The plugin does not encrypt it. Use a token limited to one repository, with an expiry date.
The rest of the connection (provider, repository, branch, path, last revision) is saved in the Figma file, so it travels with the file. Each computer that pulls or pushes needs the token once. Anyone else can edit tokens in the file without Git access. Until then the connection shows Credential required: choose edit and paste it. Leave the field blank to keep a saved token. Switching provider needs a new one.
disconnect removes the connection and this device’s token. It does not change the repository or your tokens.
Error messages and their fixes are in Troubleshooting.