Do you like GitHub, but don’t like having to log in to check on the status of your project or code? GitHub events are your solution.
GitHub events provide a handy way to receive automated status updates from your GitHub repos concerning everything from code commits to new users joining a project. And because they are accessible via a Web API as GET requests, it’s easy to integrate them into the notification system of your choosing.
Keep reading for a primer on GitHub events and how to get the most out of them.
What GitHub events are, and what they are not
Again, GitHub events provide an easy way to keep track of your GitHub repository without monitoring its status manually. They’re basically a notification system that offers a high level of customizability.
You should keep in mind, however, that GitHub events are designed only as a way to receive notifications. They don’t allow you to interact with your GitHub repo. You can’t trigger events; you can only receive notifications when specific events occur.
That means that events are not a way for you to automate the maintenance of your repository or project. You’ll need other tools for that. But if you just want to monitor changes, they’re a simple solution.
How to use GitHub events
GitHub event usage is pretty straightforward. You simply send GET requests to https://api.github.com. You specify the type of information you want by completing the URL information accordingly.
For example, if you want information about the public events performed by a given GitHub user, you would send a GET request to this URL:
https://api.github.com/users//events
(If you are authenticated, this request will generate information about private events that you have performed.)
Here’s a real-world example, in which we send a GET request using curl to find information about public events performed by Linus Torvalds (the original author of Git), whose username is torvalds:
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -X GET https://api.github.com/users/torvalds/events
Another handy request lets you list events for a particular organization. The URL to use here looks like:
https://api.github.com/users/:username/events/orgs/
The full list of events, with their associated URLs, is available from the GitHub documentation.
Use GitHub Webhooks for automated events reporting
So far, we’ve covered how to request information about an event using a specific HTTP request. But you can take things further by using GitHub Webhooks to automate reporting about events of a certain type.
Webhooks allow you to “subscribe” to particular events and receive an HTTP POST response (or, in GitHub parlance, a “payload”) to a URL of your choosing whenever that event occurs. You can create a Webhook in the GitHub Web interface that allows you to specify the URL to which GitHub should send your payload when an event is triggered.
Alternatively, you can create Webhooks via the GitHub API using POST requests.
However you set them up, Webhooks allow you to monitor your repositories (or any public repositories) and receive alerts in an automated fashion.
Like most good things in life, Webhooks are subject to certain limitations, which are worth noting. Specifically, you can only configure up to a maximum of twenty events per each GitHub organization or repository.
Authentication and GitHub events
The last bit of information we should go over is how to authenticate with the GitHub API. While you can monitor public events without authentication, you’ll need to authenticate in order to keep track of private ones.
Authentication via the GitHub API is detailed here, but it basically boils down to having three options. The simplest is to do HTTP authentication using a command like:
curl -u "username" https://api.github.com
If you want to be more sophisticated, you can also authenticate using OAuth2 via either key/secrets or tokens. For example, authenticating with a token would look something like:
curl https://api.github.com/?access_token=OAUTH-TOKEN
If you’re monitoring private events, you’ll want to authenticate with one of these methods before sending requests about the events.
Further reading
If you want to dive deeper into the details of GitHub events, the following resources are useful:
- Overview of event types.
- Event payloads according to event type.
- Setting up Webhooks.
- GitHub API authentication.
A Beginner’s Guide to GitHub Events is published by the Sumo Logic DevOps Community. If you’d like to learn more or contribute, visit devops.sumologic.com. Also, be sure to check out Sumo Logic Developers for free tools and code that will enable you to monitor and troubleshoot applications from code to production.
