# Setting up Jira

Source: https://codeherder.com/docs/jira/

Connect a Jira Cloud site, register the webhook, add intake rules, and map stages. Read the activity list and fix a connection that turns off.

CodeHerder connects to Jira Cloud with the token of a service account. This page takes you from nothing to a Jira issue that creates a task. It then covers comments, stage moves, troubleshooting and disconnect.

## What Jira sync does

- **Intake.** A Jira issue that enters a status you choose creates one linked task. Each issue creates a task once, ever.
- **Comments.** Jira comments reach the task. Task comments reach Jira. No comment returns to the side it came from.
- **Stage moves.** When the task changes stage, CodeHerder moves the Jira issue to the status you map.
- **Links.** CodeHerder adds a link on the Jira issue that points to the task. It adds a link to the merge request too.

CodeHerder owns the task. A manual status move in Jira never changes the task. Jira Cloud is the only supported deployment. CodeHerder refuses a Jira Data Center site.

## Who can do what

Owners and admins connect Jira, add rules, map stages and change settings. Other members can read them. An agent cannot change them. You also need a Jira site admin to register the webhook.

## Create the service account

1. In Jira, create a dedicated account for CodeHerder. Use an Atlassian service account if your plan has one. Otherwise create a normal user.
2. Name the account **CodeHerder**. Every comment CodeHerder posts shows this name.
3. Give the account these permissions in each project you want to sync:
  - Browse projects
  - Add comments
  - Edit own comments
  - Delete own comments
  - Transition issues
  - Link issues
4. Do not give it Create issues or Jira administration. CodeHerder does not need them.

## Create the token

1. Sign in to Atlassian as the service account.
2. Create an API token.
3. A service account can only create scoped tokens. Give the token these scopes: `read:jira-work`, `write:jira-work` and `read:jira-user`.
4. A classic token from a normal user also works.
5. Copy the token. Atlassian shows it once.

## Connect Jira

1. Open **Admin → Integrations**, then open **Jira**.
2. Click **Connect**.
3. Type the **Base URL** in full, with `https://`. Example: `https://yourorg.atlassian.net`.
4. Type the service account **Email** and the **API token**.
5. Click **Connect Jira**.

CodeHerder asks Jira to confirm the email and token. If Jira refuses them, nothing is saved and the form shows the reason. The server stores the token encrypted. An agent never sees it.

Connect once on a group. Every workspace below it uses that connection. A workspace can have its own connection instead. The nearest one wins.

## Register the webhook

The webhook makes Jira events arrive in seconds. You need a Jira site admin for this step.

1. On the Jira page in CodeHerder, find **Webhook URL**. Copy it.
2. Click **Rotate webhook secret** on the group or workspace that owns the connection. CodeHerder never shows the first secret. The rotate step creates one you can read.
3. Copy the secret. CodeHerder shows it once. `ch jira rotate-webhook-secret` does the same.
4. In Jira, open **Settings → System → WebHooks**. Click **Create a WebHook**.
5. Paste the URL and the secret.
6. Select these events: **Issue created**, **Issue updated**, **Issue deleted**, **Comment created**, **Comment updated** and **Comment deleted**.
7. Add a JQL filter if you want to limit the webhook to your projects. Save it.

A workspace that uses a group connection cannot rotate the secret. Rotate it on the group that owns the connection.

When you rotate again, the old secret stops working at once. Paste the new secret into Jira. Jira deliveries fail the signature check until you do.

CodeHerder shows **Last event received** on the page. It reads “No Jira event has arrived yet” until the first event comes in.

## Add an intake rule

A rule says which Jira issues become tasks.

