How to sync design tokens from Specify to GitLab

Specify helps you collect design data from Figma and distribute it in the right format, in the right project, at the right time, and to top it all: automatically.

In this article you'll learn how to synchronize design tokens from Specify to your GitLab repository.

We're about to sync design tokens as CSS Variables. Looking for another output format? Feel free to check all our other configuration templates (React Native, CSS, Tailwind...) and you can find our full parser list here.

We will use the Specify CLI inside GitLab CI/CD.

Prerequisites

Please make sure you have:

• A Specify repository containing design tokens

• A working Specify CLI config

• A GitLab account

The workflow

We will pull design tokens and assets from several Specify repositories and generate them as CSS Variables in a single GitLab repository thanks to the Specify CLI.

Design tokens from 3 Specify repositories generated by the Specify CLI inside an GitLab repository.

We'll setup a GitLab workflow that does 2 jobs:

1. Generate design tokens on a branch called specify

2. Create a merge request from the specify to the main branch

Generating design tokens

1. Fork this GitLab repository

2. Generate public and private SSH keys. We need them to authorize the CI machine to push to your GitLab repository

3. Generate a Specify personal access token from your user settings

Create SSH private and public keys

GitLab CI/CD consists in creating a series of actions called Jobs a virtual machine will execute.

Our first job does the following:

1. Authorizes our virtual machine to push to our GitLab repository by setting SSH private and public keys (see code)

2. Installs the Specify CLI (see code)

3. Executes Specify and generates design data (see code)

4. Push to the specify branch (see code)

Generate SSH private and public keys

Generate your SSH private and public keys: ssh-keygen -t ed25519 -C "gitlab-ci-ssh-key"

Advice: When you're prompted to "Enter a file in which to save the key" name your file id_gitlab so you don't override a potential existing file already named ed25519.

Add them in GitLab

Add public key to your GitLab user settings.

Now add your private and public keys in your GitLab repository CI/CD variables:

1. For each of them, go to your folder containing your SSH keys and copy their value in base64

2. Run cat id_gitlab | base64 | pbcopy to copy your private key

3. Run cat id_gitlab.pub | base64 | pbcopy to copy your public key

4. Add each of them with their respective variable name set in .gitlab.ci.yml: SSH_PRIVATE_KEY and SSH_PUBLIC_KEY.

5. For each of them disable the "Protect variable option" and enable "Mask variable".

Don't forget to delete your private and public SSH keys on your machine. Now they are encoded in base64 in our GitLab repository CI/CD variables we don't need them anymore.

Add your Specify personal access token in your CI/CD variables

Set your Specify personal access token as a CI/CD variable named SPECIFY_TOKEN (Settings > CI/CD > Variables).

Several SSH private keys and a Specify personal access token set as GitLab CI/CD variables

Testing our design tokens generation

Before we see how to create a merge request let's test our generate_design_tokens job.

The following code in .gitlab.ci.yml sets our generate_design_tokens job to only run every X time:

generate_design_tokens: 
  only

Now, let's define a CRON job in your GitLab repository CI/CD settings that will run our generate_design_tokens job:

An example GitLab CI/CD schedule called 'Generate design tokens' that runs every day.

Need help writing a CRON expression? Check these examples ⚡️

Now run your newly pipeline by hitting the "▶️ Play" button.

You should see a job called generate_design_tokens running in your Jobs page:

Now our generate_design_tokens job has passed, let's generate a merge request on the main branch.

Creating the merge request

Now we have pushed our design tokens on the specify branch we need to merge it on the main branch.

We handle this via the "create_merge_request" job in the .gitlab-ci.yml file.

This job runs a create_merge_request.sh file which uses the GitLab API to create a merge request on your GitLab user behalf.

As we're using the GitLab API we need to set a personal access token:

1. Go to your Access Tokens settings

2. Generate a new personal access token (e.g., "GitLab API") and check api in the permissions scope

3. Copy it

4. Add it in your GitLab repository CI/CD variables. Name it GITLAB_PRIVATE_TOKEN. Disable the "Protect variable option" and enable "Mask variable"

An example personal access token set as a GitLab CI/CD variable

Now go back to your Schedules page and run your "Generate design tokens" schedule by hitting the "▶️ Play" button again.

Our 2 jobs generate_design_tokens and create_merge_request will be exectued one after the other and you should get a new merge request created containing your design tokens.

In summary

We just pulled design tokens from several Specify repositories to our GitLab repository.

We used the Specify CLI inside GitLab CI/CD to generate design tokens on a branch called specify. Then, we used the GitLab API to create a merge request from the specify branch to the main one.

Now, every time your design data is updated on Specify, you'll receive an automated merge request on your GitLab repository ⚡️