Automatically consume APIs and perform behind-the-scenes actions with your everyday Git commands

Matt Ball

·

Follow

Published in

Better Practices

·

6 min read

·

Aug 15, 2019

--

2

Listen

Share

Most of us are using Git to version control our source code and to provide us with a simple way to collaborate on projects.

Over time we’ve seen how this workflow has grown with connected apps — be it Codeship for CI, Snyk for vulnerability management, or Greenkeeper for managing dependencies in an automated way.

When these apps and integrations don’t exist, we often feel like we need to work around the problem, hashing together webhooks and services until we get what we need. This works well when we’re thinking about the remote-side of a Git repo, but what about during local development?

For this, we can consider using Git Hooks. Hooks are a lesser known but very effective approach for automating parts of our workflow.

So what exactly are hooks? Git Hooks are scripts that Git executes before or after specific events. This could be a checkout, commit or push command for example. The beauty of Git Hooks is that they are included in Git as standard. There’s nothing we need to configure or install before getting started.

Here are a few popular hooks, but you can also consult the full list:

• pre-commit
• post-commit
• pre-rebase
• post-checkout
• post-merge
• pre-receive
• post-receive
• pre-push

Getting started 🛠

We should be able to find a .git/hooks directory from the root of a local Git repo. This directory houses a number of sample hooks we can use to get started, or we can create our own. Let’s try creating our own “Hello world!” hook which runs any time we execute git checkout.

1. Create a file calledpost-checkout inside the .git/hooks directory.
2. Make it executable, and change the permissions to suit:
   chmod +x post-checkout.
3. Write some script to give our hook something to run. We can write our hook in any language. I like using Node, so that’s what we’ll go with here:

#!/usr/bin/env nodeconsole.log('Hello world!')

4. Test the hook by running ./.git/hooks/post-checkout. If steps 1–3 went smoothly, we should see the output Hello world!. Now we can move on and try running the git checkout command to see if it works there too.

Making things more sophisticated ⚙

At Postman we’ve been working hard to enable a best in class platform for collaborative API design and development. Team workspaces, granular roles and permissions and built in fork and merge capability make this easy.

However, we know that a lot of teams already have their workflow setup, and would rather manage their Postman collections through their existing version control system.

If we’re working in this format; at the same time as developing our code and opening a pull request for it, we’d be iterating on our collection within Postman. Once the collection and code are aligned, we can manually export the collection to disk and add it as another commit in our pull request.

Manual workflow

This process is only a few steps: we have to import the latest collection each time we open a new pull request, and export it each time we’re finalizing our pull request. However, just these few steps can be a setback. The reliance on human input means it gets forgotten or is left out being deemed as too tedious of a process.

Automation is clearly the answer, and that’s where Git Hooks comes back into the picture.

Automated workflow

To get started, we’ll need a Postman API key and to add a file called postman_collection.json to our repo. Our hooks will need to know the API key, as well as the path to the collection file, so we’ll create a config.js file to hold this. I placed mine in a hooks directory.

module.exports = {
  postmanApiKey: 'xxx',
  collectionFile: 'postman_collection.json'
}

Now, let’s break this down into two steps.

1. Automatically import the current collection into Postman upon creating a new branch 📩

Again, we’ll want to make use of the post-checkout hook. We need to:

• Determine when a new branch is created
• Read the current/master postman_collection.json held in the repo
• Upload this into our Postman workspace via Postman’s API so we can start working with it right away

If we tweak our Node script to do this, we end up with something like this:

Now, when we run our git checkout command, our postman_collection.json is read from our repository and synced to Postman via Postman’s API.

Upon opening the Postman app and navigating to our workspace, we see our collection waiting for our changes. Great, no manual import required!

2. Automatically commit collection changes that were made through Postman to our branch 🚢

For this step of the process we need to:

• Identify if we’ve made any changes to the collection in Postman
• If yes, pull those changes out of the Postman app into our local repo
• Add another commit to keep things in sync

This time we’ll need a pre-push hook.

Upon a git push, the script will retrieve the collection we’ve been working on in Postman via the Postman API. If its content differs from the collection we already had in the repo, it’ll update the repo and add another commit for us, before prompting us to git push again to complete the action.

Upon opening a pull request for the branch, we see the local changes we made to our files, along with the automated commit and the updated copy of the Postman collection pulled in from the app.

Summary 🛤

We’ve shown how you can get started with Git Hooks, beginning with a basic hello world script, right through to an integration with Postman.

We used Postman’s API to sync data to our Git repo automagically, but we could have also connected to anything that has an API. The chances are that your imagination is the only limit to what you can do!

Can you see how Git Hooks might fit in with your Git workflow? Can you use these hooks as a starting point to automation? Have fun developing your hooks and please share your results!