CodeHerderSearch⌘KRequest access →

Setting up 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.
  • 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 and 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.

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. 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.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close