Issue tracker sync

Defects and change requests can link to GitHub, GitLab, or Jira issues. Configure each project’s tracker under Settings → Integrations. Set Bloom’s INTEGRATION_ENCRYPTION_KEY to encrypt tracker credentials and webhook secrets. Inbound webhooks require an authenticated delivery and reject reused delivery identifiers.

Jira also needs the site URL and the email address owning the API token. Bloom maps Jira status categories to Open, In Progress, and Closed, and uses workflow transitions for outbound status changes.

Each project has one integration per tracker.

Set the encryption key

INTEGRATION_ENCRYPTION_KEY is a Fernet key. It encrypts GitHub, GitLab, and Jira tokens and webhook secrets at rest. Generate it with:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Bloom starts without it: only tracker credential operations fail closed, and Bloom refuses to store an integration. Stored credentials and webhook secrets are never returned through the API. Keep the key with your deployment secrets: a different key makes the configured tracker secrets unreadable until they are rotated.

Webhooks

Inbound webhooks are rejected unless a webhook secret is configured and the delivery is authenticated. Each delivery identifier is accepted only once, so a captured request cannot be replayed.

Tracker	Webhook endpoint	Authentication	Delivery identifier
GitHub	/api/integrations/github/webhook	X-Hub-Signature-256 HMAC	X-GitHub-Delivery
GitLab	/api/integrations/gitlab/webhook	X-Gitlab-Token	X-Gitlab-Event-UUID
Jira	/api/integrations/jira/webhook	X-Hub-Signature HMAC	X-Atlassian-Webhook-Identifier

An unreachable tracker answers 502 (connection, DNS, or a response that is not an issue) or 504 (timeout).

Status

Outbound status changes use the same mapping for defects and change requests. In Jira they are applied as workflow transitions.

Jira

A Jira project can feed a Bloom project: a matching Jira issue creates a defect, and the defect then follows the issue. The direction is Jira to Bloom unless the project turns on two-way sync, which also pushes defect title and status changes to Jira. Two-way sync is off by default.

Jira status names are project-specific, so Bloom maps the issue’s status category:

Jira status category	Bloom status
new	Open
indeterminate	In Progress
done	Closed

Configure the integration

Set INTEGRATION_ENCRYPTION_KEY first. Then, as an administrator, open the project settings, choose Jira under External issue tracker and fill in:

• Site URL of your Jira Cloud site.
• Account email and API token of a Jira account. Jira Cloud authenticates with email:api_token. Create the token in the Atlassian account settings, under Security, API tokens. The email also makes that Bloom user the reporter of the defects. Webhook deliveries need neither. They are stored for this project only, encrypted.
• Webhook secret: any long random string. The same value goes into Jira.
• Jira project key, issue types (default Bug), and optionally a label, a custom field that holds Bloom test case IDs, and extra JQL.
• Priority map from Jira priority to Bloom priority.

Both kinds of Jira token work. A classic API token acts with the account’s own Jira permissions. An API token with scopes needs read:jira-work and read:jira-user, plus write:jira-work for two-way sync, and Bloom calls Jira for it through Atlassian’s API gateway for the site. Bloom checks the credential before each push and reports a token Jira does not accept.

Add the Jira webhook

In Jira, as a site administrator, open Settings, System, WebHooks and create a webhook:

• URL: https://bloom.example.com/api/integrations/jira/webhook
• Secret: the webhook secret entered in Bloom. Jira signs each delivery with it, and Bloom rejects unsigned or wrongly signed deliveries.
• Events: Issue created, updated and deleted. A JQL filter such as project = PRJ keeps the events of other projects away.

What Bloom does with a Jira event

• Created or updated, for an issue with no defect yet: a defect is created when the issue matches the project’s issue types and label. It takes the summary, the description as text, the priority (also as severity) through the map, the issue URL and state. A Bloom test case ID of the project in the summary, the description or the reference field becomes the defect’s source. The defect’s reporter is the Bloom user whose email is the integration’s account email; with no such user it has no reporter.
• Updated, for a linked issue: title, description, priority and state follow Jira. A resolution closes the defect.
• Deleted: the defect stays and its issue state reads Removed in Jira.
• A delivery Jira retries with the same identifier is processed once.