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

Why would you want this? Check out ChatOps.

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 access token - instructions
As a Rundeck admin, generate a Rundeck API token - instructions
Set environment variables
Run!

Getting started

The quickest way to get up and running is to use our free cloud-hosted version at https://www.remotebot.io/bot

Docker

If you'd like to run Corebot yourself as a Docker container, you can do the following:

docker run -d \
        --env SLACK_AUTH_TOKEN="CHANGEME" \
        --env SLACK_CHANNELS="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 does not require any inbound ports to be exposed.

Note: See the Environment variables section for the available configuration settings.

Creating a Slack app

As a Slack admin, create a 'Classic App' in Slack: https://api.slack.com/apps?new_classic_app=1

Add a bot user by expanding 'Add features and functionality', and clicking on Bots:

https://api.slack.com/apps/<your app ID>/app-home

Add the required scopes in the 'OAuth & Permissions' section:

https://api.slack.com/apps/<your app ID>/oauth

The scopes are:

chat:write:bot

Don't forget to save changes after adding scopes.

Install your app to your workspace. This will generate the token you need. You'll want to copy the 'Bot User OAuth Access Token'. It should look like this:

xoxp-123456789012-123456789012-abcdef1234567890abcdef1234567890

Drivers

Corebot's capabilities are determined by its driver. For example, a driver might allow you to interact with a CI/CD system.

Jenkins driver

A modern version (1.7+) of Jenkins is required - version 2.x or higher is preferred.

Here is the official Jenkins Docker image:

docker run -it \
    -p 8080:8080 \
    jenkins

Example usage:

@corebot deploy services v2 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

Rundeck driver

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

Example usage:

@corebot deploy services v2 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

Items driver

The items driver acts like a lending library. It allows users to borrow, return, or evict users from items in the library.

An example use case is a group of people reserving a server/environment.

Example usage:

@corebot list
> corebot:
> dev1 - no one is borrowing
> dev2 - in use by @alice, @bob
> staging - no one is borrowing

@corebot borrow dev1 for bugfixing
> corebot:
> OK, you've borrowed dev1

@corebot return dev1
> corebot:
> OK, you've returned dev1

Configuration

Environment variables

Configure the bot using the following environment variables.

Common variables

SLACK_AUTH_TOKEN="CHANGEME"
SLACK_CHANNELS="corebot"
ACTION_CONFIG_FILE="/path/to/actions.yaml"

Note: SLACK_CHANNELS is a comma-separated list of channel names, such as "channelA,channelB". You can also use regular expressions to match channel names, such as "channel.*".

Note: the default path for ACTION_CONFIG_FILE is /opt/corebot/actions.yml. When using corebot within a Docker container, it is typical to add your configuration file at this location, or bind-mount a file to this path.

Variables for Rundeck

RUNDECK_API_TOKEN="CHANGEME"
RUNDECK_BASE_URL="http://rundeck:4440"

Note: ensure that the API token you generate in Rundeck has the necessary permissions to trigger builds. For more information, consult the Rundeck ACL documentation.

Variables for Jenkins

JENKINS_BASE_URL="http://localhost:8080"
JENKINS_USERNAME="CHANGEME"
JENKINS_PASSWORD="CHANGEME"
JENKINS_API_TOKEN="CHANGEME"

Note: typically you will specify the username and password for accessing a Jenkins instance. The token approach is rarely used and can be omitted.

Advanced variables

Advanced variables to tune behaviour and performance:

CACHE_EXPIRY="60"

The cache expiry controls the period of time, in seconds, corebot holds the action configuration in memory after reading it from file.

EXECUTION_STATUS_TIMEOUT="120"
EXECUTION_STATUS_POLL="10"

The execution status timeout controls the period of time, in seconds, corebot will poll a running job for status updates, after which it gives up. You can also control the polling interval, also in seconds.

SLACK_REPLY_IN_THREAD="true"

Posts replies from the bot to a thread starting from the trigger message. Default: false.

SLACK_ALLOW_THREADED_TRIGGERS="true"

Allows child thread messages to be trigger messages. Implies SLACK_REPLY_IN_THREAD="true". Default: false.

CHAT_GENERATOR_FILE="/path/to/file.yml"

The path to an external YAML file containing custom chat lines. See the default file, default-chat.yml, for examples.

SYSTEM_CONFIG_FILE="/path/to/file.yml"

The path to an external YAML file containing system configuration. See the sample file, system.yml, for examples.

Operations and actions

Corebot has both built-in operations and external actions. Examples of built in operations are the lock/unlock actions. External actions are triggers for your Rundeck/Jenkins jobs, configured using a configuration file, typically called actions.yml.

Action configuration file

Note: the configuration file path is specified with the ACTION_CONFIG_FILE environment variable.

Example file:

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 either:
- a Rundeck job ID (obtain this from Rundeck), or
- a Jenkins job name
Each action must have a template - more details below
Each action may optionally specify a list of tags
Each action may optionally specify option configuration, such as:
- static values
- value transformers
- whether the option can be locked

Tip: Check out the examples/config directory for sample configuration files.

Action driver

Actions should specify a driver. The available drivers are:

jenkins - use this to allow users to trigger Jenkins jobs
rundeck - use this to allow users to trigger Rundeck jobs
items - use this to allow users to borrow/return a set of items (e.g. books, servers etc.)

Note: if none is specified, the driver is assumed to be rundeck.

Example:

version: '1'
actions:
  services:
    driver: jenkins
    jobId: my-jenkins-job
    template: deploy web {version} to {environment}

Important: Ensure that you set the environment variables corresponding to the driver(s) you use, such as the base URL, API key/username etc.

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

Static option values

You might want to pass an option value to a job every time, and not require the user to provide it. You can accomplish this using the value property of an option within the options action block:

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

Corebot

Install / Use

README

Corebot: A Slack bot for Rundeck and Jenkins

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

Getting started

Docker

Creating a Slack app

Drivers

Jenkins driver

Rundeck driver

Items driver

Configuration

Environment variables

Common variables

Variables for Rundeck

Variables for Jenkins

Advanced variables

Operations and actions

Action configuration file

Action driver

Action template

Static option values