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 allows you to back up your collections (for paid plans only) or synchronize your APIs schemas on GitHub. For each of these integrations, you'll need to generate a GitHub personal access token.

Generating a GitHub Personal Access Token

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

Log in to GitHub.

If you don’t already have a Personal Access Token from GitHub, generate a new one.

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

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.

Configuring GitHub integration for collections

In the Integrations page, find Github from a list of Postman's 3rd party Integrations for Postman Pro users.

github integration

Click View Details to see information about Github and how it can back up your Postman Collections to your designated repositories.

You also can click the Configured Integrations tab to set up other integrations, view available integrations for Github, or view all integrations.

select github integration

The above screen provides you the following two options:

Backup collections to GitHub

Click Add Integration to authorize a backup of your Postman collections, then enter your GitHub Personal Access Token and click the Proceed button.

access token

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

configure

  • Select a collection to back up.
  • Select the repository.
  • 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 should already exist in your repository. If you do not specify anything, it will be pushed to the default branch of the repository.

To finish, click Add Integration.

Every change saved to your Postman Collection automatically commits changes to your GitHub repo in real time. Your Collections and code can live together in perfect harmony in the same repository.

Backup collections to GitHub on custom domain

access token custom

Enter your GitHub Personal Access Token, specify your GitHub custom domain and click Proceed. In Backup your Postman Collections, choose an existing Postman collection, specifying your GitHub repository, a filename for your backup, and your chosen branch name.

github integrations screen

Click Add Integration. Your collection is pushed to your GitHub project under the directory that you specified and saved as a single JSON file. This is illustrated in the following screen:

github integrations screen

Now every change that is saved to your Postman Collection automatically commits changes to your GitHub repository in real time. Your collections and code can exist in the same repository.

You can navigate to your GitHub repository to view your collections.

github integrations screen

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.

Configuring GitHub integration for API schemas

You can access the configuration for the GitHub integration from the web dashboard or from the Postman app. Once on the configuration page, go ahead with the configuration.

From the web dashboard

Navigate to the web dashboard, select the appropriate workspace, then Integrations at the top. On the integrations page, click Create an integration in this workspace, search for the GitHub tile and click View Details. On the next page, click + Add Integration next to Sync API schema.

schema sync dashboard

From the Postman app

For a new API, click APIs in the app sidebar, then click + New API at the top. Once the API is created, choose Select from repository in the dropdown.

For an existing API, navigate to your API by clicking APIs in the app sidebar, select your API from the list, then click Connect Repository to start configuring the integration.

schema sync app

Configuration

Enter your personal access token in the text field, select I consent to Postman collecting and storing my GitHub Access Token, then click Proceed. On the next page, select the API you want to sync with GitHub, and the GitHub repository where the schema should sync from the dropdowns, then click Add Integration and Continue.

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

On the next page you need to setup your webhook. To do so, go to the settings page of your GitHub repository, click Webhooks, then Add webhook. Copy over the Payload URL and Secret from Postman, then click Add webhook to confirm. Refer to the GitHub documentation for more detail.

add webhook

Once your webhook is set up, go back to the Postman dashboard, click Add API Version, and select the following details:

  • the API Version you want to sync - e.g. 1.0
  • the repository branch to use - e.g. Master
  • the repository directory where you want the schema file to be saved - e.g. api

    • Leaving this field blank will 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 - e.g. petstore.yaml

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

To finish, click Add API Version

schema sync app

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. The Connect Repository should show the path and name of the schema file on your GitHub repository - e.g. api/petstore.yaml.

schema sync succesful

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.

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