Learn from experts and connect with global tech leaders at POST/CON 24. Register by March 26 to save 30%.

Learn more →
X

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

Avatar

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.

What do you think about this topic? Tell us in a comment below.

Comment

Your email address will not be published. Required fields are marked *


This site uses Akismet to reduce spam. Learn how your comment data is processed.

4 thoughts on “Syncing Your OpenAPI, RAML, and GraphQL Schema to GitHub with Postman

  • Avatar

    Hello!

    We are trying to do this in a team environment and running into the issue where only the user who granted access with their public token can see the repo while the others see “Repo Unavailable” in the APIs section. How do we configure all members of our team workspace to see the repo.

    Best,

    Griffin

  • Avatar

    Hi,

    I am having my Api Specs in my local git repository. I created Personal Access Token and done the same steps as mentioned in this article but it isn’t working. Also I couldn’t find any provision to provide url of my local git repository?
    Does this works only with GitHub.com?
    Thanks!

    Regards,
    Monish

  • Avatar

    Hi, we have the same issue like Griffin (Repo unavailable). Can you give us a hint how we can solve this in a team environment? Greets, Hannes

  • Avatar

    Is it possible to do it another way – sync schema file from GitHub repo to Postman?