cloudformation-github-sheets-sync is an AWS CloudFormation template generated using the Serverless Framework designed to pull issues from a Github repository, and sync them with a Google Docs Spreadsheet at a specified interval.

Get Started

It's simple! Click this fancy button:

Then give the stack a name, and configure it:

Parameter	Default Value	Description
UpdateSchedule	cron(0/30 12-23 ? * MON-FRI *)	The CloudWatch ScheduleExpression defining the interval the issues are synced at.
GithubToken		The Github Authentication token used for fetching issues.
Repository	sammarks/cloudformation-github-sheets-sync	A Github repository to sync, in the format of owner/repository
Labels	reporting	A comma-separated list of labels to filter on.
BlacklistLabels	reporting	A comma-separated list of labels to not include in the spreadsheet.
State	OPEN,CLOSED	A comma-separated list of states to filter on.
GoogleClientEmail		Your service account's email address for Google.
GooglePrivateKey		Your service account's JSON-encoded private key for Google. Should be something like "-----BEGIN PRIVATE KEY-----\nabddfd..."
SpreadsheetId		The spreadsheet ID to update. You can find this from the URL.
SheetName	Github Issues	The name of the sheet to update inside the spreadsheet.

Preparing Credentials

In order to be able to access Github and Google Sheets, you'll need to setup some credentials on their websites.

Github

All you need for Github is a developer token with access to be able to read issues for your repositories. This script doesn't write anything to Github.

Go to edit your personal access tokens, create one, and make sure it has the repo scope.

Google

This one is a little more complicated. To setup Google, follow these instructions from google-spreadsheet.

Then you're ready! Once the stack is deployed, you can inspect the CloudWatch logs of your Lambda functions to make sure they're pulling issues and updating spreadsheets properly.

Usage in Another Stack or Serverless

Add something like this underneath resources:

githubSheetsSyncStack:
  Type: AWS::CloudFormation::Stack
  Properties:
    TemplateURL: https://sammarks-cf-templates.s3.amazonaws.com/github-sheets-sync/VERSION/template.yaml
    Parameters:
      GithubToken: ''
      Repository: ''
      # ... other parameters

You can even create multiple instances of the stack to sync multiple repositories at a time!

Note: This stack will require the CAPABILITY_AUTO_EXPAND capability when deploying the parent stack with CloudFormation. If you are using the Serverless framework, you can "trick" it into adding the required capabilities by adding this to your serverless.yaml:

resources:
  Transform: 'AWS::Serverless-2016-10-31' # Trigger Serverless to add CAPABILITY_AUTO_EXPAND
  Resources:
    otherResource: # ... all of your original resources

What's deployed?

• One Lambda function, scheduled to execute at your interval.

How does it work?

The sync Lambda goes through the following process:

• Authenticate with Google and make sure the spreadsheet and sheet exist.
• Fetch the latest Github issues for the repository, sorting by created date descending.
• Clear the existing sheet.
• Re-populate the sheet with the headers and cells generated from the issues.

Accessing Previous Versions & Upgrading

Each time a release is made in this repository, the corresponding template is available at:

https://sammarks-cf-templates.s3.amazonaws.com/github-sheets-sync/VERSION/template.yaml

On upgrading: I actually recommend you lock the template you use to a specific version. Then, if you want to update to a new version, all you have to change in your CloudFormation template is the version and AWS will automatically delete the old stack and re-create the new one for you.

Features

• Automatically sync Github issues with Google Sheets for further refining, metadata-adding, reporting, etc.
• No need to pay for third-party services! Just pay for the Lambda (very cheap).
• Customize your own schedule and limited filtering.
• Deploy with other CLoudFormation-compatible frameworks (like the Serverless framework).
• All functionality is self-contained within one CloudFormation template. Delete the template, and all of our created resources are removed.

Why use this?

Google Sheets is a great tool for communicating Github issue progress from an engineering team to other executives. There are a lot of solutions out there for syncing Github issues, but none allow complete control over the codebase (just fork it and change what you'd like, or modify the Lambda code directly). The other solutions out there also cost money, and Lambda is cheap!