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
Go to the repository you want Specify to have access to
Go to the Destinations page
Click on "Create pipeline"
Select GitHub in the destinations
Click on "Connect account" and follow the directions.
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.
Go to the Destinations page of your repository
Click on "Create Pipeline"
Select "GitHub application"
Select your GitHub account
Select the GitHub repository you want to distribute design data to
Name for your configuration file (Learn More βοΈ)
Create the Pull Request containing your default configuration file
Merge the PR created by Specify containing your configuration file
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.