Skip to content

Commit f2f3def

Browse files
casidiablocasidiablo
committed
Improved instructions and documentation
1 parent 6fc39f9 commit f2f3def

File tree

5 files changed

+119
-26
lines changed

5 files changed

+119
-26
lines changed

‎LICENSE

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
The MIT License (MIT)
2+
Copyright (c) 2016 Cristian Castiblanco
3+
4+
Permission is hereby granted, free of charge, to any person obtaining a copy of
5+
this software and associated documentation files (the "Software"), to deal in
6+
the Software without restriction, including without limitation the rights to use,
7+
copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
8+
Software, and to permit persons to whom the Software is furnished to do so,
9+
subject to the following conditions:
10+
11+
The above copyright notice and this permission notice shall be included in all
12+
copies or substantial portions of the Software.
13+
14+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
15+
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
16+
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
17+
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
18+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
19+
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md

+72-3
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,73 @@
1-
# tako
1+
## tako
22

3-
tako is a Github notifier for Slack. It is written in Clojure and runs on
4-
AWS lambda.
3+
🐙 tako is a Github notifier for Slack. It is written in Clojure and can be deployed to AWS lambda.
4+
5+
![blame imgur if you see this](http://i.imgur.com/mamKBe7.png)
6+
7+
## Why?
8+
9+
These are some (personal?) reasons to use tako:
10+
11+
- **Email kinda sucks**. By default Github sends you an email everytime someone creates a pull request or issue on a project you follow, or when you are mentioned, etc. Being an *inbox zero* freak myself, depending on email to stay on top of what's going on my your github account is rather cumbersome.
12+
- **Slack does a decent job** You probably use it more than email anyway. Slack messages are easier to skim and keep clean. Most notifications don't require you to reply back.
13+
14+
15+
## Requirements
16+
17+
- [lein](http://leiningen.org)
18+
- A [Github token](https://github.com/settings/tokens)
19+
- A [Slack Webhook URL](https://slack.com/apps/new/A0F7XDUAZ-incoming-webhooks) pointing to a channel of your preference.
20+
21+
To run locally:
22+
23+
lein run YOUR_GITHUB_TOKEN YOUR_SLACK_WEBHOOK_URL
24+
25+
You can also create an jar with `lein uberjar`.
26+
27+
## Running from AWS lambda
28+
29+
In my current setup I have `tako` running on top of [AWS lambda](https://aws.amazon.com/lambda/). This is why it is cool:
30+
31+
- [It is free](https://aws.amazon.com/lambda/pricing/), at least for this use case. Since `tako` runs just a few times per hour, it will never be executed more than one million times a month (which is when Amazon starts charging you).
32+
- You don't need to care about configure/maintain a server
33+
- It is easy to update/deploy the code
34+
35+
There's one caveat though: AWS can be configured to run every N minutes; the minimum N is 5, so worst case scenario you receive the notifications 5 minutes after they were produced. Not a big deal for me, but worth taking into account.
36+
37+
That said, all you have to do is create a new AWS lambda function and configure it to run every 5 minutes. The steps are slightly modified from [this guide](http://docs.aws.amazon.com/lambda/latest/dg/with-scheduled-events.html):
38+
39+
0: Build a jar
40+
```bash
41+
git clone [email protected]:casidiablo/tako.git
42+
cd tako
43+
export GITHUB_TOKEN=your token
44+
export SLACK_WEBHOOK_URL=the slack webhook url
45+
./build-jar
46+
47+
# a jar will be assembled in tako/target/tako.jar
48+
```
49+
1. Sign in to the AWS Management Console and open the AWS Lambda console at https://console.aws.amazon.com/lambda/
50+
2. Choose Create a Lambda function.
51+
3. In **Step 1: Select blueprint**, choose the **lambda-canary** blueprint.
52+
4. In **Step 2: Configure event source**:
53+
- In **Event source type**, choose **CloudWatch Events - Schedule**.
54+
- In **Name** type a name (for example, **Github Poller**). Then, this name appears in the list of event sources in the console.
55+
- In **Schedule expression**, specify **rate(5 minutes)**.
56+
5. In **Step 3**: Configure function, do the following:
57+
- Set the function name to `tako`
58+
- In **Runtime**, specify *Java 8*
59+
- In **Handler** type `tako.core::handler`
60+
- In **Role**, choose basic execution role.
61+
- In the **Lambda function code**, choose the jar produced in step `0`
62+
- In **Memory (MB)**, set the dropdown to 256
63+
- In **Timeout**, configure it to be 30 seconds
64+
6. In **Step 4: Review**, review the configuration and then choose **Create Function**. The function must look [like this](http://i.imgur.com/3tduRGF.png).
65+
66+
### Updating code
67+
68+
You can upload changes from the command line by running:
69+
70+
# make sure you have awscli installed and configured
71+
./lambda-deploy
72+
73+
Or by building a new jar and uploading it manually using the AWS web console.

‎build-jar

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
#!/bin/bash
2+
if [ "$GITHUB_TOKEN" = "" ]; then
3+
echo "You must specify a Github token using the env variable \$GITHUB_TOKEN.
4+
If you don't have a token, generate one at https://github.com/settings/tokens"
5+
exit -1
6+
fi
7+
if [ "$SLACK_WEBHOOK_URL" = "" ]; then
8+
echo "You must specify a Slack webhook URL using the env variable \$SLACK_WEBHOOK_URL.
9+
If you don't have one yet, generate it at https://slack.com/apps/new/A0F7XDUAZ-incoming-webhooks"
10+
exit -1
11+
fi
12+
13+
# create a config file with the token and url
14+
echo "github.token=$GITHUB_TOKEN" > resources/config.properties
15+
echo "slack.webhook.url=$SLACK_WEBHOOK_URL" >> resources/config.properties
16+
17+
echo "Creating uberjar:"
18+
echo
19+
20+
lein uberjar
21+
cp $PWD/target/uberjar/tako-*-standalone.jar $PWD/target/tako.jar
22+
23+
echo
24+
echo "File to upload to AWS: $PWD/target/tako.jar"

‎lambda-deploy

+1-22
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,5 @@
11
#!/bin/bash
2-
echo "Creating properties file..."
3-
echo
4-
if [ "$GITHUB_TOKEN" = "" ]; then
5-
echo "You must specify a Github token using the env variable \$GITHUB_TOKEN.
6-
If you don't have a token, generate one at https://github.com/settings/tokens"
7-
exit -1
8-
fi
9-
if [ "$SLACK_WEBHOOK_URL" = "" ]; then
10-
echo "You must specify a Slack webhook URL using the env variable \$SLACK_WEBHOOK_URL.
11-
If you don't have one yet, generate it at https://slack.com/apps/new/A0F7XDUAZ-incoming-webhooks"
12-
exit -1
13-
fi
14-
15-
# create a config file with the token and url
16-
echo "github.token=$GITHUB_TOKEN" > resources/config.properties
17-
echo "slack.webhook.url=$SLACK_WEBHOOK_URL" >> resources/config.properties
18-
19-
echo "Creating uberjar:"
20-
echo
21-
22-
lein uberjar
23-
cp $PWD/target/uberjar/tako-*-standalone.jar $PWD/target/tako.jar
2+
bash build-jar
243

254
echo
265
echo "Uploading as AWS lambda"

‎src/tako/core.clj

+3-1
Original file line numberDiff line numberDiff line change
@@ -28,4 +28,6 @@
2828
(info "Running tako from main...")
2929
(binding [tako.github/github-token (first args)
3030
tako.slack/slack-webhook-url (second args)]
31-
(slack/publish-notifications (github/poll-notifications))))
31+
(while true
32+
(slack/publish-notifications (github/poll-notifications))
33+
(Thread/sleep 60000))))

0 commit comments

Comments
 (0)