gitrdone

Self-hosted, AWS Lambda-backed (Serverless) "Dones" with Slack and Github integration!

Why use Gitrdone?

• To keep track of what you got done today!
• Free and open-source alternative to costly SaaS products such as iDoneThis
• Alternative to third-party Slack apps that request too much Slack permission, opening up security vulnerabilities in your team.
• Integrates with tools you already use, Slack & Github!

Usage:

• In Slack, type something like /gitrdone That thing I got done
• First-time users will be directed through a quick auth flow that associates their Slack and Github accounts.
• "Dones" will be recorded in a Github Gist (https://gist.github.com)!
• A new Gist "file" will be created on the same Gist every day with your Dones.
• Dones are parsed with Github-flavored Markdown, allowing some neat things.

Requirements

Gitrdone is a self-hosted service, meaning you host it on your own Amazon Web Services account. It relies on the following AWS products:

• API Gateway - for programmatic API deploys
• Lambda - for processing requests
• S3 - for storing user keychains (Slack & Github profiles/tokens)
• IAM - for your Lambda permissions
• CloudFormation - for hosting the Lambda scripts and their assets
• CloudWatch - for logging

Gitrdone is NOT a SaaS service. That means you also have to create your own Slack & Github developer applications.

Installation

Installation and deployment must be performed by an Administrator of your team's AWS account.

Install the Serverless framework via npm: (requires Node V4)

npm install serverless -g

Clone this repository (or a fork of it) and cd into the root directory. Then install the dependencies

npm install

Run the following command to initialize your customized version of gitrdone. This will generate a _meta directory which should not be committed to public repositories. The included .gitignore will prevent you from committing the sesitive files, but it is important to remember that they are there.

Note: You can change the -s argument if you want to setup a different stage for testing (i.e. development or staging). I recommend just using one stage (production).

serverless project init -s production

Your self-hosted Gitrdone API is now deployed to AWS API Gateway / Lambda, but it will not work yet. First you need to create developer applications for both Slack and Github.

Both accounts will require you to specify your API's OAuth redirect URI. The output of the previous command should have the fully qualified URLs for the endpoints.

Create your team's Gitrdone Slack appication here:

https://api.slack.com/applications

Specify the OAuth redirect URL to be the github-auth endpoint. It should look like this:

  https://<YOUR_API_ID>.execute-api.us-east-1.amazonaws.com/<YOUR_API_STAGE>/github-auth

Take note of your Verification Token, you'll need to save this to your API variables later.

Configure a Slash Command called /gitrdone (or however you prefer to log your dones) with a Request URL of:

https://<YOUR_API_ID>.execute-api.us-east-1.amazonaws.com/<YOUR_API_STAGE>/webhook

Suggested value for Short Description:

Make a note about something you got done!

Suggested value for Usage Hint:

[Shipped a new jorbascrap nanoservice]

Create your team's Gitrdone Github appication here:

https://github.com/settings/developers

Specify the OAuth redirect URL to be the github-callback endpoint. It should look like this. Note that the only difference from the last step was the API method:

  https://<YOUR_API_ID>.execute-api.us-east-1.amazonaws.com/<YOUR_API_STAGE>/github-callback

Finally, update your API variables in the _meta/variables/s-variables-production.json (assuming stage is production) to contain the following variables:

key	required	description
stage	y	this should already be set
github_client_id	y	your github app's client id
github_client_secret	y	your github app's client secret
slack_team_id	n	your slack team id if you want to restrict use of this app to a single team
slack_client_id	y	your slack app's client id
slack_client_secret	y	your slack app's client secret
slack_verification_token	y	your slack app's verification token
s3_bucket_name_gitrdone	y	should already be set, should look like gitrdone-production-something
encryption_key	y	a long, randomly generated key used for encryption of user data. can be generated by running rake secret if you have the rake gem installed on your system.

That's it! Everything will definitely work 100% all the time ! Just run the deploy command from your project root and choose to deploy endpoints.

serverless dash deploy

TODO

• Document env configuration, how to generate slss metadata
• Add prompts to post-init hook for entering Slack & GitHub configs
• Fail gracefully during auth flow, render HTML or plaintext errors
• Support custom domain
• Add support for TODOs (create an unchecked markdown list item in the gist)