This Slack bot improves the workflow of development teams. Especially with focus on Jenkins, Github, Gitlab and Jira, as the integration is working out of the box. But also custom commands, macros, crons and other project specific commands can be implemented in a simple and flexible way.
- Create a Slack App
- Select "From an app manifest"
- Select your Workspace
- Paste this Yaml code:
Click to expand!
_metadata:
major_version: 1
minor_version: 1
display_information:
name: slack_bot
features:
app_home:
messages_tab_enabled: true
messages_tab_read_only_enabled: false
bot_user:
display_name: bot
always_online: true
oauth_config:
scopes:
bot:
- app_mentions:read
- channels:read
- chat:write
- im:history
- im:write
- mpim:history
- reactions:read
- reactions:write
- users:read
- files:write
settings:
event_subscriptions:
bot_events:
- app_mention
- message.im
interactivity:
is_enabled: true
org_deploy_enabled: false
socket_mode_enabled: true
- Create the App!
- Go to "Basic Information"
- -> in "App-Level Tokens", "Generate a Token" with the scope "connections:write"
- You will see a App-Level Token (beginning with xapp-). Set it in the config.yaml as slack.socket_token.
- Go to "OAuth & Permissions":
- -> "Install to Workspace"
- -> you should see a "Bot User OAuth Access Token" (beginning with "xoxb-"). Use it as slack.token in the config.yaml
- start the bot!
Expand steps!
- Create a [Slack App](https://api.slack.com/apps?new_app=1) - Select from scratch and choose a name and workspace. - Go to "Socket Mode" menu and activate it. - - use any token name, like "Slack-Bot Socket Mode token" - - You will see a App-Level Token (beginning with xapp-). Sse it in the config.yaml as slack.socket_token. - Enable "Interactivity & Shortcuts" - Enable "Event Subscriptions": - - if you see a "Send events to my app using the new format" checkbox, check it (only for old migrated apps) - - in "Subscribe to bot events", add "app_mention" and "message.im" events - Go to "OAuth & Permissions": - - use the "Bot User OAuth Access Token" (beginning with "xoxb-") as slack.token in the config.yaml - - in "Scopes" we need this permissions: "app_mentions:read", "channels:read", "chat:write", "im:history", "im:write", "users:read", "reactions:read", "reactions:write" - Go to "Install your App" and "Install your app to your workspace" - Back to "Install app" tab, the "Bot User OAuth Access Token" is visible (starts with "xoxb-"). You need this one in the config.yaml in slack->token.- install go (at least 1.18)
- create a config.yaml (at least a slack token is required) or take a look in config-example.yaml
go run github.com/innogames/slack-bot/v2/cmd/bot
- install Docker incl. docker-compose
- clone this repo or at least fetch the docker-compose.yaml
- create a config.yaml (at least a slack token is required) or take a look in config-example.yaml
- add your Slack user id or user name in the "allowed_users:" section of the config.yaml
docker-compose up
- install go (at least 1.16)
- clone/fork this repo
- create a config.yaml (at least a slack token is required) or take a look in config-example.yaml
- run
go run cmd/bot/main.go
ormake run
to run the go application
As slack user, you just have to send a private message to the bot user/app containing the command to execute.
Additionally you can execute bot commands in channels by prefix your command with @bot_name, e.g. @slack-bot start job DailyDeployment
Note: You have to invite the bot into the channel to be able to handle commands.
The help
command just prints a list of all available commands of this bot.
With help *command*
you'll get a short description and some examples for a single command.
The bot is able to start and monitor jenkins job on a simple but powerful way.
By default the commands are not available and not visible in the "help", till the "jenkins.host" is defined in the config file.
The start job
command starts a Jenkins job and shows the current progress. Attention: only whitelisted jobs in the config are startable!
In additions each job can have a configurable trigger
which make it possible to create custom commands to start jobs. (it's a regexp which takes parameter names into account).
E.g. "start daily deployment" could be the trigger for one jenkins job. Sending this text to the bot would start he job.
After starting a job the bot will show the estimated build time and some action buttons. There you can open the logs or abort the build directly.
The bot is also able to parse parameters and lookup branch names using a fuzzy branch search.
Examples:
trigger job DeployBeta
start job BackendTests TEST-123
(search for a full branch name, containing TEST-123. e.g. feature/TEST-123-added-feature-456)
The bot has also the possibility to create one time notifications for jenkins builds. This might be useful for long running jobs where the devs is waiting for the result.
Example:
inform me about build NightlyTests
(watches the most recent running build)inform me about build MyJobName #423
(specify a build number)inform job MyJobName
(alternative syntax)
Receive slack messages for all process builds for the given job:
Example:
watch JenkinsSelfCheck
notifies about any build of JobJenkinsSelfCheck
unwatch JenkinsSelfCheck
Small command to disable/enable job execution on Jenkins side.
Example:
disable job NightlyTests
(disable job on jenkins)enable job NightlyTests
When a build failed you are able to retry any build by:
Example:
retry build NightlyTests
(retries the last build of a job)retry build NightlyTests #100
(retries given build)
jenkins nodes
lists all available Jenkins nodes. The online/offline status and number of executors are visible.
If you just paste a link to a Github/Gitlab/Bitbucket/Stash Pull request, the bot will track the state of the ticket!
- When a developer was added as reviewer, it will add a "eyes" reaction to show other devs that someone is already taking a look
- When the reviewer approved the ticket, a checkmark is added
- After merging the pull request, it will add a "merge" reaction
You're also able to set custom "approved" reactions. E.g to see directly who or which component/department approved a pull request you can use the name of the reaction or the Unicode character directory
Expand example!
pullrequest:
reactions:
merged: custom_merge_arrow
review: 👀
custom_approve_reaction:
nerdydev: "approved_backend"
iamamobiledev: "approved_mobile"
iamamobiledev2: "approved_mobile"
Extra Features:
For Bitbucket the bot is able to extract the current build status (e.g. from Jenkins/Bamboo etc) and show failed and running builds (fire reaction) as a reaction (circle arrow reaction). When the build is stable, the build reactions disappear.
The queue
command (with the alias then
) is able to queue the given command, until the currently running command finished.
Example following scenario: you have a build job (which might take some minutes) and a deploy job which relies of the build artifacts. Now you can do:
trigger job Build feature1234
to start the Build job with given branchqueue trigger job DeployBranch feature1234
queue reply Deployment is done!
Other example:
delay 1h
then send message #backend coffee time?
To see all running background commands (like Jenkins jobs or PR watcher) use this command:
list queue
The bot is able to query information from Jira, either from a single ticket, or a whole list of tickets.
By default the commands are not available and not visible in the "help", till the "jira.host" is defined in the config file.
Examples
jira TEST-1234
jira 1242
(opens the ticket, using the configured default jira project)jql type=bug and status=open
(use default project by default)jira "Second city"
(text search of tickets in default project)
It's also possible to get a notification when there is a state change in a certain Jira ticket.
Example
watch ticket PROJ-12234
It's possible to create buttons which are performing any bot action when pressing the button. Slack interactions
Examples:
add button "Start Deployment" "trigger job LiveDeployment"
Note
- only whitelisted users can click the button
- each button is only active once
Configure user specific variables to customize bot behaviour. E.g. each developer has his own server environment.
Example: Having this global config:
commands:
- name: Deploy
trigger: "deploy (?P<branch>.*)"
commands:
- deploy {{.branch}} to {{ customVariable "defaultServer" }}
Each developer can now call ONCE this commands like: set variable defaultSerer foobarX.local
to register the custom "defaultServer".
When now calling deploy mater
, it will deploy the master
branch to foobarX.local
server.
Another example
Here an advanced version which uses Go templates.
In the end the command will generate one subcommand, like:
reply <!here> demo for <https://jira.example.com/TEST-1234|TEST-1234: Example-Ticket>
which will post the link to the Slack channel.
- name: demo
trigger: "demo (?P<ticketId>\\w+-\\d+)"
commands:
- |
{{ $ticket := jiraTicket .ticketId }}
{{ if $ticket }}
reply <!here> demo for <{{ jiraTicketUrl $ticket.Key }}|{{ $ticket.Key }}: {{ $ticket.Fields.Summary }}>
{{ else }}
reply Ticket {{ .ticketId }} not found :white_frowning_face:
{{ end }}
description: Informs the current channel about a demo of a Jira ticket. It directly posts a link to the ticket
examples:
- demo XYZ-1232
User can define his default environment once by using set variable serverEnvironment aws-02
.
Then the deploy feature-123
will deploy the branch to the defined aws-02
environment.
Each user can define his own variables.
If you need a small break and want to play a little quiz game you can do so by calling this command. No more than 50 questions are allowed. The questions are from different categories and difficult levels and are either multiple choice or true/false questions.
Commands
quiz 10
to start a quiz with 10 questionsanswer 1
to answer a question with the first answer
It's possible to setup OpenWeatherMap to get information about the current weather at your location.
Example config:
open_weather:
apikey: "612325WD623562376678"
location: "Hamburg, DE"
units: "metric"
Every user is able to define own command aliases. This is a handy feature to avoid typing the same command every day.
Example usage
list commands
to just list the defined commands for the current useradd command 'myCommand' 'trigger job RestoreWorld 7
-> then just callmyCommand
lateradd command 'build master' 'trigger job Deploy master ; then trigger job DeployClient master'
delete command 'build master'
- -> then you can execute
myCommand
to trigger this jenkins job
Defined "Commands" (former called "Macros") are very magical and can be defined in the yaml configuration files.
They have a trigger (a regular expression) and have a list of sub commands which will be executed. They take parameter groups from regexp into account - so they can be very flexible!
One simple example to start two Jenkins jobs with a given branch name at the same time:
commands:
- name: build clients
trigger: "build clients (?P<branch>.*)"
commands:
- "reply I'll build {{ .branch }} for you"
- "trigger job BuildFrontendClient {{ .branch }}"
- "trigger job BuildMobileClient {{ .branch }}"
- "then reply done! :checkmark:"
Note: In the commands you can use the full set of template features of go -> loops/conditions are possible!
Beside the usual template features of go a bunch of bot specific commands are available in the template scope.
A list of all available functions (with arguments and return types) can be generated by using the list template functions
command.
Note: This template functions can be used in different commands/features:
- Crons
- Defined commands (via .yaml)
- Custom commands (defined per user)
- Jenkins hooks (lik send custom message when a Job fails)
With retry
or repeat
your last executed command will be re-executed. -> Useful when a failed Jenkins job got fixed.
A small command which might be useful in combination with command
command or as hook for jenkins jobs.
Example command: delay 10m trigger job DeployWorldwide
As reply you'll get a command to stop the queued job (like stop timer 123456
). As everyone can send the command, the command can be used to announce a deployment and in doubt, the execution can still be stopped by everyone.
Reply / send message
reply
and send message
are also small commands which are useful in combination with command
or jenkins hooks.
Examples:
send message to #backend The job failed :panic:
delay 10m send message to @peter_pan I should notify you to...
Simple command if you are not able to decide between different options
Examples
random Pizza Pasta
-> produce either "Pizza" or "Pasta"random Peter Paul Tom Jan
-> who has to take about organizing food today?
- Make sure Go version 1.12+ is installed
- clone the project
- create config file called
config.yaml
(you can take a look atconfig.example.yaml
)
This command will start the bot, using the config.yaml
file by default. Use the -config
argument to use the config file(s) from another location.
go run cmd/bot/main.go
Attention: Create a config.yaml file first
docker-compose up
The configuration is managed via simple .yaml files which are storing the credentials for the external services and the custom commands etc.
The easiest way is to just have one config.yaml
file with all needed options included the config.yaml
is loaded by default. It's also possible to split up the configuration into multiple files.
Example structure with mutiple config files:
secret.yaml
containing the credentials for the external services (slack, jenkins) - can be managed by puppet/ansible etc.jenkins.yaml
configuration of jenkins job and their parameters etcproject-X.yaml
custom commands for a specific teamproject-Y.yaml
To load the multiple config files, use go run cmd/bot/main.go -config /path/to/config/*.yaml
which merged all configs together.
To run this bot, you need a "bot token" for your slack application. See the installation section how to create a proper app with the needed tokens.
To be able to start or monitor jenkins jobs, you have to setup the host and the credentials first. The user needs read access to the jobs and the right to trigger jobs for your whitelisted jobs.
jenkins:
host: https://jenkins.example.de
username: jenkinsuser
password: secret
To be able to start a job, the job and it's parameters have to be defined in the config.
A job without any parameter looks very simple:
jenkins:
jobs:
CleanupJob:
Then you can use trigger job CleanupJob
or start job CleanupJob
to start the job. It will also notify you when the job succeeded or failed (incl. error log).
Next a job with two parameters:
jenkins:
jobs:
RunTests:
parameters:
- name: BRANCH
default: master
type: branch
- name: GROUP
default: all
This job can handle two parameters:
- BRANCH: VCS branch name, "master" as default
- GROUP: optional parameter, using "all" as default
If you setup the VSC in the config, you don't have to pass the full branch name but can use the fuzzy search.
Example:
start job RunTests
would start "all" groups on master branchstart job JIRA-1224 unit
would try to find a matching branch for the ticket number. (Error message if there is no unique search result!)
Now a more complex example with more magic:
jenkins:
jobs:
DeployBranch:
trigger: "deploy (?P<BRANCH>[\\w\\-_\\.\\/]*) to (?P<ENVIRONMENT>prod|test|dev)"
parameters:
- name: BRANCH
default: master
type: branch
- name: ENVIRONMENT
onsuccess:
- reply Tadaa: Take a look on http://{{ .ENVIRONMENT }}.example.com
Step by step:
The trigger
is a regular expression to start the job which may contain named groups. The regexp groups will be matched to the job parameters automatically.
Then you can use deploy bugfix-1234 to test
to start the jenkins job.
Note: You can always start this job also via start job DeployBranch master
. The trigger
is just an alternative.
The onsuccess
is a hook which will be executed when a job ist started via this bot.
In addition onsuccess
and onerror
is also available...e.g. to send custom error messages.
It's possible to define periodical commands via crons, using the robfig/cron library.
Example config
crons:
- schedule: "0 8 * * *"
commands:
- trigger job BuildClients
- then deploy master to staging
channel: "#backend"
To be able to resolve branch names in jenkins trigger, a VCS system can be configured (at the moment it's just Stash/Bitbucket).
vcs:
type: bitbucket
host: https://bitbucket.example.com
username: readonlyuser
password: secret
project: MyProjectKey
repository: repo_name
If no config is provided, there is no automated branch lookup and the "branch" parameters are passed 1:1 to the jenkins job.
bot/
contains the code classes of the bot: connection to slack, user management, command matching...cmd/bot/
entry points aka main.go for the bot and the CLI test toolcommand/
real command implementing the bot.Command interfaceclient/
communication interfaces for Slack, Jenkins, Jira etc...
If you need a new command, which is not implementable with a "command" command, you have to write to write go code.
- create a new file within the "commands/" directory or one submodule of it
- create a new struct which fulfills the bot.Command interface. The service.SlackClient might be needed as dependency
- GetMatcher() needs to provide the information which command text is matching our command
- register the command in command/commands.go
- restart the bot application
- it's recommended to fulfill the bot.HelpProvider (your command will show up in `help)
- it's also recommended to create a integration test for your command
There is a handy CLI application which emulates the Slack application...just chat with your local console without any Slack connection!
make run-cli
make air
to use the "air auto reload tool".
There are a bunch of tests which can be executed via:
make test
Test coverage is generated to build/coverage.html
make test-coverage