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.
It's simple! Click this fancy button:
Then give the stack a name, and configure it:
||The CloudWatch ScheduleExpression defining the interval the issues are synced at.|
|GithubToken||The Github Authentication token used for fetching issues.|
||A Github repository to sync, in the format of
||A comma-separated list of labels to filter on.|
||A comma-separated list of labels to not include in the spreadsheet.|
||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
|SpreadsheetId||The spreadsheet ID to update. You can find this from the URL.|
||The name of the sheet to update inside the spreadsheet.|
In order to be able to access Github and Google Sheets, you'll need to setup some credentials on their websites.
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
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
resources: Transform: 'AWS::Serverless-2016-10-31' # Trigger Serverless to add CAPABILITY_AUTO_EXPAND Resources: otherResource: # ... all of your original resources
- 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:
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.
- 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!