Agile Bot
Agile bot is a free and open source integration between Atlassian Jira and Discord. Support for other Agile and Kanban platforms may appear in the future, but for now it is only Jira.
Usage Examples
Simply run a command with the key for a project or issue in order to have the bot embed it.!
Multiple commands in a single line are supported.!
As are groups of tasks.
Custom JQL and other advanced Queries are also available. For examples, see Property Overrides below.
Property Overrides
Each property of TaskParams in Commands.cs can be overridden using the syntax defined by Discord.NET. The names of properties are not case-sensitive. Arguments with spaces can be surrounded by quotes.
The fields are as follows:
Max: The maximum number of tasks to display. Defaults to 10.
User: Search for tasks with this user as an assignee. Discord names will be mapped to Jira names as specified in the
settings.json
. Defaults to the querying user.Project: The project to search. No default.
Type: The type of Jira story to search. Default changes depending on whether
!tasks
or!bugs
was called.Status: The status of the tasks to search for. Defaults to "In Progress" as specified in the
settings.json
if!tasks
was called or "Bug" if!bugs
was called.OrderBy: How the tasks should be ordered in the Discord embed. Defaults to "priority".
Order: How the ordering should be displayed in the Discord embed. Defaults to "desc" (Descending).
PreJql: A JQL statement that is prepended to the other fields with an "AND" statment. Can be used to combine JQL and the other fields. No default.
Jql: A raw JQL statment that will cause any other fields to be ignored. No default.
An example of Property Overrides:
!tasks project:PWS status: "In Progress" User: Scion
An example of a PreJql query:
!tasks PWS Done OrderBy: created PreJql: "createdDate <= '2021/06/30' AND createdDate >= '2021/06/29'"
An example of a Jql query:
!tasks jql: "status = Done AND assignee = scion AND createdDate <= '2021/06/30' AND createdDate >= '2021/06/29' ORDER BY priority DESC"
Running the bot
Simply download and build the project for your desired hosting platform and run the application next to a settings.json
file. settings.json.example
provides an example.
Adding a Bot to your Discord Server
- Go to: https://discord.com/developers/applications
- Create a new application.
- Activate: Settings->Bot
- Reveal the Token and copy it to the "bot_token" setting.
- Under OAuth2, select the "bot" Scope and copy the URL. DO NOT SHARE THIS TOKEN!
- Visit the URL in your browser and Authorize the bot to join your desired server.
Authorizing the Bot with Jira
Install the .NET SDK for the dotnet command line tool if you have not already. Now you need to use the Jira OAuth CLI tool to authorize the application to your Jira instance.
- Run
dotnet tool install -g jira-oauth-cli
- Run
jira-oauth-cli get-keys
- Visit your Jira instance's Application links, enter whatever you think is appropriate for this first form but select 'Generate incoming link' and click next.
- Application links can be found under
Settings->Products->Application links
in Jira Cloud andSettings->Applications->Application links
in Jira Server/Data Center.
- Application links can be found under
- Input a custom
Consumer Key
and remember it. - Paste in the
Public Key
from Step 2. - Run
jira-oauth-cli get-tokens --url <Your_Atlassian_Root_URL> -u <Username> -p <Password> -k <Step4_Consumer_Key> -s <Step2_Private_Key>
- Visit the output URL in your browser and authorize the app.
- In settings.json set the following from the output:
"Consumer Key:" -> "consumer_key"
"Consumer Secret:" -> "consumer_secret"
"Access Token:" -> "oauth_token"
"Token Secret:" -> "oauth_secret"
DO NOT SHARE ANY OF THESE TOKENS!
Now just run the bot and, if all goes well, you should see it appear as active in your Discord server. Happy sprinting!
Running the bot in a docker container
For convenience, create a .env
file and set it up with all the tokens from before. Like so:
BOT_TOKEN=<ex: Discord Bot token>
JIRA_URL=<ex: https://myjirainstance.atlassian.net/>
CONSUMER_KEY=<ex: Jira_Bot>
CONSUMER_SECRET=<ex: Massive string>
OAUTH_TOKEN=<ex: Token string>
OAUTH_SECRET=<ex: Secret string>
Then modify settings.json
to your needs (notice the environment variables names being used correspond with the ones in .env
), you can use docker compose to bring up the container.
docker-compose up -d --build
You could also build the image.
docker build . -t agile-bot
And then run it.
docker run -d \
--name=agile-bot \
--restart unless-stopped \
--env-file ./.env \
agile-bot