> For the complete documentation index, see [llms.txt](https://docs.hivel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hivel.ai/hybrid-hivel-agent/5.-configuration-reference/jira-settings-jira.md).

# Jira settings (jira: )

jira: is a list, so you can configure one or more Jira instances (Cloud, Server, or Data Center) in the same config.yml. The settings below are grouped by concern: connection details, how far back and how often to sync, which projects to include or exclude, custom field mapping, optional data types, download tuning, and user filtering.

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Key</strong></td><td><strong>Required</strong></td><td><strong>Description</strong></td></tr><tr><td>url</td><td>Yes</td><td>Your Jira instance URL</td></tr><tr><td>instance_slug</td><td>yes</td><td>Unique name for this instance (e.g. jira)</td></tr><tr><td>email</td><td>Cloud only</td><td>Atlassian account email. Omit for Hivel-managed credentials</td></tr><tr><td>token</td><td>Yes (self-hosted)</td><td>API token (Cloud) or PAT (Server/DC). Omit for Hivel-managed credentials - see Hivel-managed credentials below</td></tr><tr><td>username</td><td>Server legacy</td><td>Basic auth username (legacy)</td></tr><tr><td>password</td><td>Server legacy</td><td>Basic auth password (legacy)</td></tr><tr><td>no_verify_ssl</td><td>No</td><td>Skip TLS verification (self-signed certs)</td></tr><tr><td>gdpr_active</td><td>No</td><td>Force Cloud GDPR mode (auto-detected for *.atlassian.net)</td></tr></tbody></table>

**Incremental sync**

| **Key**                             | **Required** | **Default** | **Description**                                     |
| ----------------------------------- | ------------ | ----------- | --------------------------------------------------- |
| earliest\_issue\_date               | First run    | -           | YYYY-MM-DD. Issues updated before this are skipped. |
| issue\_created\_after\_buffer\_days | No           | 180         | Buffer days before earliest\_issue\_date            |

**Project filtering**

| **Key**                      | **Description**                             |
| ---------------------------- | ------------------------------------------- |
| include\_projects            | Only sync these project keys                |
| exclude\_projects            | Always skip these project keys              |
| include\_project\_categories | Only sync projects in these Jira categories |
| exclude\_project\_categories | Skip projects in these categories           |

**Custom fields**

| **Key**                  | **Description**                                       |
| ------------------------ | ----------------------------------------------------- |
| required\_hivel\_types   | Mandatory Hivel semantic types                        |
| extra\_fields            | Custom field IDs to fetch and their semantic mappings |
| exclude\_fields          | Field IDs to omit from payload                        |
| extra\_changelog\_fields | Force-include additional changelog fields             |

**Optional data types**

| **Key**              | **Default** | **Description**                                         |
| -------------------- | ----------- | ------------------------------------------------------- |
| download\_sprints    | false       | Fetch board and sprint data                             |
| download\_worklogs   | false       | Fetch worklogs per issue (expensive)                    |
| download\_changelogs | true        | Issue status transition history (needed for cycle time) |

**Issue download tuning**

| **Key**                              | **Default** | **Description**                               |
| ------------------------------------ | ----------- | --------------------------------------------- |
| issue\_batch\_size                   | 100         | Page size. Cloud max: 100. Server: up to 250. |
| issue\_download\_concurrent\_threads | 10          | Goroutines for concurrent fetching            |
| issue\_jql\_filter                   | -           | Extra JQL appended to every query             |
| recursively\_download\_parents       | false       | Follow parent links to download ancestors     |

**User filtering**

| **Key**                  | **Default** | **Description**                                                                                                  |
| ------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| required\_email\_domains | -           | Only sync users whose email domain is in this list; users with no matching domain are dropped                    |
| is\_email\_required      | false       | Drop users with no email address at all                                                                          |
| skip\_downloading\_users | false       | Skip the user list fetch entirely - use if your token lacks Browse Users permission, or you don't need user data |

{% columns %}
{% column %} <a href="/hybrid-hivel-agent/5.-configuration-reference/hivel-settings-hivel.md" class="button primary" data-icon="backward">Hivel settings</a>
{% endcolumn %}

{% column %}

{% endcolumn %}

{% column %} <a href="/hybrid-hivel-agent/5.-configuration-reference/github-settings-github.md" class="button primary" data-icon="forward">GitHub settings</a>
{% endcolumn %}
{% endcolumns %}