1. Help Center
  2. Phrase for Developers
  3. Using version control systems with Phrase

GitHub Sync

Phrase GitHub Sync lets you sync your Phrase projects with your GitHub repositories easily.


In order to identify which locale files you want to sync with Phrase, we rely on the .phraseapp.yml configuration file being present in your GitHub repository.

The file is used by most Phrase clients and defines which files you want to import (push) and export (pull).

See the documentation to learn more about how to set up your Phrase configuration file.

Connect your project

If you have set up and uploaded your configuration file to GitHub, it’s time to connect your repository to Phrase:

  1. Go to the Project Settings of the project you want to connect and select GitHub Sync.
  2. Enable GitHub Sync and enter a valid GitHub personal access token. You can create an access token in your GitHub Settings. Make sure the access token has the repo if scope (or public_repo if you want to sync with a public GitHub repository).
  3. Select the GitHub repository you want to sync with Phrase.
  4. Select the repository’s branch used to import (push) and export (pull) your locales (usually ‘master’)
  5. Click Validate Configuration to check if your access token and the configuration file is set up correctly.
  6. Click Save.

Your project is now connected to your GitHub repository!


Importing your locale files to Phrase from your connected GitHub repository is easy:

  1. Go to the Locales section.
  2. If you haven’t created any locales yet, add at least your default locale.
  3. Click GitHub Sync > Import from GitHub
  4. Your locale files (defined as push source entries in your configuration file) are now imported into your Phrase project. This can take a few seconds and you will see the status as new updates in your project’s activity stream.


You can also import your locales to Phrase after every commit to GitHub with Auto-Import:

  1. Go to your project’s settings in Phrase and select GitHub Sync.
  2. Enable the auto-import option.
  3. Generate a payload URL and copy it. Please note that this will automatically generate a Phrase access_token that can be managed in your Profile Settings
  4. Click Save.

Next, add a webhook to your GitHub repository in order to notify Phrase of new pushes:

1. Go to your GitHub repository’s Settings section and select Webhooks & services

2. Add a new webhook:

  • Payload-URL: Paste your generated payload URL. 
  • Content-Type: application/json
  • Secret: leave blank
  • Let the webhook trigger just the push event

3. Click Add webhook

You have successfully activated Auto-Import for your Phrase project and we will import locale files from your repository after every update pushed to the selected branch (usually ‘master’) of your repository.


Exporting the most recent locale files to your repository is just one click away:

  1. Go to the Locales section.
  2. Click GitHub Sync > Export to GitHub as pull request
  3. After a few seconds, your most recent locale files are exported to your GitHub repository as a new pull request. You will see this as an update in your project’s activity stream, too.

You can now head over to your Github repository in order to merge (or close) the pull request. Don’t forget to delete the branch after that.


Why a pull request?

We’re delivering locale file updates as pull requests so that you can review all changes and thus remain in charge of what actually goes into your selected branch (usually ‘master’).

Github Enterprise

Github Sync also supports Github Enterprise. To sync with a self-hosted Github Enterprise instance you need to enable Github Enterprise in the project settings and add the API URL to an Enterprise instance. Please make sure that the API endpoint is publicly reachable from Phrase.



The validation fails although the configuration file seems correct, what's wrong?

Make sure you have set up at least one push source and one pull target entry in your configuration file. Double-check if you have entered a valid Project ID and that the Project ID belongs to the Phrase project you want to sync your files with.

Why does nothing gets imported?

Please make sure that your .phraseapp.yml configuration file contains valid push sources. Note that a lot of file formats require the locale_id to be defined for each source since they don’t contain any information on the locale in the file itself.

You can always use the Phrase Client in order to check if your configuration file behaves as you expect.

Why does auto-Import not work?

Go to your GitHub repository’s Settings section of the project you have enabled auto-import for and select Webhooks & services. Click on the webhook you’ve added in order to notify Phrase about changes. Make sure you have entered the correct Payload URL and it contains the valid Project ID and access token.

You can also examine the most recent deliveries for each webhook and check out the response for error messages returned by Phrase.

Why does "Export as pull request" not work?
For the pull request to work, you have to check if the user who created the access token has the full repo scope. Also , if you have enabled SSO for your GitHub, you also have to make sure that SSO is enabled for the token as shown here: https://help.github.com/en/articles/authorizing-a-personal-access-token-for-use-with-a-saml-single-sign-on-organization.

It still doesn’t work?

Contact us — we’re happy to help.

Further reading