Integrate Postman with GitHub

GitHub Enterprise Server integrations are available on Postman Enterprise plans with the API Builder add-on.

Back up your Postman collections to GitHub, a cloud-based hosting service for Git repositories, with the Postman to GitHub integration. You can also back up collections to a custom domain on GitHub Enterprise Server.

Setting up a GitHub integration requires you to generate a GitHub personal access token and configure how you would like to back up your collections.

To import data into Postman from a GitHub repository, see Importing from GitHub repositories.

API sync with GitHub

With Postman v10 and later, you can connect a GitHub repository to an API in the API Builder. Once connected, you can sync your API's definition and associated collections between Postman and GitHub. You can switch branches, pull changes from the repository, and push changes to the repository, all from within Postman. To learn more about syncing your API with GitHub, see API version control overview.

The legacy GitHub Sync API schema integration is no longer available. You can't create new integrations using this legacy integration, and any legacy integrations you created have been removed. Instead, you can connect your API to a Git repository to sync your API's definition between Postman and GitHub.

Generating a GitHub personal access token

To integrate with GitHub, you need a GitHub personal access token.

1. Sign in to GitHub.

2. If you don't already have a personal access token, generate a new one. You can use a classic token or a fine-grained token.

   • Classic token - Make sure to select the repo and user scopes.
   • Fine-grained token - Make sure the token has access to the repository you want to back up to and has the following Repository permissions: Contents (Read and write) and Metadata (Read-only).

3. Save the generated token to use later.

For more information about generating a token, see the GitHub documentation.

Backing up collections to GitHub

You can back up a Postman Collection to a GitHub repository. After you create the integration, any new changes to the collection in Postman will also appear in the GitHub repository.

1. From the Home page select Integrations.

2. Search and select GitHub.

   

3. Next to Backup a collection, select Add Integration.

4. Enter your GitHub Personal Access Token and select Authenticate and Proceed.

   

5. After Postman verifies the token, you can configure the integration:

   • Nickname - A nickname for your integration.
   • Workspace - The workspace with the collection you want to back up.
   • Collection - Select a collection to back up.
   • Repository - Select the GitHub repository where you want to back up the collection.
   • Directory - Enter the directory where you want to push the collection. This is optional. If the directory doesn't exist, Postman will create it for you. If you don't specify a directory, Postman will create a Postman collections directory.
   • Filename - Enter the file name of the collection in the repository.
   • Branch - Select the branch where you want to push the collection. The branch must already exist in your repository. If you don't specify a branch, Postman will push the collection to the default branch of the repository.

6. To finish setting up the integration, select Add Integration.

Postman often checks your collection for changes. If Postman identifies changes when it checks your collection, the changes automatically commit to your repository in JSON format. Go to your GitHub repository to view your collections.

You can view your configured integrations on the Browse Integrations page. You can also view integrations that have been configured for a collection by opening the collection and selecting the information icon in the right sidebar. Learn more about viewing or editing integrations.

Backing up collections to GitHub Enterprise Server

You can back up a Postman Collection to a GitHub Enterprise Server repository on a custom domain. Follow the same step as backing up collections to GitHub with the following differences.

1. After searching for the GitHub integration in Postman, select Add Integration next to Backup a collection (custom domain).

2. Along with your personal access token, enter the custom domain of your enterprise server (for example, https://my-git-server.example.com). Then select Authenticate and Proceed.

3. Configure the integration with your collection, repository, directory, file name, and branch.

4. To finish setting up the integration, select Add Integration.

Postman often checks your collection for changes. If Postman identifies changes when it checks your collection, the changes automatically commit to your repository in JSON format. Go to your GitHub repository to view your collections.

Static IP support

If your network is behind a firewall, you must allowlist a static IP address to enable collection backups to GitHub Enterprise Server on a custom domain.

Contact your IT team to allowlist the following static IP in your firewall:

• US East: 3.212.102.200

Once you allowlist this IP address, the collection backup integration will be able to connect to your private network.

The Backup a collection (custom domain) integration requires the ability to reach the static IP address 3.212.102.200 from the network where your GitHub Enterprise Server instance is hosted. If your server instance is in a virtual private cloud (VPC), you may need to change the VPC's network access control list or rules.

Troubleshooting the GitHub integration

If your GitHub integration has issues or your data isn't pushed to GitHub, make sure you've met the following requirements:

• You added the GitHub integration in the same workspace as the content you want to push to the GitHub repository.

• You selected the correct GitHub integration in Postman. For example, if you use GitHub Enterprise Server on a custom domain, make sure you selected the Backup a collection (custom domain) integration.

• You initialized your GitHub repository with a README.md file. When creating a new repository, you can select the Add a README file checkbox.

• You selected the correct permissions when creating your GitHub personal access token:

  • Classic token - Make sure to select the repo and user scopes.
  • Fine-grained token - Make sure the token has access to the repository you want to back up to and has the following Repository permissions: Contents (Read and write) and Metadata (Read-only).

• The branch you specified when setting up the integration already exists on GitHub. Postman won't create the branch if it doesn't already exist.

• You have permissions to push to the branch.

• If your instance of GitHub Enterprise Server is on-premises or self-hosted, check with your IT team for firewall requirements.

Edit the integration to make any required changes. If the integration still doesn't work after you edit it, delete the integration and add it again.