Keybase notifications for github actions

Keybase is a service and tool that makes cryptography easier and more accessible for the masses. It offers end-to-end encrypted chat, encrypted git repositories, cloud storage and a mechanism for proving your identity amongst other services.

For automating tasks or building websites I typically setup a notification to inform me when the process has completed. In large organizations I might have this as a slack notification or an email. For personal projects I don’t want to fill my inbox or sign up for a whole personal slack org just for a message. While there are plenty of existing systems to receive a notification (irc, sms or discord come to mind). Using keybase to notify me seemed like a perfect way to handle this.

For this setup I’m using a github repo and action that is building my website and deploying it. Once its deployed I’m sending the notification to myself via a keybase bot.

To get started if you aren’t already using keybase then head over to keybase.io and register and setup your account. Once that’s done we are going to need to create a bot that can send messages to us.

Creating a bot

To create a bot we first need to create a bot token. This is a base64 token and it will allow us to sign up bots.

Create a bot token

keybase bot token create > /tmp/bot_token

Signup the bot

Now we have the bot token we can signup a bot. We pass in a home directory to avoid picking up the existing keybase account. We also pass standalone mode and the bot username in order to run the client and service in the same process and exist at the same time. The output of the signup is a paper key. This bot has one keypair and that is a paper key and there are no device keys.

keybase --standalone --home=/tmp/bot bot signup -u bot_name_here -t $(cat /tmp/bot_token) > paper-key

Now we have the bot signed up and our paper key for the bot we can create our github action that has a step that will notify us.

Setting up the notification job

To send the keybase notification we are going to use the keybase docker image from here https://hub.docker.com/r/keybaseio/client. We can use a public docker image in the github action by referencing uses: docker:// and then the name of the image. In this case we are going to be using docker://keybaseio/client:stable

In your github repo if you don’t already have a github action or workflow create a file at the following location /.github/workflows/ci.yaml with the contents below.

name: CI
on:
  push:
    branches:
      - 'master'

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      # ... steps where you do something here ...
      - name: Build Live Notification
        env:
          JSON_MSG: >-
            {
                "method": "send",
                "params": {
                    "options": {"channel": {"name": "your_keybase_username"},
                    "message": {"body": "Deploy to live is complete! https://davidejones.com/"}}
                }
            }            
        run: echo $JSON_MSG > message.json
      - name: Keybase Notification
        uses: docker://keybaseio/client:stable
        env:
          KEYBASE_USERNAME: "your_keybase_bot_username"
          KEYBASE_PAPERKEY: "${{ secrets.PAPERKEY }}"
          KEYBASE_SERVICE: "1"
        with:
          args: keybase chat api -i message.json

This has 2 steps to it.

• Step 1 is to build a json payload that we can pass to step 2
• Step 2 will take the json payload and pass it to the keybase api

A few things to note, this is the more verbose way of sending a message which I opted to do so that I could replace variables in the payload and use other keybase features in the api. For simplicity you could instead just do one step of sending a message with a command like this

keybase chat send "your_keybase_username" "message goes here"

Lastly for any of this to function you will need to add a github secret with your bots paper key to the github repository. Make sure to name the secret PAPERKEY and it will get passed as the KEYBASE_PAPERKEY environment variable to the keybase docker image.

After that you should start recieving notifications from github on keybase quick and easily.