Skip to main content

Sync github, bitbucket, and trac issues with taskwarrior

Project description

bugwarrior is a command line utility for updating your local taskwarrior database from your forge issue trackers.

It currently supports the following remote resources:


Create a ~/.bugwarriorrc file with the following contents.

# Example ~/.bugwarriorrc
# Use "password = @oracle:use_keyring" to retrieve a password from a keyring.
# Use "password = @oracle:ask_password" to ask the user for the password.
# Use "password = @oracle:eval:<command>" to use the output of <command> as the password.
# Note that using one of these strategies is in general more secure
# than storing a password in plain text.

# General stuff.
# Here you define a comma separated list of targets.  Each of them must have a
# section below determining their properties, how to query them, etc.  The name
# is just a symbol, and doesn't have any functional importance.
targets = my_github, my_bitbucket, paj_bitbucket, moksha_trac, bz.redhat

# log.level specifices the verbosity.  The default is DEBUG.
#log.level = DEBUG

# If log.file is specified, output will be redirected there.  If it remains
# unspecified, output is sent to sys.stderr
#log.file = /var/log/bugwarrior.log

# The bitly username and api key are used to shorten URLs to the issues for your
# task list.  If you leave these options commented out, then the full URLs
# will be used in your task list.
#bitly.api_user = YOUR_USERNAME
#bitly.api_key = YOUR_API_KEY

# This is an experimental mode where bugwarrior will query all of your
# online sources simultaneously.  It works as far as I've tested it, so
# give it a try.  Please backup your ~/.task/ directory first and report
# any problems if you encounter them at
#multiprocessing = False

# Configure the default description or annotation length.
#annotation_length = 45
#description_length = 35

# This section is for configuring notifications when bugwarrior-pull runs,
# and when issues are created, updated, or deleted by bugwarrior-pull.
# Three backend are currently suported:
#  - growlnotify (v2)   Mac OS X   "gntp" must be installed
#  - gobject            Linux      python gobject must be installed
#  - pynotify           Linux      "pynotify" must be installed
# To configure, adjust the settings below.  Note that neither of the
# "sticky" options have any effect on Linux with pynotify.  They only work
# for growlnotify.
# notifications = True
# backend = growlnotify
# finished_querying_sticky = False
# task_crud_sticky = True

# This is a github example.  It says, "scrape every issue from every repository
# on  It doesn't matter if ralphbean owns the issue
# or not."
service = github
username = ralphbean
default_priority = H

# I want taskwarrior to include issues from all my repos, except these
# two because they're spammy or something.
exclude_repos = project_bar,project_baz

# Working with a large number of projects, instead of excluding most of them I
# can also simply include just a limited set.
include_repos = project_foo,project_foz

# Note that login and username can be different.  I can login as me, but
# scrape issues from an organization's repos.
login = ralphbean
passw = OMG_LULZ

# This is the same thing, but for bitbucket.  Each target entry must have a
# 'service' attribute which must be one of the supported services (like
# 'github', 'bitbucket', 'trac', etc...).
service = bitbucket
username = ralphbean
default_priority = M

# Here's another bitbucket one.  Here we want to scrape the issues from repos of
# another user, but only include them in the taskwarrior db if they're assigned
# to me.
service = bitbucket
username = paj
only_if_assigned = ralphbean
default_priority = L

# Here's an example of a trac target.  Scrape every ticket and only include them
# if 1) they're owned by me or 2) they're currently unassigned.
# Note -- You must have the trac XML-RPC plugin installed and configured to work
# over HTTP.
service = trac

trac.base_uri =
trac.username = ralph
trac.password = OMG_LULZ

only_if_assigned = ralph
also_unassigned = True
default_priority = H

# Here's an example of a bugzilla target.  This will scrape every ticket
# 1) that is not closed and 2) that is either the
# owner or reporter or is cc'd on.  Bugzilla instances can be quite different
# from one another so use this with caution and please report bugs so we can
# make bugwarrior support more robust!
service = bugzilla

bugzilla.base_uri =
bugzilla.username =
bugzilla.password = OMG_LULZ

# Here's an example of a megaplan target.
service = megaplan

hostname =
login = alice
password = secret

default_priority = H
project_name = example

# Here's an example of a jira project. The ``jira-python`` module is
# a bit particular, and jira deployments, like Bugzilla, tend to be
# reasonably customized. So YMMV. The ``base_uri`` must not have a
# have a trailing slash. In this case we fetch comments and
# cases from jira assigned to 'ralph' where the status is not closed or
# resolved.
service = jira
jira.base_uri =
jira.username = ralph
jira.password = OMG_LULZ
jira.query = assignee = ralph and status != closed and status != resolved
jira.project_prefix = Programming.
# Set this to your jira major version. We currently support only jira version
# 4 and 5(the default). You can find your particular version in the footer at
# the dashboard.
jira.version = 5

