GitHub

Syncing API Schemas on GitHub is available with a free Postman account. You can back up your collections to GitHub on Postman Team, Business, and Enterprise plans.

Postman enables you to back up your collections (for paid plans only) or synchronize your API schemas on GitHub. For each of these integrations, you'll need to generate a GitHub personal access token.

If you are looking to import data into Postman from a GitHub repository, see Importing via GitHub repositories.

Generating a GitHub Personal Access Token

In order to set up an integration, you will need a GitHub Personal Access Token.

  1. Log in to GitHub.
  2. If you don’t already have a Personal Access Token from GitHub, generate a new one.
  3. For backing up your collections, select the repo and the user scope. For syncing your API schema, select only the repo scope.

    repo scope user scope

  4. Once that token is generated, copy it and save it somewhere for future use. generated token

Backing up collections on GitHub

You can back up and sync your Postman collections with a GitHub repo. Once the integration is complete, any new changes to your collection in Postman will also appear in the repository.

Backing up collections on GitHub is available for Team, Business and Enterprise plans only.

  1. From the Home page select Integrations.

    home page and integrations

    Search and select Github.

    github integration

  2. Next to Backup a collection, click Add Integration to authorize a backup of your Postman collections.
  3. Enter your GitHub Personal Access Token and click the Proceed button.

    access token

  4. Once the token is verified, you'll be able to configure the integration.

    configure

    • Give the integration a nickname.
    • Select a workspace containing the collection to back up.
    • Select a collection to back up.
    • Select the GitHub repository where it will be backed up.
    • Enter the directory where the collection will be pushed. If the directory does not exist, it will be created for you. If you do not specify anything, the default directory will be Postman Collections.
    • Enter the file name of the collection in the repository.
    • Enter the branch where the collection will be pushed. This branch must already exist in your repository. If you do not specify anything, it will be pushed to the default branch of the repository.
  5. To finish, click Add Integration.

Every change saved to your Postman Collection automatically commits changes to your GitHub repo in real time. You can navigate to your GitHub repository to view your collections.

github integrations screen

Backing up collections to GitHub on a custom domain

Backing up collection to GitHub with a custom domain name is similar to the above, with the following differences.

  1. From the initial GitHub integrations page, next to Backup a collection (custom domain), click Add Integration.
  2. In addition to your Personal Access Token, enter your GitHub Custom Domain, and click Proceed:

    access token custom

  3. Complete the same steps as above to configure your collection, repository, directory, file name, and branch.
  4. To finish, click Add Integration.

Static IP Support

If your network is behind a firewall that requires whitelisted IP addresses, you will need to use a static IP address to enable collection backups to GitHub on custom domains.

Contact your IT team to whitelist the following static IP in your firewall to enable collection backups to GitHub:

  • US East: 3.212.102.200

Once you whitelist this IP address, calls for this integration will be able to connect to your network and allow the integration to work as expected.

Syncing your API schemas on GitHub

Syncing your API schemas will enable a two-way sync between the schema stored in the GitHub repository and the schema on Postman.

  1. From the Integrations search page, search for GitHub and select it from the results.
  2. Next to Sync API schema, click Add Integration to authorize a backup of your Postman collections.
  3. Enter your Personal Access Token, select I consent to Postman collecting and storing my GitHub Access Token, then click Proceed.
  4. On the next page, give the integration a nickname, select the workspace and API you want to sync with GitHub, and the GitHub repository where the schema should sync from the dropdowns, then click Add Integration.

    The list of your GitHub repositories may take some time to load.

    github integrations screen

  5. On the next page you need to set up your webhook. Go to the settings page of your GitHub repository, click Webhooks, then Add webhook. Copy over the Payload URL and Secret from Postman, set Content type to application/json, and click Add webhook. Refer to the GitHub documentation for more detail.

    add webhook

  6. Back to the Postman dashboard, click Add API Version, and select the following details:

    • The API Version you want to sync, such as 1.0.
    • The repository directory where you want the schema file to be saved, such as api.

      • Leave this field blank to save the schema at the root of your repository. If the folder specified doesn't exist on the repository it will be created.
    • The name and extension of the schema file, such as petstore.yaml.

      • If the file doesn't exist on the repository it will be created.

    github integrations screen

  7. To finish, click Add API Version.

You can sync multiple API versions by clicking Add API Version again. To delete an existing API version, hover over the entry, click the grey X to the right, then click Remove API Version.

If you are linking an existing API schema on Postman to an existing schema file on GitHub, a pop-up message will appear asking which schema you want to keep. The other schema will be overwritten.

Once the integration is complete, return to the Postman app and navigate to your API. A badge will show the sync status, file, and repository.

github integrations screen

The sync of API schemas is two-way; after your first schema sync, each change to the schema in Postman will appear in the repository as a new commit. Similarly, if you or someone else updates the file on the GitHub repository, the API schema on Postman will be updated.

To ensure that changes made in GitHub work properly in your collection, use the Validate option as described here.

If changes take place on the repository while you are editing the file on Postman, a Conflict state will be displayed. Saving the changes on Postman will override the file on GitHub.

commit example github

Troubleshooting GitHub Sync

If you're having issues with your GitHub integration and find your data isn't syncing to GitHub, please ensure that the following requirements are in place:

  • The GitHub integration has been added to the same workspace as the content you're trying to push to the GitHub repo.
  • The correct option has been chosen when setting up your integration and selecting Backup your Postman Collections to GitHub, for example if you're using a custom domain.
  • Your repo has been initialized with a Readme.md file. Check the box Initialize this repository with a README and then configure a new integration on it.
  • The scopes user and repo are selected when creating the access token on GitHub.
  • The branch specified in the setup already exists on GitHub. The integration will not create one if the branch doesn't exist.
  • You have permissions to push to the branch.
  • If all else fails, try reinstalling the integration.

If your enterprise version of GitHub is on-premises / self-hosted, this may be a firewall issue.