{"id":21487646,"url":"https://github.com/outofcoffee/corebot","last_synced_at":"2025-07-15T15:31:32.796Z","repository":{"id":52347819,"uuid":"71644979","full_name":"outofcoffee/corebot","owner":"outofcoffee","description":"A bot to trigger Rundeck and Jenkins jobs from Slack.","archived":false,"fork":false,"pushed_at":"2023-03-02T11:15:55.000Z","size":1436,"stargazers_count":74,"open_issues_count":19,"forks_count":15,"subscribers_count":8,"default_branch":"master","last_synced_at":"2023-08-08T01:35:02.640Z","etag":null,"topics":["chatops","deployment","jenkins","rundeck","slack-bot"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/outofcoffee.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-22T14:40:54.000Z","updated_at":"2023-03-06T06:05:05.000Z","dependencies_parsed_at":"2023-01-30T03:15:41.021Z","dependency_job_id":null,"html_url":"https://github.com/outofcoffee/corebot","commit_stats":null,"previous_names":[],"tags_count":27,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outofcoffee%2Fcorebot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outofcoffee%2Fcorebot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outofcoffee%2Fcorebot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outofcoffee%2Fcorebot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/outofcoffee","download_url":"https://codeload.github.com/outofcoffee/corebot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226048174,"owners_count":17565479,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatops","deployment","jenkins","rundeck","slack-bot"],"created_at":"2024-11-23T13:29:57.506Z","updated_at":"2024-11-23T13:29:58.075Z","avatar_url":"https://github.com/outofcoffee.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Corebot: A Slack bot for Rundeck and Jenkins [![CI](https://github.com/outofcoffee/corebot/actions/workflows/ci.yaml/badge.svg)](https://github.com/outofcoffee/corebot/actions/workflows/ci.yaml)\n\nTrigger your [Rundeck](http://rundeck.org) or [Jenkins](https://jenkins.io) jobs from [Slack](https://slack.com).\n\n_Example:_\n\n    @corebot deploy user-service 1.0 to staging\n    \u003e corebot:\n    \u003e OK, I'm deploying user-service version 1.0 to staging.\n    \u003e Status of job is: running\n    \u003e Details: http://rundeck/jobs/abc/123\n\n\u003e Why would you want this? Check out [ChatOps](http://blogs.atlassian.com/2016/01/what-is-chatops-adoption-guide/).\n\n## What can it do?\n\n##### Trigger your deployment jobs\n\n\u003cimg alt=\"Deploy\" src=\"https://github.com/outofcoffee/corebot/raw/master/docs/images/deploy.png\" width=\"467\"\u003e\n\n##### Trigger your other custom jobs\n\n\u003cimg alt=\"Restart\" src=\"https://github.com/outofcoffee/corebot/raw/master/docs/images/restart.png\" width=\"472\"\u003e\n\n##### Lock things to prevent accidental deployment\n\n\u003cimg alt=\"Lock deployment failure\" src=\"https://github.com/outofcoffee/corebot/raw/master/docs/images/lock_deploy_fail.png\" width=\"371\"\u003e\n\n##### Unlock things you've locked\n\n\u003cimg alt=\"Unlock job\" src=\"https://github.com/outofcoffee/corebot/raw/master/docs/images/unlock.png\" width=\"336\"\u003e\n\n##### Get help\n\n\u003cimg alt=\"Help\" src=\"https://github.com/outofcoffee/corebot/raw/master/docs/images/unknown.png\" width=\"389\"\u003e\n\n## Instructions\n\n* As a Slack admin, create a Slack bot user and obtain its access token - [instructions](https://my.slack.com/services/new/bot)\n* As a Rundeck admin, generate a Rundeck API token - [instructions](http://rundeck.org/2.6.9/api/index.html#token-authentication)\n* Set environment variables\n* Run!\n\n## Getting started\n\nThe quickest way to get up and running is to use our free cloud-hosted version at [https://www.remotebot.io/bot](https://www.remotebot.io/bot)\n\n## Docker\n\nIf you'd like to run Corebot yourself as a Docker container, you can do the following:\n\n    docker run -d \\\n            --env SLACK_AUTH_TOKEN=\"CHANGEME\" \\\n            --env SLACK_CHANNELS=\"corebot\" \\\n            --env RUNDECK_API_TOKEN=\"CHANGEME\" \\\n            --env RUNDECK_BASE_URL=\"http://rundeck:4440\" \\\n            -v /path/to/actions.yml:/opt/corebot/actions.yml \\\n            outofcoffee/corebot\n\n\u003e Note: the container does not require any inbound ports to be exposed.\n\n\u003e Note: See the _Environment variables_ section for the available configuration settings.\n\n## Creating a Slack app\n\nAs a Slack admin, create a 'Classic App' in Slack: https://api.slack.com/apps?new_classic_app=1\n\nAdd a bot user by expanding 'Add features and functionality', and clicking on Bots:\n\n    https://api.slack.com/apps/\u003cyour app ID\u003e/app-home\n\nAdd the required scopes in the 'OAuth \u0026 Permissions' section:\n\n    https://api.slack.com/apps/\u003cyour app ID\u003e/oauth\n\nThe scopes are:\n\n    chat:write:bot\n\n\u003e Don't forget to save changes after adding scopes.\n\nInstall 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:\n\n    xoxp-123456789012-123456789012-abcdef1234567890abcdef1234567890\n\n## Drivers\n\nCorebot's capabilities are determined by its driver. For example, a driver might allow you to interact with a CI/CD system.\n\n### Jenkins driver\n\nA modern version (1.7+) of Jenkins is required - version 2.x or higher is preferred.\n\nHere is the official Jenkins Docker image:\n\n    docker run -it \\\n        -p 8080:8080 \\\n        jenkins\n\nExample usage:\n\n    @corebot deploy services v2 to staging\n    \u003e corebot:\n    \u003e OK, I'm deploying user-service version 1.0 to staging.\n    \u003e Status of job is: running\n    \u003e Details: http://rundeck/jobs/abc/123\n\n### Rundeck driver\n\nAny Rundeck instance can be used as long as it supports API v14 or higher.\n\nAs an example, here is an unofficial Rundeck Docker image: https://hub.docker.com/r/jordan/rundeck/\n\n    docker run -it \\\n        -p 4440:4440 \\\n        -e SERVER_URL=http://localhost:4440 \\\n        jordan/rundeck\n\nExample usage:\n\n    @corebot deploy services v2 to staging\n    \u003e corebot:\n    \u003e OK, I'm deploying user-service version 1.0 to staging.\n    \u003e Status of job is: running\n    \u003e Details: http://rundeck/jobs/abc/123\n\n### Items driver\n\nThe items driver acts like a lending library. It allows users to borrow, return, or evict users from items in the library.\n\nAn example use case is a group of people reserving a server/environment.\n\nExample usage:\n\n    @corebot list\n    \u003e corebot:\n    \u003e dev1 - no one is borrowing\n    \u003e dev2 - in use by @alice, @bob\n    \u003e staging - no one is borrowing\n    \n    @corebot borrow dev1 for bugfixing\n    \u003e corebot:\n    \u003e OK, you've borrowed dev1\n    \n    @corebot return dev1\n    \u003e corebot:\n    \u003e OK, you've returned dev1\n\n## Configuration\n\n### Environment variables\n\nConfigure the bot using the following environment variables.\n\n#### Common variables\n\n    SLACK_AUTH_TOKEN=\"CHANGEME\"\n    SLACK_CHANNELS=\"corebot\"\n    ACTION_CONFIG_FILE=\"/path/to/actions.yaml\"\n    \n\u003e 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.*\"`.\n\n\u003e 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.\n\n#### Variables for Rundeck\n\n    RUNDECK_API_TOKEN=\"CHANGEME\"\n    RUNDECK_BASE_URL=\"http://rundeck:4440\"\n\n\u003e 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.\n\n#### Variables for Jenkins\n\n    JENKINS_BASE_URL=\"http://localhost:8080\"\n    JENKINS_USERNAME=\"CHANGEME\"\n    JENKINS_PASSWORD=\"CHANGEME\"\n    JENKINS_API_TOKEN=\"CHANGEME\"\n    \n\u003e Note: typically you will specify the username and password for accessing a Jenkins instance. The token approach is rarely used and can be omitted.\n\n#### Advanced variables\n\nAdvanced variables to tune behaviour and performance:\n\n    CACHE_EXPIRY=\"60\"\n\nThe cache expiry controls the period of time, in seconds, corebot holds the action configuration in memory after reading it from file.\n\n    EXECUTION_STATUS_TIMEOUT=\"120\"\n    EXECUTION_STATUS_POLL=\"10\"\n\nThe 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.\n\n    SLACK_REPLY_IN_THREAD=\"true\"\n    \nPosts replies from the bot to a thread starting from the trigger message. Default: `false`.\n    \n    SLACK_ALLOW_THREADED_TRIGGERS=\"true\"\n    \nAllows child thread messages to be trigger messages. Implies `SLACK_REPLY_IN_THREAD=\"true\"`. Default: `false`.\n\n    CHAT_GENERATOR_FILE=\"/path/to/file.yml\"\n    \nThe path to an external YAML file containing custom chat lines. See the default file, `default-chat.yml`, for examples.\n\n    SYSTEM_CONFIG_FILE=\"/path/to/file.yml\"\n\nThe path to an external YAML file containing system configuration. See the sample file, `system.yml`, for examples.\n\n### Operations and actions\n\nCorebot 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`.\n\n#### Action configuration file\n\n\u003e Note: the configuration file path is specified with the `ACTION_CONFIG_FILE` environment variable.\n\n_Example file:_\n```\nversion: '1'\nactions:\n  services:\n    jobId: 9374f1c8-7b3f-4145-8556-6b55551fb60f\n    template: deploy services {version} to {environment}\n```\n\nFile structure:\n\n* All files must specify version ‘1’\n* All actions must sit under a top level `actions` block\n* Each action must have a name (it’s `services` in this example)\n* Each action must have either:\n  * a Rundeck job ID (obtain this from Rundeck), or\n  * a Jenkins job name\n* Each action must have a template - more details below\n* Each action may optionally specify a list of tags\n* Each action may optionally specify option configuration, such as:\n  * static values\n  * value transformers\n  * whether the option can be locked\n  \n\u003e Tip: Check out the `examples/config` directory for sample configuration files.\n\n#### Action driver\n\nActions should specify a driver. The available drivers are:\n\n* jenkins - use this to allow users to trigger Jenkins jobs\n* rundeck - use this to allow users to trigger Rundeck jobs\n* items - use this to allow users to borrow/return a set of items (e.g. books, servers etc.)\n\n\u003e Note: if none is specified, the driver is assumed to be `rundeck`.\n\n_Example:_\n```\nversion: '1'\nactions:\n  services:\n    driver: jenkins\n    jobId: my-jenkins-job\n    template: deploy web {version} to {environment}\n```\n\n**Important:** Ensure that you set the environment variables corresponding to the driver(s) you use, such as the base URL, API key/username etc.\n\n#### Action template\n\nAn action template provides the syntax for invoking the command. \n\n_Example:_\n\n\tdeploy services\n\nA template also allows you to specify job options as placeholders, such as:\n\n\tdeploy services {version} to {environment}\n\nIn this example both _version_ and _environment_ are captured from the command, such as:\n\n\t@corebot deploy services 1.0 to UAT\n\nThis will result in the action being fired, passing the following options:\n\n- version=1.0\n- environment=UAT\n\n#### Static option values\n\nYou 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:\n\n```\nversion: '1'\nactions:\n  services:\n    jobId: 9374f1c8-7b3f-4145-8556-6b55551fb60f\n    template: deploy services {version} to {environment}\n    options:\n      myOption:\n        value: someValue\n      myOtherOption:\n        value: someOtherValue\n```\n\nThis will result in the action being fired, passing the following options:\n\n- version=1.0\n- environment=UAT\n- _myOption=someValue_\n- _myOtherOption=someOtherValue_\n\n#### Transforming options\n\nYou might want to transform an option value provided by a user before it is passed to a job. You can accomplish this using the `transformers` section of an option within the `options` action block:\n\n```\nversion: '1'\nactions:\n  services:\n    jobId: 9374f1c8-7b3f-4145-8556-6b55551fb60f\n    template: deploy services {version} to {environment}\n    options:\n      version:\n        transformers:\n          - LOWERCASE\n      environment:\n        transformers:\n          - UPPERCASE\n```\n\nIf the user typed this command:\n\n    @corebot deploy services V1.0 to uat\n\nThis will result in the action being fired, passing the following options:\n\n- version=v1.0 (note: lowercased)\n- environment=UAT (note: uppercased)\n\n#### Locking options\n\nYou might want to lock an option value, so that it cannot be passed to an action.\n\n\u003e Example: If you have an option to specify the environment for a deployment, you might wish to lock deployments to the environment named 'production'.\n\nYou can accomplish this using the `lockable` property of an option within the `options` action block:\n\n```\nversion: '1'\nactions:\n  services:\n    jobId: 9374f1c8-7b3f-4145-8556-6b55551fb60f\n    template: deploy services {version} to {environment}\n    options:\n      environment:\n        lockable: true\n```\n\nIf the user typed this command:\n\n    @corebot lock environment prod\n\nThis will result in a lock being placed on the 'environment' option, with the value 'prod'.\n\nWith the lock applied, this will fail:\n\n    @corebot deploy services 1.0 to prod\n    \n...but this will still succeed:\n\n    @corebot deploy services 1.0 to uat\n    \nYou can of course unlock the option with:\n\n    @corebot unlock environment prod\n    \n\u003e Note: It's strongly advisable to apply a _transformer_ to lockable options, to ensure the value 'prod' is considered equivalent to 'PROD'.\n\n#### Tags and multiple job actions\n\nSometimes actions can be run on multiple jobs. To do this, set the `tags` block:\n\n```\nversion: '1'\nactions:\n  deploy-services:\n    jobId: 9374f1c8-7b3f-4145-8556-6b55551fb60f\n    template: deploy services {version} to {environment}\n    tags:\n\t  - services\n\t    \n  restart-services:\n    jobId: e9d12eec-abff-4780-89cd-56a48b8c67be\n    template: restart services in {environment}\n    tags:\n\t  - services\n```\n\nHere, two actions are defined: `deploy-services` and `restart-services`, both tagged with `services`. This means you can do things like:\n\n\t@corebot lock services\n\n…and both actions will be locked.\n\n\u003e Tip: There is a special tag set on all actions, named 'all'. This means you can do things like `@corebot lock all`.\n\n#### Customised output\n\nSometimes the bots reaction is enough to see the status. To do this, set the `showJobOutcome` option to `false`. Default is `true`.\n \nSometimes the output of the job is needed to be given back by the bot. To do this, set the `showJobOutput` option to `true`. Default is `false`.\n\n```\nversion: '1'\nactions:\n  deploy-services:\n    jobId: 9374f1c8-7b3f-4145-8556-6b55551fb60f\n    template: deploy services {version} to {environment}\n    showJobOutput: true\n    showJobOutcome: false    \n```\n\n#### Security\n\nYou can choose which users are authorised to perform actions, using the `security` block:\n\n```\nsecurity:\n  users:\n    # alice uses the built-in 'admin' role\n    alice:\n      roles:\n        - admin\n```\n\u003e *Important:* if you do not specify a security configuration explicitly, the default will be used. The default settings permit all users to perform all actions.\n\nThere is a built in role, named `admin`, which you can assign to users. You can also define your own roles, listing the permissions granted to users with that role.\n\nYou can assign roles on a per-username basis or, if you wish to assign certain roles to all users, use the special `\"*\"` key, as shown in the example below:\n\n```\nsecurity:\n  roles:\n    # a role that can only trigger jobs\n    deployer:\n      permissions:\n        - trigger\n\n  users:\n    # alice uses the built-in 'admin' role\n    alice:\n      roles:\n        - admin\n\n    # all users can trigger jobs\n    \"*\":\n      roles:\n        - deployer\n```\n\nBy default, role definitions apply to all actions. If you wish to restrict the permissions granted by a role to certain actions only, add a tag to the action and also to the corresponding `tags` array in the role:\n \n```\nsecurity:\n  roles:\n    # a role that can only trigger jobs\n    deployer:\n      permissions:\n        - trigger\n    \n    # this role only permits triggering of actions tagged with 'services'\n      tags:\n        - services\n```\n\n### Built-in actions\n\nThere are a number of built in actions, such as:\n\n* `@corebot help` - show usage information.\n* `@corebot lock {action or tag name}` - lock action(s) to prevent them being triggered accidentally.\n* `@corebot unlock {action or tag name}` - unlock locked action(s).\n* `@corebot status {action or tag name}` - show status of action(s).\n* `@corebot lock {option name} {option value}` - lock an option with a given value.\n* `@corebot unlock {option name} {option value}` - unlock an option with a given value.\n* `@corebot status {option name} {option value}` - show status of an option with a given value.\n* `@corebot enable {action or tag name}` - 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.\n* `@corebot disable {action or tag name}` - 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.\n\n### System and shared/default configuration\n\nYou can set some default operations for all actions using the system configuration file.\n\nThe path to this file is specified using the `SYSTEM_CONFIG_FILE` environment variable.\n\nAn example configuration follows:\n\n    # System configuration\n    ---\n    version: '1'\n    \n    system:\n      defaults:\n        driver: jenkins\n        showJobOutput: false\n        showJobOutcome: true\n        runAsTriggerUser: false\n        \n        options:\n          myVar:\n            value: someDefaultValue\n    \n      requestHeaders:\n        Cookie: \"foo=bar\"\n\nThe example above sets a number of default values, which can be overridden by your individual action configurations.\n \nThis example also specifies a map of HTTP headers to set on each API request to the external build/deployment systems. These headers will be sent to Jenkins and Rundeck when making any requests.\n\n## Plugins\n\nCorebot supports plugins, loaded dynamically at startup.\n\n### Plugin categories\n\nThe following plugin categories are supported:\n\n* front-ends (e.g. Slack, WebSocket)\n* back-ends (e.g. Rundeck, Jenkins, Items)\n* stores (e.g. MySQL, Redis)\n\n### Plugin distribution\n\nPlugins are packaged and distributed as WAR files and include all required dependencies.\n\n### Loading plugins\n\nYou can load plugins by using the `generic-bot` distribution.\n\n\u003e See `bots/generic/README.md` for information.\n\u003e See the `examples/plugins` directory for plugin configuration examples.\n\n## Building\n\nIf you wish to build and run locally, you can run:\n\n    ./gradlew installDist\n    docker-compose build\n\nOnce built, set the environment variables in `docker-compose.yml`. See the _Environment variables_ section.\n\nThen run with:\n\n    docker-compose up\n\nIf you change anything, don't forget to rebuild before running again.\n\n#### Publishing\n\nDependencies can be published to the project Maven repository.\n\n\u003e Note: Publishing to the repository requires appropriate AWS keys to be set in `gradle.properties`.\n\n## Embedding Corebot in your applications\n\nThe Corebot libraries are published to our Maven repository. You can include them as dependencies in your project.\n\n### Maven dependencies\n\nTo use the dependencies in a project, add the repository:\n\n```\nrepositories {\n    maven {\n        url 'https://s3-eu-west-1.amazonaws.com/gatehillsoftware-maven/snapshots/'\n    }\n    \n    // jitpack required for Slack dependency\n    maven { url \"https://jitpack.io\" }\n}\n```\n\n...then add a dependency:\n\n```\ncompile \"com.gatehill.corebot:core:0.7.0\"\n```\n\n\u003e Note: update the version with the latest stable [release](https://github.com/outofcoffee/corebot/tags).\n\n# Recent changes and Roadmap\n  \nFor recent changes see the [Changelog](CHANGELOG.md), or view the [Roadmap](docs/roadmap.md).\n\n## Contributing\n\n* Pull requests are welcome.\n* PRs should target the `develop` branch.\n* Please run `ktlint` against the code first ;-)\n\n## Author\n\nPete Cornish (outofcoffee@gmail.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foutofcoffee%2Fcorebot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foutofcoffee%2Fcorebot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foutofcoffee%2Fcorebot/lists"}