cloudformation-zenhub-github-label: A JavaScript repository from sammarks

cloudformation-zenhub-github-label is an AWS SAM + CloudFormation template designed to automatically update Github issues with their current ZenHub pipeline.

Get Started

It's simple! Click this fancy button:

Then give the stack a name, and configure it:

Parameters

Parameter	Required	Default Value	Description
GithubToken	Yes		Your Github authentication token. Requires the `repo` scope.
Pipelines	Yes		A comma-separated list of ZenHub pipelines to track in Github.
DebugLevel	No	`<empty string>`	The `DEBUG` environment variable for the Lambda. Set to `cloudformation-zenhub-github-label` to enable debug messages.

Outputs

Output	Description
APIEndpoint	The API Gateway endpoint to add to ZenHub

Usage in Another Stack or Serverless

Add something like this underneath resources:

videoThumbnailStack:
  Type: AWS::CloudFormation::Stack
  Properties:
    TemplateURL: https://sammarks-cf-templates.s3.amazonaws.com/zenhub-github-label/VERSION/template.yaml
    Parameters:
      GithubToken: 'abcde'
      Pipelines: 'Done, Todo'
      DebugLevel: ''

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

Regions

A quick note on regions: If you are deploying this stack in a region other than us-east-1, you need to reference the proper region S3 bucket as we're deploying Lambda functions. Just add the region suffix to the template URL, so this:

https://sammarks-cf-templates.s3.amazonaws.com/zenhub-github-label/VERSION/template.yaml

becomes this:

https://sammarks-cf-templates-us-east-2.s3.amazonaws.com/zenhub-github-label/VERSION/template.yaml

What's deployed?

An API Gateway service
A Lambda function for ingesting Webhook notifications from ZenHub.

How does it work?

The Lambda goes through the following steps:

It first checks Github to get information about the labels enabled in the repository and the labels currently present on the issue.
It creates the pipeline label if it does not already exist (prefixed with zh:)
It updates the issue, adding the new pipeline label, removing the old one, and preserving any already-existing labels.

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/zenhub-github-label/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 update Github issues with their current ZenHub Pipeline for tracking.
Automatically creates labels representing the ZenHub pipelines if they do not yet exist.
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?

Let's say you're using something like cloudformation-github-sheets-sync and you want to keep track of the ZenHub pipeline inside your spreadsheet so you can do some reporting on it. Before, you would have to make an API request to ZenHub from Google Sheets, which is possible, but you run into problems with API limits.

Since ZenHub also supports webhooks, this Lambda function just updates the labels on Github which have first-party support from the cloudformation-github-sheets-sync script.

sammarks/cloudformation-zenhub-github-label