Jira Bugzilla Integration (JBI)

System to sync Bugzilla bugs to Jira issues.

Caveats

• The system accepts webhook events from Bugzilla
• Bugs' whiteboard tags are used to determine if they should be synchronized or ignored
  • Only public bugs are eligible for synchronization.
• The events are transformed into Jira issues
• The system sets the see_also field of the Bugzilla bug with the URL to the Jira issue
  • No other information is synchronized from Jira to Bugzilla.

Note: whiteboard tags are string between brackets, and can have prefixes/suffixes using dashes (eg. [project], [project-fx-h2], [backlog-project]).

Diagram Overview

graph TD
    subgraph bugzilla services
        A[Bugzilla] -.-|bugzilla event| B[(Webhook Queue)]
        B --- C[Webhook Push Service]
    end
    D --> |create/update/delete issue| E[Jira]
    D<-->|read bug| A
    D -->|update see_also| A
    subgraph jira-bugzilla-integration
        C -.->|post /bugzilla_webhook| D{JBI}
        F["config.{ENV}.yaml"] ---| read actions config| D
    end

Loading

Documentation

• Actions
• Deployment
• Troubleshooting
• RRA for JBI

Usage

How to onboard a new project?

1. Submit configuration for your project

   • If you're comfortable opening your own pull request, add an entry for your whiteboard tag (eg. famous-product) in the actions configuration files. See actions documentation
   • If not, submit an issue here, and we'll set up your configuration

2. Grant permissions to the Jira Automation Bot

   • If you are an admin of the Jira project

     • go to your Jira project and open Project Settings, then People.
     • Select Add People and search for Jira Automation. If two are listed select the one with the green logo
     • From the Roles drop down select Bots. Click Add 1 person.
     • Add these permissions for the bot

        "ADD_COMMENTS",
        "CREATE_ISSUES",
        "DELETE_ISSUES",
        "EDIT_ISSUES"
     

   • If you are not an admin of the Jira project, contact the admin or reach out to #jira-support in Slack to determine how best to request the changes described above

3. Some actions require specific fields on the create and update screens in Jira. Double check the actions documentation

4. Once your configuration is merged and a JBI release is deployed, create a bug in Bugzilla and add your whiteboard tag to the bug. Note that the tag must be enclosed in square brackets (eg. [famous-project]). You should see an issue appear in Jira

   • If you want to start syncing a bug to a Jira issue that already exists, add the issue's link to the See Also section of the Bugzilla bug before you add the whiteboard tag

5. Verify that the action you took on the bug was property reflected on the Jira issue (e.g. the description was updated or a comment was added)

Development

We use pandoc to convert markdown to the Jira syntax. Make sure the binary is found in path or specify your custom location and its version is sufficiently recent to support Jira syntax (e.g. 3.6.3).

• make start: run the application locally (http://localhost:8000)
• make test: run the unit tests suites
• make lint: static analysis of the code base
• make format: automatically format code to align to linting standards

In order to pass arguments to pytest:

poetry run pytest -vv -k test_bugzilla_list_webhooks

You may consider:

• Tweaking the application settings in the .env file (See jbi/environment.py for details)
• Installing a pre-commit hook to lint your changes with pre-commit install