# Here's an example of a teamlab target.
service = teamlab

hostname =
login = alice
password = secret

project_name = example_teamlab

# Here's an example of a redmine target.
service = redmine
url =
key = c0c4c014cafebabe
user_id = 7
project_name = redmine

# Here's an example of an activecollab3 target. This is only valid for
# activeCollab 3.x, see below for activeCollab 2.x.
# Obtain your user ID and API url by logging in, clicking on your avatar on
# the lower left-hand of the page. When on that page, look at the URL. The
# number that appears after "/user/" is your user ID.
# On the same page, go to Options and API Subscriptions. Generate a read-only
# API key and add that to your bugwarriorrc file.
# Bugwarrior will only gather tasks and subtasks for projects in your "Favorites"
# list. Note that if you have 10 projects in your favorites list, bugwarrior
# will make 21 API calls on each run: 1 call to get a list of favorites, then
# 2 API calls per projects, one for tasks and one for subtasks.

service = activecollab3
url =
key = your-api-key
user_id = 15

# Here's an example of an activecollab2 target. Note that this will only work
# with ActiveCollab 2.x - see above for 3.x.
# You can obtain your user ID and API url by logging into ActiveCollab and
# clicking on "Profile" and then "API Settings". When on that page, look
# at the URL. The integer that appears after "/user/" is your user ID.
# Projects should be entered in a comma-separated list, with the project
# id as the key and the name you'd like to use for the project in Taskwarrior
# entered as the value. For example, if the project ID is 8 and the project's
# name in ActiveCollab is "Amazing Website" then you might enter 8:amazing_website
# Note that due to limitations in the ActiveCollab API, there is no simple way
# to get a list of all tasks you are responsible for in AC. Instead you need to
# look at each ticket that you are subscribed to and check to see if your
# user ID is responsible for the ticket/task. What this means is that if you
# have 5 projects you want to query and each project has 20 tickets, you'll
# make 100 API requests each time you run `bugwarrior-pull`

service = activecollab2
url =
key = your-api-key
user_id = 15
projects = 1:first_project, 5:another_project


Just run bugwarrior-pull.

It’s ideal to create a cron task like:

*/15 * * * *  /usr/bin/bugwarrior-pull

Bugwarrior can emit desktop notifications when it adds or completes issues to and from your local ~/.task/ db. If your ~/.bugwarriorrc file has notifications turned on, you’ll also need to tell cron which display to use by adding the following to your crontab:

*/15 * * * *  /usr/bin/bugwarrior-pull

Getting bugwarrior

Installing from the Python Package Index

Installing it from is easy with pip:

$ pip install bugwarrior

Alternatively, you can use easy_install if you prefer:

$ easy_install bugwarrior

Installing from Source

You can find the source on github at Either fork/clone if you plan to do development on bugwarrior, or you can simply download the latest tarball:

$ wget -O bugwarrior-latest.tar.gz
$ tar -xzvf bugwarrior-latest.tar.gz
$ cd ralphbean-bugwarrior-*
$ python install

Hacking on It

You should install the virtualenv tool for python. (I use a wrapper for it called virtualenvwrapper which is awesome but not required.) Virtualenv will help isolate your dependencies from the rest of your system.

$ sudo yum install python-virtualenv git
$ mkdir -p ~/virtualenvs/
$ virtualenv ~/virtualenvs/bugwarrior

You should now have a virtualenv in a ~/virtualenvs/ directory. To use it, you need to “activate” it like this:

$ source ~/virtualenv/bugwarrior/bin/activate
(bugwarrior)$ which python

At any time, you can deactivate it by typing deactivate at the command prompt.

Next step – get the code!

(bugwarrior)$ git clone
(bugwarrior)$ cd bugwarrior
(bugwarrior)$ python develop
(bugwarrior)$ which bugwarrior-pull

This will actually run it.. be careful and back up your task directory!

(bugwarrior)$ bugwarrior-pull


  • Ralph Bean (primary author)
  • Justin Forest (contributed support for RedMine, TeamLab, and MegaPlan, as well as some unicode help)
  • Tycho Garen (contributed support for Jira)
  • Kosta Harlan (contributed support for ActiveCollab 2.x/3.x, notifications, and experimental taskw support)
  • Luke Macken (contributed some code cleaning)
  • James Rowe (contributed to the docs)

Project details

Release history Release notifications

History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
bugwarrior-0.7.0.tar.gz (40.1 kB) Copy SHA256 hash SHA256 Source None Jan 21, 2014

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page