Add GitHub as a Destination

Learn how to distribute your design tokens from Specify to your GitHub repositories via automated Pull Requests.

Updated over a week ago

The Specify GitHub app helps you distribute your design tokens and assets from your Specify to your GitHub repositories. Every change detected in your Specify repository will create a Pull Request in your GitHub repository.

Please make sure you have connected your GitHub account to Specify.

How to install the GitHub app

  1. Go to the repository you want Specify to have access to

  2. Go to the Destinations page

  3. Click on "Create pipeline"

  4. Select GitHub in the destinations

  5. Click on "Connect account" and follow the directions.

  6. You will now be able to connect your Specify and your GitHub repositories together πŸŽ‰

Specify has the following permissions:

  • Read access to your GitHub repository metadata

  • Read and write access to code, issues, and pull requests

⚠️ Please keep in mind you can't connect the GitHub app to several Specify organizations.

How to connect your Specify and your GitHub repositories?

Once you've connected your GitHub account, Specify has to know what design tokens to synchronize and how.

  1. Go to the Destinations page of your repository

  2. Click on "Create Pipeline"

  3. Select "GitHub application"

  4. Select your GitHub account

  5. Select the GitHub repository you want to distribute design data to

  6. Name for your configuration file (Learn More β†—οΈŽ)

  7. Create the Pull Request containing your default configuration file

  8. Merge the PR created by Specify containing your configuration file

  9. Specify will now automatically sync design data to your GitHub repository πŸŽ‰

By default, Specify only returns your design data as JSON. Our newly created Pull Request contains a .specifyrc.json file doing just that from what you have in Specify. However, JSON might not be what you need for your project.

πŸ‘‰ Check out our templates β†— or our documentation to create a custom configuration β†—οΈŽ that suits your needs.

What are unused pipelines?

When you connected your GitHub account, a first PR was created by Specify with a .json configuration file. As long as this PR isn't merged, your pipelines are considered "unused" as they won't be automatically updated.

You just need to merge the PR and refresh your Destinations page in Specify and voilΓ , your design tokens will be considered "active".

Having trouble getting automated Pull Requests?

Case 1: Your Specify config file is not updated on your main branch

Please make sure to update your .specifyrc.json configuration file on your main branch so your changes take effect.

Case 2: you've installed the Specify GitHub app but no Pull Request are created

Please make sure the owner of your GitHub organization validates the installation of the Specify GitHub app.

You should be able to see the app in your GitHub organizations GitHub app's listing (https://github.com/organizations/your_github_organization/settings/apps).

Case 3: Your Specify configuration file has errors

Please make sure to test your configuration with the Specify CLI beforehand. We advise you to test your configuration beforehand as you can't get any feedback from our API directly in GitHub.
​
You could also use our REST API or our CLI within a GitHub Action to get feedback from our API.

Did this answer your question?