Jira
Connect Jira so tickets can trigger pipelines and track work status.
What this means
Jira integration lets Bilbis connect ticket workflow to pipeline workflow.
When Jira is configured, Bilbis can listen for Jira issue updates, start pipelines when tickets move into configured statuses, and move tickets through the statuses your team expects while work is in progress, in review, and done.
Bilbis has two Jira layers:
- Org-wide Jira config lives in Settings -> Integrations -> Jira and is the default for the organization.
- Per-product Jira override lives on a product detail page and is used only when one product needs different Jira credentials, project keys, statuses, or webhook settings.
When to use it
Use Jira when your team wants to:
- Start Bilbis work from a ticket status, such as
Ready for AI. - Route tickets from different Jira projects to different Bilbis products.
- Keep Jira statuses aligned with pipeline progress.
- Let Jira comments resume a pipeline that is waiting for clarification.
- Use a different Jira project or Jira instance for a specific product.
Before you start
You need:
- Owner or admin access in Bilbis.
- A Jira Cloud or Jira Server/Data Center instance.
- A Jira account email and API token with access to the projects Bilbis should read or update.
- At least one Bilbis product if you want Jira tickets to route to product-specific pipelines.
For Jira Cloud, the account email should match the Atlassian account that owns the API token.
Org-wide Jira fields
| Field | What it means | Default |
|---|---|---|
| Enable Jira | Turns the org-wide Jira config on or off. | Off |
| Jira URL | Base URL for the Jira site, such as https://acme.atlassian.net. | Required |
| Type | Jira Cloud or Jira Server/Data Center. | Cloud |
| Account email | Jira account email tied to the API token. | Optional in the form, usually required for Cloud |
| API token | Token Bilbis uses to talk to Jira. | Required |
| Default project key | Fallback Jira project key when a ticket is not mapped more specifically. | Empty |
| Trigger statuses | Status names that should start a pipeline when a ticket moves into them. | Ready for AI |
| Cancel statuses | Status names that cancel the pipeline if a ticket moves into them. Empty disables auto-cancel. | Empty |
| Hold statuses | Status names that pause the pipeline. Pipeline auto-resumes when the ticket leaves all hold statuses. Empty disables auto-pause. | Empty |
| In-progress status | Status Bilbis can move the ticket to when work starts. | In Progress |
| Review status | Status Bilbis can move the ticket to when the MR/PR is waiting for review. | Code Review |
| Done status | Status Bilbis can move the ticket to after successful completion. | Done |
| Transition field mappings | Field values Bilbis sends to Jira when it moves the ticket to a target status. Required when Jira's workflow demands fields like start_date or end_date on Code Review. See Transition field mappings. | Empty |
| Webhook secret | Shared secret Bilbis embeds in the Jira webhook URL so it can verify which org the call belongs to. | Empty |
| Project mappings | Maps Jira project keys to Bilbis products. | Empty |
Product override fields
Use a product override only when that product should not use the org-wide default.
| Field | What it means |
|---|---|
| Jira URL, type, email, token | Product-specific Jira connection. |
| Project key | Jira project key for this product. |
| Trigger statuses | Product-specific statuses that start pipelines. |
| Cancel statuses | Product-specific statuses that cancel the pipeline. |
| Hold statuses | Product-specific statuses that pause the pipeline. |
| In-progress and done statuses | Product-specific status names. |
| Transition field mappings | Product-specific field values for workflow transitions. Wins over the org-global mapping when set. |
| Webhook shared secret | Product-specific webhook secret. |
| Enable override | Turns this product override on or off. |
The product page also shows an Effective config panel. That panel tells you whether pipelines will use the product override or the org-wide Jira config.
Steps
- Open Settings.
- Open Integrations.
- Open the Jira row.
- Enter the Jira URL.
- Choose Cloud or Server / DC.
- Enter the Jira account email and API token.
- Add the default project key if your organization usually routes tickets from one Jira project.
- Review the trigger, in-progress, review, and done status names.
- Add project mappings if different Jira projects should route to different Bilbis products.
- Add a long random webhook secret.
- Save the Jira config.
- Validate the credential if the button is available.
Trigger, cancel, and hold statuses
Bilbis reacts to three lists of Jira status names. Configure each on the org-wide Jira card or on a per-product override.
| List | What happens when a ticket enters this status |
|---|---|
| Trigger statuses | Bilbis dispatches a pipeline. Default: Ready for AI. |
| Cancel statuses | Bilbis cancels any in-flight pipeline for the ticket. The pipeline ends in Cancelled. Recommended preset: To Do, Backlog, Cancelled, Won't Do. |
| Hold statuses | Bilbis pauses the pipeline at Paused — ticket on hold. The pipeline auto-resumes when the ticket leaves all hold statuses. Recommended preset: On Hold, Blocked. Hold wins over cancel if a status is in both lists. |
Each input is a comma-separated list of Jira status names. Names are case-sensitive at write time but matched case-insensitively at runtime. Click a preset chip below the input to add a recommended value.
Empty cancel or hold lists disable the corresponding behavior.
Transition field mappings
Some Jira workflow transitions require field values before they accept the move. A common case: moving a ticket to Code Review requires customfield_<sprint_start> and customfield_<due_date>. If Bilbis can't supply those values, Jira rejects the transition and the pipeline pauses at Configure Jira fields until an admin updates the mapping.
The Transition field mappings editor lives in the Jira card on Settings → Integrations → Jira (org-wide) and on each product's Jira override page (per-product). Per-product mappings take precedence over the org-wide map for that product.
The editor is grouped by target status. Inside each group you list one row per Jira field ID with its value.
| Mode | When to use it |
|---|---|
| Simple | A plain text or placeholder value. Default. |
| Advanced | A JSON value (object or array). Toggle on the row. Bilbis tries to parse the textarea contents as JSON; if it fails, the value is stored as a literal string. |
Bilbis substitutes these placeholders at transition time:
| Placeholder | Result |
|---|---|
{{today}} | Today's date in YYYY-MM-DD. |
{{today+Nd}} | Today plus N days. N must be between -365 and 365. Example: {{today+7d}}. |
{{now}} | Current ISO timestamp. |
Recommended preset for Code Review:
| Field ID | Value |
|---|---|
customfield_<sprint_start> | {{today}} |
customfield_<due_date> | {{today+7d}} |
Replace <sprint_start> and <due_date> with the real custom field IDs from your Jira instance. Find them in Jira → Project settings → Issue layout or via Jira's REST /rest/api/3/field endpoint.
Empty status name or empty field ID rows are dropped on save - Bilbis will not write { "": { ... } } to the backend.
Configure the Jira webhook
In Jira, create a System WebHook that sends events to Bilbis.
The Jira card shows the exact endpoint to copy. The shape is:
https://api.bilbis.ai/api/v1/webhooks/jira?secret=<your Bilbis webhook secret>Standard Jira System WebHooks can't add custom HTTP headers, so the shared secret rides in the ?secret= query string instead. Bilbis reads the secret from the URL and uses it to look up which org the webhook belongs to.
If you use Jira Automation rules instead of System WebHooks, those can add custom headers - in that case, Bilbis also accepts the secret in the X-Jira-Webhook-Token header.
Subscribe the webhook to at least:
- Issue updated events.
- Comment created events.
Issue updates let Bilbis start pipelines when an issue moves into a trigger status, pause pipelines when it moves into a hold status, and cancel pipelines when it moves into a cancel status. Comments let Bilbis resume pipelines that are waiting for a user reply.
What happens next
When a Jira ticket moves into one of the configured trigger statuses, Bilbis tries to resolve the matching product and repository configuration. If it can resolve the work, it starts a pipeline.
When a Jira comment arrives for a ticket connected to a paused clarification pipeline, Bilbis can use that comment as the user's reply and resume the pipeline. For the answering side of that workflow, see Clarifications and approvals.
Problems and fixes
| Problem | What to check |
|---|---|
| Jira says the webhook is unauthorized | Confirm the X-Jira-Webhook-Token header exactly matches the Bilbis webhook secret. |
| Jira validation fails | Check the Jira URL, Jira type, account email, API token, and provider-side permissions. |
| Saving an existing Jira config fails | Re-enter the Jira API token. Bilbis does not show the saved token again, and some saves replace the credential. |
| Ticket moves status but no pipeline starts | Confirm the status name exactly matches a trigger status and the Jira project maps to a Bilbis product. |
| Product uses the wrong Jira settings | Open the product and check the Effective config panel. It shows whether Bilbis uses the override or org-wide config. |
| A product should not inherit org-wide Jira | Create and enable a per-product Jira override. |
| Jira comments do not resume a pipeline | Confirm Jira sends comment created events and the pipeline is actually waiting for clarification. |