outofcoffee/corebot repository overview

⁠Corebot: A Slack bot for Rundeck and Jenkins

Trigger your Rundeck⁠ or Jenkins⁠ jobs from Slack⁠.

Example:

@corebot deploy user-service 1.0 to staging

> corebot:
> OK, I'm deploying user-service version 1.0 to staging.
> Status of job is: running
> Details: http://rundeck/jobs/abc/123

⁠What can it do?

⁠Trigger your deployment jobs

⁠Trigger your other custom jobs

⁠Lock things to prevent accidental deployment

⁠Unlock things you've locked

⁠Get help

⁠Instructions

• As a Slack admin, create a Slack bot user and obtain its auth token
• As a Rundeck admin, generate a Rundeck API token
• Set environment variables
• Run!

⁠Quick start

The quickest way to get up and running is to use the Docker image:

docker run -d \
        --env SLACK_AUTH_TOKEN="CHANGEME" \
        --env SLACK_CHANNEL_NAME="corebot" \
        --env RUNDECK_API_TOKEN="CHANGEME" \
        --env RUNDECK_BASE_URL="http://rundeck:4440" \
        -v /path/to/actions.yml:/opt/corebot/actions.yml \
        outofcoffee/corebot

Note: the container doesn't require any inbound ports to be exposed.

⁠Actions and configuration

The bot has both built-in actions and custom actions. Examples of built in actions are the lock/unlock actions. Custom actions are triggers for your Rundeck jobs, configured using a configuration file, typically called actions.yml.

⁠Action configuration file

Example:

version: '1'
actions:
  services:
    jobId: 9374f1c8-7b3f-4145-8556-6b55551fb60f
    template: deploy services {version} to {environment}

File structure:

• All files must specify version ‘1’
• All actions must sit under a top level actions block
• Each action must have a name (it’s services in this example)
• Each action must have a Rundeck job ID (obtain this from Rundeck)
• Each action must have a template - more details below
• Each action may optionally specify a map of default options
• Each action may optionally specify a list of tags

⁠Action template

An action template provides the syntax for invoking the command.

Example:

deploy services

A template also allows you to specify job options as placeholders, such as:

deploy services {version} to {environment}

In this example both version and environment are captured from the command, such as:

@corebot deploy services 1.0 to UAT

This will result in the action being fired, passing the following options:

• version=1.0
• environment=UAT

⁠Default options

Sometimes you might want to pass an option to a job by default, and not require the user to provide it. You can do this with the options action block:

version: '1'
actions:
  services:
    jobId: 9374f1c8-7b3f-4145-8556-6b55551fb60f
    template: deploy services {version} to {environment}
    options:
	    myOption: someValue

This will result in the action being fired, passing the following options:

• version=1.0
• environment=UAT
• myOption=someValue

⁠Tags and multiple job actions

Sometimes actions can be run on multiple jobs. To do this, set the tags block:

version: '1'
actions:
  deploy-services:
    jobId: 9374f1c8-7b3f-4145-8556-6b55551fb60f
    template: deploy services {version} to {environment}
    tags:
	    - services
	    
  restart-services:
    jobId: e9d12eec-abff-4780-89cd-56a48b8c67be
    template: restart services in {environment}
    tags:
	    - services

Here, two actions are defined: deploy-services and restart-services, both tagged with services. This means you can do things like:

@corebot lock services

…and both actions will be locked.

⁠Built-in actions

There are a number of built in actions, such as:

• @corebot lock {action name or tag} - lock action(s) to prevent them being triggered accidentally.
• @corebot unlock {action name or tag} - unlock locked action(s).
• @corebot status {action name or tag} - show status of action(s).
• @corebot enable {action name or tag} - set the Rundeck execution status for a job - Note: this requires the Rundeck ACL to permit the API user to set the execution status of a job.
• @corebot disable {action name or tag} - set the Rundeck execution status for a job - Note: this requires the Rundeck ACL to permit the API user to set the execution status of a job.

⁠Contributing

Pull requests accepted at https://github.com/outofcoffee/corebot⁠

⁠More info

Slack API: https://api.slack.com/bot-users⁠

Rundeck API: http://rundeck.org/2.6.9/api/index.html#running-a-job⁠

⁠Rundeck

Any Rundeck instance can be used as long as it supports API v14 or higher.

As an example, here is an unofficial Rundeck Docker image: https://hub.docker.com/r/jordan/rundeck/⁠

docker run -it \
    -p 4440:4440 \
    -e SERVER_URL=http://localhost:4440 \
    jordan/rundeck