1. On the Jira page, open **Intake rules**. Click **New rule**.
2. Choose the **Project**.
3. Choose one or more **Trigger statuses**. A new task starts when an issue enters one of them. Example: Ready for Dev.
4. Optional: choose **Issue types**. Leave all unchecked to match any type.
5. Optional: type a **Label**. Only issues with this label match.
6. Choose the **Task type**. Leave it empty to take the type from the Jira issue type.
7. Choose the **Workflow** and the repository for the new task.
8. Optional: choose an **Acceptance field**. CodeHerder copies that Jira field into the task’s acceptance criteria.
9. Click **Create rule**.

The task title is the issue summary. The description starts with a link to the issue, then the issue text.

If another workspace in your account has a rule on the same project and status, the rule shows an overlap warning. The oldest matching rule makes the task.

After intake, Jira edits do not overwrite the task. A change to the summary or description adds a short note comment on the task. A manual move of the issue in Jira changes nothing in CodeHerder.

## Set comment sync

Open **Comment sync** on the Jira page.

- **Comments sent to Jira.** Choose one:
  - **Post no task comments to Jira**
  - **Post comments people write** (the default)
  - **Post comments people write and agent hand-offs**
  - **Post every comment**
- **Comments from Jira.** On by default. Turn it off to keep Jira comments in Jira.

A Jira comment with restricted visibility does not sync. A Jira comment cannot answer an agent question. CodeHerder cannot link a Jira account to a CodeHerder person. When an agent asks a question, CodeHerder posts “CodeHerder needs an answer” on the issue, with a link. Answer in CodeHerder.

## Map stages

Open **Stage mapping** on the Jira page. A mapping says which Jira status a stage moves an issue to. Each Jira project has its own mapping.

1. Choose the **Jira project**. Add an intake rule first if the list is empty.
2. For each stage, choose a **Jira status**.
3. Click **Save changes**.

A row for a stage name wins over the default for its class. These defaults apply when you map nothing:

- A stage that does work moves the issue to the first status in the Jira “In progress” category.
- A stage that finishes the task moves it to the first status in the “Done” category.
- A waiting stage (`todo`) does not move the issue.

If a transition needs a resolution, set `resolutionName` on the mapping row through the API. Use `PUT /v1/workspaces/{id}/jira-stage-mappings`. That call replaces the full set of rows, so send every row. The **Stage mapping** page keeps the value when you save.

## Read the activity list

**Recent sync actions** shows what CodeHerder and Jira sent each other, newest first. Each row has an **Issue**, an **Action**, a **State**, **Attempts**, a **Reason** and an **Updated** time.

- **pending.** CodeHerder has not sent it yet, or it will retry.
- **done.** It worked.
- **failed.** It failed for good. The **Reason** says why.
- **skipped.** CodeHerder chose not to send it. The **Reason** says why.

An admin clicks **Try again** on a failed action. Use the **State** filter to find failures. From the command line, run `ch jira activity`.

The task page shows a Jira row with the issue key and the last failure.

## Troubleshoot

