A library for extracting actionable data from development tools

metrics, jira, github, development
pip install augurlib==1.1.62


Augur Developer Metrics

Help team leads, managers and developers track progress, improvement, gaps by combing data from multiple tools into an easy to use dashboard using the Augur Development Method.

This is a library that can be easily included into any client that wants to collect data using ADM.

Augur Installation

To install, you can do one of the following:

Install on command line

pip install augur 

Without changing your global index, this will install augur using the custom index this once.

Install in requirements.txt

Then include augur as you would any other package:


Augur Development

To upload a new version of augur, you can modify your .pypirc file with the following:

.... # whatever indexes you already had in there


You can use fabric to build and publish.

>> pip install -g fabric
>> cd /path/to/augur
>> fab publish:bump_version_type=<major,minor or patch>,upload=<True,False>,update_in_vcs=<True,False>

fab publish can perform all aspects of deployment optionally. By default, it will only build
a new package. But you can also have it automatically bump the version (major,minor or patch), publish the new build to whatever artifact repo you've configured in .pypirc and automically commit and push the changes to git.

Augur Integration


In order to use Augur there are some settings that it expects to be accessible via environment variables. In some cases, there are defaults that are applied, in other cases, the initialization will fail if not specified.

Environment Variable Purpose Default Example
JIRA_INSTANCE The full url to the JIRA instance to use Required
JIRA_USERNAME The full url to the JIRA instance to use Required A username
JIRA_PASSWORD The full url to the JIRA instance to use Required It's a password
JIRA_API_PATH Relpath to root of rest endpoints rest/api/2 rest/api/2
DB_TYPE What type of database to use Required postgres
CONFLUENCE_INSTANCE The full url to the Confluence instance JIRA_INSTANCE
CONFLUENCE_USERNAME The full url to the Confluence instance JIRA_USERNAME A username
CONFLUENCE_PASSWORD The full url to the Confluence instance JIRA_PASSWORD Another password
GITHUB_BASE_URL The full url to the Github instance Required
GITHUB_LOGIN_TOKEN The token of the user that should be used Required cbab75c1....
to access the API for the instance of
github specificed in GITHUB_BASE_URL
GITHUB_CLIENT_ID The client ID that has been registered Required e3d808650b4f45f9ac03
for the client that is using this
instance of the Augur library
GITHUB_CLIENT_SECRET The client secret that has been Required f3d80e650b4d45f9ad15
registered for the client that is using
this instance of the Augur library

Integration with External Tools


There is no explicit requirements for Github setup other than this: Augur was developed from the enterprise edition which means it's more acceptable for Github Organizations to be part of the hierarchy of the codebase.


Groups, Workflows and Teams

Augur now supports creation of custom workflows. To do this, a taxonomy of was created to organize them.

  • Groups
    • Workflow
      • Projects
    • Teams
      • Staff
  • Vendors


A group in Augur is a group of people within an organization that share a common workflow. For example, developers might use a workflow that is different than that used by the marketing team. Groups are described by a single workflow and a set of teams.


While Augur workflows are closely tied to Jira workflows there's not a 1:1 comparison.

A workflow is made up of:

  • Statuses - The various statuses that this workflow includes
  • Resolutions - fixed, completed, etc.
  • Projects - the Jira projects that are considered part of the workflow
  • Project Categories - A jira project category that should be included in this project
  • Issue Types - The types of issues that should be considered identified selected when making queries
  • Defect Projects - Which projects within the list of projects above are used for storing defects

Within a workflow, statuses can be of three types (open, in progress, resolved). This helps us understand what tickets are actively being worked on for metrics purposes.


When a ticket status is set to a resolved state, we look at the resolution types to understand the success or failure of that issue. So each resolution type supported has a type as well: postive or negative. So a positived resolution would be "fixed" and a negative one would be "won't fix"


We can indicate which projects to include by either specifying the project keys individually or using JIRA's project categories which is a more easy to manage because you simply have to set the category of a project in JIRA and it will automatically be included in this workflow.

Issue Types

We can also indicate which issue types we should pay attention to. This is helpful when projects have issue types that are used for tracking information that has nothing to do with the workflow - like individual todo items, etc.

Defect Projects

Finally, defect projects are projects that we specifically call out for consisting entirely of bugs found in production. We can use this information to collect defect metrics over time. A defect project is not necessarily just all tickets in the project but can also be further filtered by the issue type.


Teams are made up of staff who have a long list of attributes associated with each.
We keep information about the staff such as who they work for, email, usernames for different tools, etc.


Sprints are not stored in the augur db explicitly but the agile board ID is used to retrieve sprint information. To ensure that the correct sprints are being read, sprint names must follow a certain format:

<sprint_num> - Team <team_name>

001 - Team Voltron

This is to ensure that only sprints that are associated with the team are included in the metrics. Due to the way Jira works, it is possible for a sprint that is part of a different agile board to be included in the metrics if this formatting restriction is not used.


The Augur database supports notification settings for individual staff members.

Staff can customize notifications by channel and by content. For example, we can turn off email or slack messages for build notification but we can also specify what type of build notifications we want to get.

In the notifications table there are these fields:

  • build - Can be one or more of [slack,email] separated by commas
  • deploy - Can be one or more of [slack,email] separated by commas
  • build_types - Can be one or more of [all,upstream,myteam,otherteams] separated by commas

Build Types Explained

  • All - If all is in there, then everything else is ignored and all build types are sent
  • upstream - This means that notifications for builds that occur in a non-team org and are the master branch will be sent
  • myteam - This means that notification for builds that occur in the committers own team org will be sent
  • otherteams - This means that notifications for builds that occur in team orgs other than the committers will be sent.