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

GitHub Sync

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


GitHub Sync relies on the .phrase.yml configuration file being present in your GitHub repository in order to know which language files you want to sync with Phrase. This is the same file that the command-line Phrase Client uses, and it 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

Once your completed configuration file is in place, you can connect your repository to Phrase:

  1. Go to the settings for the project you want to connect and select GitHub Sync.
  2. Enable GitHub Sync and enter your GitHub personal access token. You can create an access token in your GitHub Settings. Make sure the access token has the repo scope (or public_repo if you want to sync with a public GitHub repository).
  3. Choose the GitHub repository you want to sync with Phrase.
  4. Choose the repository branch you want to import (push) from and export (pull) to. Usually, this is the “main” branch.
  5. Click Validate Configuration to check if your access token and configuration file are set up correctly.
  6. Click Save.

Your project is now connected to your GitHub repository.

Import files

To import files to Phrase from your connected GitHub repository, follow these steps:

  1. Go to the Languages section of your Phrase project.
  2. If you haven’t created any languages yet, add at least a default locale.
  3. Choose GitHub Sync > Import from GitHub.
  4. Phrase imports language files (defined as push source entries in your configuration file) into your project. This can take a few seconds. You can monitor the import progress by watching for updates in your project’s activity stream.

Turn on Auto-Import

You can use Auto-Import to automatically import files to Phrase after every commit to GitHub. To turn it on, follow these steps:

  1. Go to your project’s settings in Phrase and choose GitHub Sync.
  2. Enable the Auto-Import option.
  3. Generate a payload URL and copy it to the clipboard. This will automatically generate a Phrase access_token that you can manage in your Profile Settings.
  4. Click Save.

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

  1. Go to the settings for your GitHub repository. Then, choose “Webhooks"
  2. Add a new webhook with these settings:
  • Payload-URL: Paste the payload URL you generated here. 


  • Content-Type: application/json
  • Leave the Secret field blank.
  • Select  “just the push event” for the events to trigger the webhook
  1. Click “Add webhook.”

After setting up Auto-Import for your Phrase project, Phrase will import language files from your repository after every update pushed to the repository branch you chose (usually “main”).

Export files

To export the most recent language files to your repository, follow these steps:

  1. Go to the Languages section of your Phrase project.
  2. Choose GitHub Sync > Export to GitHub as Pull Request.
  3. Phrase exports the most recent language files to your GitHub repository as a new pull request. This may take a few seconds. You can monitor the export progress in your project’s activity stream.

Once Phrase is done exporting files, you can go to your GitHub repository to merge (or close) the pull request. Remember to delete the branch when you finish.


Github Enterprise

GitHub Sync also supports GitHub Enterprise. To sync with a self-hosted GitHub Enterprise instance, select the GitHub Enterprise checkbox in the project settings and add the API URL to an Enterprise instance. Make sure that the API endpoint is publicly reachable from Phrase.



Why a pull request?

Phrase delivers language file updates as pull requests so that you can review all the changes. This keeps you in control of what actually goes into the branch you chose (usually “main”).

The validation fails, but the configuration file seems correct

Make sure that your configuration file includes at least one pull target (for importing into Bitbucket) and one push target (for exporting into Phrase). Double-check that the project ID is valid and belongs to the Phrase project you want to sync your files with.

Nothing gets imported or exported

Make sure that your .phraseapp.yml configuration file contains valid pull and push targets. Note that many file formats require locale_id to be defined for each source, since the files don’t contain any locale information. You can always use the Phrase Client to check if your configuration file behaves as you expect.

Auto-Import doesn’t work as expected

In the Settings section of the GitHub repository for your project, go to “Webhooks.” Click the webhook you added to notify Phrase about changes. In the webhook settings, make sure that the Payload URL is correct. It should contain a valid project ID and access token. You can also examine the most recent deliveries for each webhook. Check the response for any error messages returned by Phrase.

"Export as pull request" doesn’t work as expected

Make sure that the user who created the access token has the full repo scope. If you enabled SSO in GitHub, make sure to also enable SSO for the token

Please also make sure the branch phrase-translations created through the sync process is not protected.

Please also check if your repository settings require signed commits. Our commits are currently not signed and are being rejected by GitHub. For now, please disable this in their project settings to use the GitHub Sync.

GitHub Sync still doesn’t work

Contact us — we’re happy to help.

Further reading