Syncing Your OpenAPI, RAML, and GraphQL Schema to GitHub with Postman

Kin Lane

February 11, 2020

Postman is already a critical tool throughout your API development lifecycle, but with the latest release of GitHub Sync, you can now also seamlessly connect your OpenAPI, Swagger, and RAML definitions as part of your existing processes. When you manage any of your schema in the Postman APIs tab, you can leverage the API builder to sync any changes you make in Postman to GitHub and vise versa. 

Integrate and Streamline Your Process 

Put the GitHub Sync to work by going to any of your API schema in Postman, and clicking on the “Connect Repository” button above the “Define” editor.

After you click the “Connect Repository” button, you’ll be taken to a page on the web where you’ll need to enter a GitHub personal access token. That will allow Postman to push data to your GitHub account.

If you’re not familiar with GitHub personal access tokens, you can find the screen for managing them by going to your GitHub account settings, and then clicking on developer settings. You can use this page to add and manage tokens for use in 3rd party integrations like Postman.

Once you have a token you can paste into the screen and have given Postman permission to store your key for future use, you can move on to the next step.

Your API schema and GitHub repository should now be connected, but there’s still just a little more work to do before your API schema will actually sync.

Finalize your sync

To finalize your sync, you’ll first need to setup a webhook on GitHub: it’s the webhook that will actually handle the real-time syncing between Postman and GitHub. Go ahead and copy the payload URL from this screen:

Then, head over to the GitHub repository you want to sync with (if you don’t have a repository, go ahead and create a new one) and click on the settings. Under the settings, you’ll see an option to manage your webhooks. Select to add a new webhook, paste in the payload URL you just copied, and then do the same for the secret.

Once the webhook is setup, you’ll need to select which version of our API to sync. This will not only tell the integration exactly which version of our API to sync, but also the specific folder and file to sync to. That means that you can potentially sync multiple versions of the same API to the GitHub repository we have connected. 

Get to work

Now that you’ve linked the repository, version, and file, you should be all set up. Any change made within Postman will now sync to GitHub, and any change made within GitHub will sync to Postman. You can replicate this sync across all of the APIs you manage across an organization, connecting your existing API life cycle to the distributed teams of developers who are already using Postman across an organization.

The Postman API Builder and GitHub Sync is brand new, but generally available in the Postman application. We need your feedback to help improve it and make it a tool that keeps your team in sync across your organization using Postman. Please make sure you share any feedback using the Postman application support repository. Just submit a new issue with details of your feedback. We look forward to hearing from you and learning more about how you are using GitHub schema sync as part of your API development life cycle.