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.)Screenshot 2015-06-28 11.42.24

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:

“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..”
Screenshot 2015-06-28 12.16.09

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.

Screenshot 2015-06-28 14.37.50

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”.

Screenshot 2015-06-28 12.17.37

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.

Screenshot 2015-06-28 12.17.48

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”.

Screenshot 2015-06-28 14.44.28

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”.

Screenshot 2015-06-28 14.47.13

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.

Screenshot 2015-06-28 14.53.06

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.

Screenshot 2015-06-28 14.53.35

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.
Screenshot 2015-06-28 14.53.50

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.

Screenshot 2015-06-28 15.02.47

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:

Screenshot 2015-06-28 15.05.43

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.

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:

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.