Octobot wants to make your github and slack lives better by triggering more directed pull request notifications to help pull requests from their worst nightmare: remaining un-reviewed.

Octobot isn't content to stop there, it also wants to help merge pull requests to release branches for you. All you have to do is label pull requests with "backport-1.0" (for example). After merging the original PR, it will cherry-pick the commit to "release/1.0" and open up a new PR for you.

Yet still more, octobot also wants to help improve JIRA issue tracking. If a PR is submitted with jira issues in its commits, they will be commented on and transitioned to in-progress/pending-review. When the PR is merged, they will be commented on again, given a pending fix version, and issues marked as fixed will be transitioned to Resolved: Fixed. See JIRA commit references for the exact rules.

• Install docker
• Run build.py

This will result in docker image called octobot:latest that you can deploy as follows:

docker run --restart=always --privileged -d  -p 80:3000 -p 443:3001 --stop-timeout 30 \
       -v /path/to/host/storage/:/data --name octobot --hostname octobot octobot:latest

• Make sure that whatever path you map /data to is a persistent location since this is where configuration is stored.
• Create a config.toml file in this location before deploying (see below).
• On stop, octobot spends up to 25 seconds finishing open requests and background jobs such as backports and Slack messages. The 30 second stop timeout gives it that time; for a podman Quadlet, set StopTimeout=30.

Using podman? use build.py --use-podman

There is one main config file to know about. Hopefully this examples will be sufficiently explanatory:

config.toml

[main]
slack_webhook_url = "<slack webhook URL>"
clone_root_dir = "/home/octobot/repos"
ssl_cert_file = "/data/ssl.crt"
ssl_key_file = "/data/ssl.key"
listen_addr = "0.0.0.0:3000"
listen_addr_ssl = "0.0.0.0:3001"

[github]
webhook_secret = "<secret for github hook>"
host = "git.company.com"
api_token = "<token-for-octobot-user>"

[jira]
# required to enable jira support
host = "jira.company.com"
# for on-premise jira: username/password.
# for jira cloud: the account email as username and an API token as password.
username = <jira username>
password = <jira password>
# alternatively, for on-premise jira only: a personal access token.
# (jira cloud does not support bearer tokens)
#token = <personal access token>

# optional. shown here with defaults:
progress_states = [ "In Progress" ]
review_states = [ "Pending Review" ]
resolved_states = [ "Resolved", "Done" ]
fixed_resolutions = [ "Fixed", "Done" ]
fix_version_field = "fixVersions"

[events]
# optional: enables the gRPC event stream. Plaintext HTTP/2, meant to sit
# behind a TLS-terminating proxy (nginx: `grpc_pass grpc://127.0.0.1:3002;`).
# In docker, listen on 0.0.0.0:3002 and publish it to the proxy only.
listen_addr = "127.0.0.1:3002"
# host[:port] clients dial; they sign it to subscribe.
authority = "octobot.company.com"

For the octobot github user token, you will need to:

• Create and octobot developer app in github for your organization

• Create an octobot user in github

• Run the following command to get a token:

    curl -u octobot https://git.company.com/api/v3/authorizations \
         -d '{"scopes": ["repo"], "client_id": "<app id>", "client_secret": "<app secret>"}'
  

• Grab the "token" value and put it in the config file.

  🚨 Warning 🚨

  This token has read/write access to your code. Guard it carefully and make sure config.toml is only readable by root.

The event stream pushes a thin hint (repo, event, action, PR or issue number) to each GitHub user octobot notifies about a change, so local tools can refetch from GitHub without polling. Hints follow octobot's direct messages: the same events, to the same people, except that they also go to the sender and ignore Slack mute settings. So there are none for draft pull requests, or for events octobot only posts to channels, such as a pull request opening. Only octobot users can subscribe. They authenticate by signing a challenge with an SSH key registered to their GitHub account. An open stream closes within 5 minutes of the user being removed from octobot, and within about 10 minutes of the key being removed from GitHub. The octobot_events crate has the protocol and a client.

A challenge tells anyone who asks whether a login is an octobot user, and lists that user's SSH key fingerprints. A private-mode GitHub Enterprise shows its users as much, so serve the event stream only on the network that can reach it.

The client's subscribe reconnects on its own and yields Reset on every connect, Change for each hint, and Disconnected (with a cause, the error and when it retries) whenever it is not connected. Resync from GitHub on Reset. It signs with an ssh-agent, found through SSH_AUTH_SOCK or a given socket path (AgentSigner), or with an unencrypted key file (ssh_key::PrivateKey).

To configure repositories and users, you will need to login to octobot's web UI, for which you will need to create a password.

   octobot-passwd <path/to/config.toml> <admin username>

This does not need to be run inside the docker container since it just modifies the configuration file.

The UI lives in ui/: Svelte and TypeScript, built by Vite. Run octobot on port 3000, then:

cd ui
npm install
npm run dev

This serves the UI with hot reload and forwards /api and /auth to octobot. Set OCTOBOT_URL to use another address.

The API types in ui/src/bindings are generated from the Rust structs by cargo test; commit them with the Rust change. npm run check type-checks the UI against them.

Release builds embed ui/dist, so run npm run build before cargo build --release. build.py does this for you.

It is highly recommended to enable SSL.

When SSL is enabled, the plain HTTP port will always redirect to HTTPS.

It should be noted that the SSL implementation is very particular about certificates and SNI. Make sure your SSL certificate has a subjectAltName that matches your octobot's hostname exactly.

How a JIRA key is mentioned in a commit message determines what octobot does with it:

• reference: octobot comments on the issue, transitions it to in-progress when the PR is submitted, and adds a pending fix version when the PR is merged.
• resolve: additionally, the issue is transitioned to pending-review when the PR is submitted, and to Resolved: Fixed when the PR is merged.
• comment only: octobot comments on the issue, but does not transition it or add any versions.
• no action: octobot does nothing with the key.

Markers are case-insensitive, allow an optional colon, and accept multiple keys, e.g. Fixes: [ABC-123][ABC-456], ABC-789. Keys must directly follow the marker: prose in between (e.g. part of the ABC-123 epic) does not count, and the key is treated as a bare mention.

Note: Relates to is a temporary migration measure and is only recognized at the start of a line; treat it as deprecated in favor of Part of.

Tested with GitHub Enterprise as well as GitHub.com and primarily with on-premise JIRA. Both on-premise JIRA and JIRA Cloud are supported.

See LICENSE.txt for details.