Advanced Configurations

Syncing issues without Parent fields

Overview

In some scenarios, you may need to sync issues from a source system to a target system, but you do not want the Epic (Parent) field to be included for certain issue types. This is useful when, for example, the source issues are linked to Epics, but the target system should not have those Epic associations.

Use Case

Scenario:
You want to sync issues from the source system that may have an Epic, but the synced issues in the target system should not retain the Epic value.

Simple Configuration

Use this approach when you want to exclude Epics for specific issue types (e.g., Task, Bug).

YAML

pushJQL: Project = DEMO
syncSettings:
  ...
  # Other sync settings above
  syncIssuesWithoutParent:
    enabled: true
    conditions:
      issueTypes:
        - 10001 # task
        - 10002 # bug

How it works:

The pushJQL selects issues from the DEMO project.
For issues of type Task (10001) or Bug (10002) that have an Epic, the Epic field will be omitted when syncing to the target system.
Other issue types or issues without an Epic are not affected.

Advanced Configuration

Use this approach for more granular control, such as filtering by additional criteria (e.g., labels, specific issue types).

YAML

pushJQL: Project = DEMO
syncSettings:
  ...
  # Other sync settings above
  syncIssuesWithoutParent:
    enabled: true
    conditions:
      filterJql: Project = DEMO AND issueType IN (Bug) AND labels = demonstation_sync

How it works:

pushJQL still determines which issues are eligible for syncing.
filterJql provides an additional filter: only issues matching this JQL (e.g., Bugs with the label demonstation_sync) will have their Epic field omitted during sync.
Issues must match both pushJQL and filterJql to be synced without Epics.

Precedence:

If both filterJql and issueTypes are configured, filterJql takes precedence.

Important Notes

This configuration does not prevent Epics from being created on the target system. Other issues that do not match the conditions may still require Epics.
If you want to prevent all Epics from being synced, set the Epic mapping in serverFrom.issueTypes to _ignore_.

Summary

Use issueTypes for simple exclusion of Epics by issue type.
Use filterJql for advanced, granular filtering.
Remember that filterJql overrides issueTypes if both are set.
To block all Epic syncing, use the _ignore_ mapping for Epics.

mTLS Configuration (Mutual TLS)

Enable Jira Sync to connect to Jira instances behind API Gateways that require client certificate authentication.

When Do You Need This?

Use mTLS configuration when:

Your Jira Data Center is behind an API Gateway requiring client certificates
Your organization mandates certificate-based authentication

What You'll Need

Request these three PEM-formatted files from your security/infrastructure team:

File	Description	Example
CA Certificate	Certificate Authority that signed the API Gateway's certificate	`cacert.pem`
Client Certificate	Your public certificate for authentication	`client.crt.pem`
Client Private Key	Your private key (keep secure!)	`client.key.pem`

Quick Setup

Add the tls section to your server configuration:

YAML

serverfrom:
  host: api-gateway.example.com
  path: /rest/api/2
  scheme: https
  auth:
    username: your-username
    password: your-password
  tls:
    cacert: /path/to/cacert.pem
    clientcert: /path/to/client.crt.pem
    clientkey: /path/to/client.key.pem

serverto:
  host: target.atlassian.net
  auth:
    username: your-username
    password: your-api-token
  # No TLS section needed - uses standard HTTPS

Success indicator - You should see this log when mTLS is active:

CODE

INFO mTLS enabled for server connection  server="api-gateway.example.com" cacert="/path/to/cacert.pem" clientcert="/path/to/client.crt.pem"

Configuration Reference

Field	Required	Description
`cacert`	Required*	Path to CA certificate for server verification. *Only optional if server uses a public CA.
`clientcert`	Required for mTLS	Path to client certificate. Must be paired with `clientkey`.
`clientkey`	Required for mTLS	Path to client private key. Must be paired with `clientcert`.

Important rules:

