README.md

stalkr micro service which feeds our clients with GitHub push events.

---

Table of Contents

• Usage
  • A Few Technical Notes
    • WebHooks
    • Pusher
    • GitHub
  • Getting Started
    • Locally
    • Deploying
      • now.sh
    • On GitHub
    • On The TV

Usage

A Few Technical Notes

WebHooks

Webhooks are user-defined HTTP callbacks which are usually triggered by some event, such as pushing code to a repository–which is what happens here–or a comment being posted to a blog. When that event occurs, the source platform makes an HTTP request to the URI which as been previously set for the webhook.

Users can set them to cause events on one site to invoke behaviour on another. The action taken may be anything. Common uses are to trigger builds with continuous integration systems or to notify bug tracking systems–and that's how stalkr works. Since they use HTTP, they can be integrated into web services without adding new infrastructure.

Pusher

We intend to work over a bunch of different realtime frameworks–e.g. Socket.IO, Primus and ws–and services–e.g. Ably, PubNub and Pusher itself–based on a commom protocol for transporters.

But now Pusher has shown to achieve good documentation/examples, a solid API, and great backend/debug tools, which led us to deal, in our Minimum Viable Product, only with Pusher.

Then you need to create an account, and make a note of your app_id, app_key and app_secret for each project you'd like to integrate with stalkr.

GitHub

Depending on how much push events your repo triggers, it can be necessary to add a Github API token:

1. Head on over to your settings to manage personal API tokens.

2. Then clink on Generate new token.

3. Put the description which is more expressive for you.

4. Check both repo and user scopes.

5. Then click on Generate token.

Getting Started

Locally

1. Make sure you define the ENV variables below:

   # Pusher credentials
   export PUSHER_ID='123456'
   export PUSHER_KEY='4JEUi0C2UT49m872Euc5'
   export PUSHER_SECRET='Bzx2MlrMbNtBpZv391J1'
   
   # GitHub credentials
   export GITHUB_TOKEN='5K78650K9PGuTHgbVOGl26l9nQ6JuLyS'
   
   # Basic stalkr cell metadata
   export STALKR_TEAM='myTeam'
   export STALKR_PROJECT='myProject'

2. Clone this repository:

   git clone https://github.com/stalkr-io/github-commits-feed

3. Install all dependencies:

   # via npm
   npm install
   # or using yarn
   yarn

4. Launch it:

   # via npm
   npm start
   # or using yarn
   yarn start

If everything goes okay, it should now be running at localhost:3000.

Deploying

now.sh

1. Install now globally:

   # via npm
   npm install -g now
   # or using yarn
   yarn global add now

2. Run now with the -e flag to define these environment variables:

   now -e PUSHER_ID='123456' \
          PUSHER_KEY='4JEUi0C2UT49m872Euc5' \
          PUSHER_SECRET='Bzx2MlrMbNtBpZv391J1' \
          GITHUB_TOKEN='5K78650K9PGuTHgbVOGl26l9nQ6JuLyS' \
          STALKR_TEAM='myTeam' \
          STALKR_PROJECT='myProject'

On GitHub

1. Sign in, then select the related repository you own.

2. Click on Settings on the top panel.

3. Then click on Webhooks & Services on the left panel.

4. Click on the Add WebHook Button.

5. Paste the URL where you've deployed your stalkr webhook in the URL form field.

6. Select application/json as the content type.

7. Remain the Just the push event. checkbox checked.

8. Remain the Active checkbox checked.

9. Click on Add webhook to save the webhook.

Your configuration should look similar to this:

On The TV

1. Install the Stalkr on your  TV

2. Go to New Dashboard tab.

   We recommend the use of one iPhone or remote keyboard to set the config in inputs.

3. You don't need to fill all the steps, but only the section Dashboard and, in the next sections, you'll need to fill only if you want this cell in your dashboard.

4. In order to know how to set a "Pusher Key" parameter, see the Pusher section.

---

Maintainer:

ythecombinator.me  ·  GitHub @ythecombinator  ·  Twitter @ythecombinator