Re-posted from old site. Original post: June 28, 2015
About a month ago I began to make a system using Google App Scripts to help my teammates log the tasks they worked on during the week. One method was using a Google Form, but my teammates wanted to be able to skip the form and just tag commit messages in order to log their tasks. This meant I had to connect our repository on GitHub to my Google App Scripts. I quickly realized there isn’t a lot of documentation on how to do that. So I decided that once I figured it out I’d share, so here it goes.
Step 1: Making a Google App Script
Pick a document, form, spreadsheet, or some other Google file in your Drive to be the base of where your scripts will live. (I attached mine to my Google Form so that everything was in one place.)
You access the Script Editor via the Tools tab in your Google file. If this is the first time you are editing a script on a file a prompt will show up. Choose “Blank Project”. This will set you up with a file called Code.gs and it should contain a function called myFunction.
Step 2: The doPost Function
In order to receive data from GitHub you need to have a function called doPost. There are two functions that get used when making a Web App to handle data they are doGet and doPost. doGet is for when you want to intercept HTTP GET Requests and doPost is when you want to intercept HTTP POST Requests. Since we will be getting a POST Request from GitHub we want to use doPost. Therefore add the following to your script:
// Required to receive data from GitHub function doPost(data) { GitHubGrab(data); }
“data” will be holding the JSON data you will receive from GitHub. In my case I pass it along to a function called GitHubGrab. You can just edit your myFunction that was provided to take “data” as a parameter and put it in place of my GitHubGrab function.
Step 3: Turning your script into a Web App
In order for your script to be accessible by GitHub it has to be made into a Web App. To do this go to the Publish tab and select “Deploy as web app..”
It might prompt you to name your project but then it should bring up a couple settings you will need to change. The first being the Project version. If you make new changes to your script and want them to be reflected in your Web App (most of the time you do) ALWAYS select New as your version (it’s usually not the defaulted choice). Otherwise it doesn’t update the code being run from the Web App.
Next it will ask you “Execute the app as:”. What you choose here might also depend on what you are trying to do but if you are editing your own files just select “Me: yourEmail@gmail.com”. The last thing is asking “Who has access to this app:”. Set this to “Anyone, including anonymous”.
There are three options. Here are what they mean:
Only myself – only you can run the app
Anyone – anyone with a Google account and is logged in can run the app
Anyone, even anonymous – anyone even without a Google account can run the app
GitHub isn’t a person so we don’t want it to need to login in order to run our app. That is why we choose the third option. Once you hit Update you will be provided with a link. If you were to go to this link it will run your Web App. We want to save this link.
Step 4: Getting GitHub to use your Web App
If you go to your repository on GitHub and go to the sidebar. Choose Settings. On this page there should be a box of Options. Click on “Webhooks & Services”.
Click “Add webhook”. The first box is for the Payload URL. This is where you put the link to your Web App. Also leave the Content type box as application/json. A little farther down you can choose which kind of events trigger your Webhook. For the basics just ensure “Commit comment” and “Push” are selected. Ensure “Active” is checked and click “Add Webhook” or “Update Webhook”.
If you scroll down to the bottom of the page you will see a box title “Recent Deliveries”. You may have a red icon next to the first one listed. This means it was unsuccessful.
If it is green this means it was successful. If you’ve followed the steps until now it should be green. Once you start filling in your functions and expanding your Web App you may encounter more errors.
Step 6: Debugging Delivery Info
One of the nice things about the Webhook setup is that you can Redeliver a packet. That way you don’t have to wait for someone to commit/push something or push constantly just for testing. If you need a specific type of commit message I recommend sending a test commit and then just using the Redeliver button on that commit.
The Request tab can give you some info about how the Webhook ran along with what the Payload looked like. It sends all the data in JSON so if you are looking for something specific you can just sample your commit Payload and later I’ll show how to access that in your script.
The Response tab also has helpful data. Here you can see if your Web App sent back any errors. If you go down to the Body section and look towards the bottom it will usually mention an error your script encountered like if something was undefined. If there were no errors it will look something like this:
GitHub can show your Webhook as a success even if you had errors. So it’s always good to go and check the Body section.
Step 7: Using the Payload in Your Scripts
So now you have GitHub running your Web App, but how do you access what it’s sending you. For this you will be using JavaScript’s functions for parsing JSON.
// Get the data sent from GitHub var jsonString = data.postData.getDataAsString(); // Turn it into a JSON object so it can be accessed easier var payload = JSON.parse(jsonString);
The lines above take the data and turn it into a string then parses that string into a JSON object. Now you can access members as if they were members of a struct or class. For example:
// Grab Commit Message var origMessage = payload.head_commit.message;
Now you can treat the origMessage variable as a string and parse out the things you do and don’t want.
That is the basics for connecting your Google App Scripts and GitHub repository. From here you can do whatever you want with the data like append it to a file or email it out to someone.