clientcert and clientkey must both be present (or both absent)
cacert is required if the API Gateway uses an internal/self-signed certificate (most enterprise setups)
Use absolute paths (e.g., /secrets/cert.pem, not ./certs/cert.pem)
Files must be PEM format (not PKCS#12/.p12/.pfx)
TLS 1.2 minimum is enforced automatically

Example Configurations

mTLS for Source Only (Most Common)

Internal Jira DC behind API Gateway → External Jira Cloud

YAML

serverfrom:
  host: api-gateway.internal.company.com
  scheme: https
  auth:
    username: sync-user
    password: password
  tls:
    cacert: /secrets/cacert.pem
    clientcert: /secrets/client.crt.pem
    clientkey: /secrets/client.key.pem
  projectkey: INTERNAL

serverto:
  host: company.atlassian.net
  iscloud: true
  auth:
    username: sync-user@company.com
    password: api-token
  projectkey: EXTERNAL
  # No TLS - standard HTTPS

mTLS for Both Servers

Both Jira instances behind separate API Gateways:

YAML

serverfrom:
  host: api-gateway-dc1.company.com
  tls:
    cacert: /secrets/dc1/cacert.pem
    clientcert: /secrets/dc1/client.crt.pem
    clientkey: /secrets/dc1/client.key.pem
  # ... other config

serverto:
  host: api-gateway-dc2.company.com
  tls:
    cacert: /secrets/dc2/cacert.pem
    clientcert: /secrets/dc2/client.crt.pem
    clientkey: /secrets/dc2/client.key.pem
  # ... other config

Troubleshooting

"file not found"

CODE

Failed to load CA certificate file: /secrets/cacert.pem - file not found

Fix: Verify the file exists and path is correct:

BASH

ls -la /secrets/cacert.pem

"invalid PEM format"

CODE

Failed to parse CA certificate file - invalid PEM format

Fix: File must be PEM-encoded (text with -----BEGIN CERTIFICATE-----).

Convert from PKCS#12 if needed:

BASH

openssl pkcs12 -in cert.p12 -clcerts -nokeys -out client.crt.pem
openssl pkcs12 -in cert.p12 -nocerts -out client.key.pem

"clientcert configured but clientkey missing"

Fix: Both clientcert and clientkey must be configured together:

YAML

tls:
  clientcert: /secrets/client.crt.pem
  clientkey: /secrets/client.key.pem  # Don't forget this!

"certificate is not trusted"

CODE

tls: failed to verify certificate: x509: certificate is not trusted

Fix: The API Gateway's certificate is signed by an internal CA. You must provide the cacert:

YAML

tls:
  cacert: /secrets/cacert.pem  # Required for internal CAs
  clientcert: /secrets/client.crt.pem
  clientkey: /secrets/client.key.pem

"certificate has expired"

Important: Expiration is checked during connection, not at startup. Jira Sync will start successfully but fail when connecting.

Fix: Check expiration and request renewed certificates:

BASH

openssl x509 -in client.crt.pem -noout -dates

"bad certificate" (server rejected)

The server rejected your client certificate.

Fix: Verify certificate and key match:

BASH

openssl x509 -noout -modulus -in client.crt.pem | openssl md5
openssl rsa -noout -modulus -in client.key.pem | openssl md5
# Both outputs should be identical

Test Connection Manually

Before configuring Jira Sync, test mTLS with curl:

BASH

curl -v \
  --cacert /secrets/cacert.pem \
  --cert /secrets/client.crt.pem \
  --key /secrets/client.key.pem \
  https://api-gateway.example.com/rest/api/2/serverInfo

Key Limitations

Limitation	Impact	Workaround
No hot-reload	Restart required after certificate update	Restart the Jira Sync process or pod
PEM only	PKCS#12/DER not supported	Convert with `openssl` commands
No expiration warnings	App starts with expired certs	Verify before deployment

File Permissions (Security)

BASH

chmod 0644 cacert.pem      # CA cert - can be readable
chmod 0644 client.crt.pem  # Client cert - can be readable  
chmod 0600 client.key.pem  # Private key - RESTRICT ACCESS

HTTP Client Timeout Configuration

Configure how long Jira Sync waits for responses from the Jira server on standard API calls (search, metadata, issue operations).

When Do You Need This?

Increase the timeout if you encounter errors like:

CODE

net/http: request canceled (Client.Timeout exceeded while awaiting headers)

Common scenarios:

Jira DC instances with large datasets or slow response times
Search queries that return many issues with expanded fields (e.g., changelog)
High-latency network connections between Jira Sync and Jira

Configuration

Add httpTimeoutSeconds under serverfrom and/or serverto in your .jira-push.yaml:

YAML

serverfrom:
  httpTimeoutSeconds: 30
  # ... other config

serverto:
  httpTimeoutSeconds: 60
  # ... other config

This is a per-server setting, allowing different timeouts for source and target Jira instances.

Default Behavior

Scenario	Timeout
`httpTimeoutSeconds` not set	30 seconds
`httpTimeoutSeconds: 0`	30 seconds (treated as not set)
`httpTimeoutSeconds: 60`	60 seconds

If not configured, the default of 30 seconds is used. This is the industry standard for production Go applications interacting with backend services.

Retry Behavior

The tool retries failed requests up to 10 times with exponential backoff. Timeout errors are retried automatically. If all retries are exhausted, the sync stops. Increasing the timeout reduces unnecessary retries caused by slow but valid responses.