- **Jira turned this connection off (401 or 403).** Jira refused the token. Create a new API token for the service account. Click **Edit connection**, paste the token, and save. Then click **Test connection**.
- **“Jira has no transition from X to Y.”** The Jira workflow does not allow that move. Add the transition in the Jira workflow, or map the stage to a status that can be reached.
- **A move fails because of required fields.** The Jira transition screen has a required field. CodeHerder cannot fill it. Remove the field from the transition screen. CodeHerder can set the resolution when the mapping row has a resolution name. See [Map stages](https://codeherder.com/docs/jira/#map-stages).
- **No Jira event has arrived yet.** The webhook is not set up. Check the URL, the secret and the six events. CodeHerder warns on the page when a rule is on and no event came in for 24 hours.
- **Signature failures after a rotate.** Paste the new secret into the Jira webhook.
- **Issues still arrive without the webhook.** A poll checks Jira every five minutes. It finds missed issues. It is slower than the webhook, with the same result.

## Disconnect

Click **Disconnect** in the page header.

- Pending actions are skipped with “Jira is disconnected”.
- Tasks stay as they are.
- Rules, mappings and comment settings stay.
- Links reattach when you reconnect to the same Jira site.

## Self-hosted servers

- **No server setup.** Jira needs no environment variable. The server encrypts the token with the key your install already uses, `CH_INTEGRATIONS_SECRET_KEY`.
- **Reachable webhook URL.** Jira Cloud calls the webhook from the internet. Your server needs a public HTTPS address for `/v1/jira/webhooks/{siteId}`.
- **Firewalled install.** If Jira Cloud cannot reach your server, skip the webhook. The poll finds issues and comments. It is slower, with the same result.
- **Outbound access.** The server needs port 443 to your Jira site and to `api.atlassian.com`.
- **Optional settings.** `CH_JIRA_POLL_INTERVAL` sets the poll period (default 5 minutes). `CH_JIRA_SYNC_RETENTION_DAYS` sets how long settled actions stay (default 90).

## Agent tools

An agent can read and write Jira issues when an admin turns on agent access for the Jira integration. The tools and their classes are listed on the Jira page in Admin → Integrations. A write tool follows the write policy: `ask` needs a person to approve each call. A write rule can allow or deny a tool per project or stage, or block one issue. See [Agent access](https://codeherder.com/docs/integrations/#agent-access) and [Write rules](https://codeherder.com/docs/integrations/#write-rules).

**Connect your own account.** When an admin allows personal accounts, a member can connect their own Jira account. A task that member filed then acts as them. See [Your account](https://codeherder.com/docs/integrations/#your-account).

To create a work item that your board accepts:

1. Call `jira_get_create_fields` with the project key and issue type. It lists each field with its id, type, required flag and allowed values.
2. Call `jira_create_issue`. Besides `projectKey`, `issueType` and `summary`, it takes `description`, `parent` (an epic or parent issue key), `priority` (a name or id), `assignee`, `labels` and `components`.
3. Put custom fields in the `fields` map, keyed by field id. Example: `{"customfield_10900": {"value": "Platform"}}`. CodeHerder checks each field against the create screen. It refuses an unknown field id, a value of the wrong type and a value outside the allowed values. The error names the field and lists what is allowed.

`assignee` is a Jira account id. The value `me` means the person whose personal account makes the call. It needs a personal account. The service account has no filer, so pass an account id there.

To link two issues, call `jira_get_link_types`, then `jira_link_issues` with the type name, `fromKey` and `toKey`. With type `Blocks`, `fromKey` blocks `toKey`.

To change fields of an existing issue, call `jira_get_edit_fields` with the key. It lists each editable field with its type, allowed operations and allowed values. Then call `jira_update_issue` with `key` and a `fields` map, for example `{"fixVersions":["1.4"],"assignee":{"accountId":"..."}}`. Only the named fields change; every other field keeps its value. `null`, or `[]` for an array, clears a field that is not required. Version and option fields take a name or an id. `assignee` also takes an account id string, or `me` for a personal account. If `assignee` is not on the edit screen, CodeHerder sets it through Jira’s assign call. That call needs the Assign Issues permission, not Edit Issues. CodeHerder checks every field against the edit screen before it writes. It refuses a field that is not editable, a wrong-typed value and a required field cleared, and it names the field. Rich-text fields, status, comments and links have other tools or are not supported. The call is a write: the write policy and write rules of the issue’s project decide whether it runs, asks or is refused. See [Write rules](https://codeherder.com/docs/integrations/#write-rules). If Jira refuses the call, the error shows Jira’s reason and the issue does not change. If the fields update but the assignee does not, the error says so.

An agent cannot fill the fields of a transition screen that is not a resolution.

## Commands

All commands accept `--workspace <ref>`.

- `ch jira status` shows the connection.
- `ch jira rules` lists the intake rules.
- `ch jira mappings` lists the stage mappings.
- `ch jira settings` shows the comment settings. `ch jira edit-settings` changes them.
- `ch jira activity` lists sync actions.
- `ch jira rotate-webhook-secret` makes a new webhook secret.
