These docs are new.

Expect rough edges. If something is missing or hard to follow, tell us on Discord or by mail at hallo@knecht.works.

Integrations

Jira

Everything you need to know about the Jira integration. What it can do and how to set it up.

The Jira integration connects a Jira Cloud site to your instance. Tickets start workflows, the agent reads and answers on them, moves them through the board, and Knecht reports the finished pull request back on the ticket.

Setup

You need a Jira Cloud site and an account Knecht acts as. A dedicated account named "Knecht" is worth the extra seat: comments show up under its name, "assign it to Knecht" becomes a normal assignment in Jira, and the account's permissions limit what Knecht can see. Registering the webhook in step three needs Jira administrator rights, once.

Create an API Token

Sign in to Atlassian as the account Knecht should use and open API tokens. "Create API token", give it a name such as "Knecht", and copy the token. It starts with ATATT and is shown only once.

Connect the Account

In your instance, open Settings, Integrations. The Jira panel has three fields:

Site URL. The Atlassian site, for example https://acme.atlassian.net. It has to start with https://.
Email. The email of the account from step one.
API token. The token from step one.

"Connect" checks the credentials against Jira before anything is stored and shows "Connected as" with the account's name on success. The token is stored encrypted and not shown again. "Reconnect" replaces the token later, "Disconnect" removes the connection.

The Jira panel under Settings, Integrations, connected to an account, with the site URL, email, and API token fields, and the webhook URL and secret below

Register the Webhook in Jira

Jira does not call Knecht until you tell it to. After connecting, the panel shows "Waiting for Jira" with the webhook URL and a secret Knecht generated for you, both with copy buttons. "Set up in Jira" opens the webhook page of your site. By hand it is the gear icon, System, and "WebHooks" under Advanced in the sidebar.

The button that adds a webhook sits at the far right of the WebHooks page and is often outside the visible area. If you only see the search field and the list, scroll the page horizontally all the way to the right.

Fill in the form:

Name. Anything, for example "Knecht".
Status. Enabled.
URL. The webhook URL from the panel, it ends in /api/jira/webhook.
Secret. Paste the secret from the panel. Do not use "Generate secret", Knecht has to know the value, and Jira does not show it again after saving.
Issue related events. In the column Issue tick "created", "updated", and "deleted". In the column Comment tick "created". Everything else stays empty.
Exclude body. Leave it unchecked. Knecht needs the ticket data in the delivery.

The events section of the Jira webhook form, with created, updated, and deleted ticked under Issue and created ticked under Comment

The JQL field above the checkboxes is optional. Left empty, Jira warns that the query matches all issues in all projects. That works, Knecht drops events of projects that are not linked. A query such as project in (KAN, WEB) limits the deliveries to the projects you link in the next step. Atlassian describes the form under Manage webhooks.

Save the webhook at the bottom of the form. The summary should list the issue events created, updated, and deleted, the comment event created, and "Exclude body: No".

The saved webhook in Jira, enabled, with the Knecht URL, the secret set, the issue and comment events, and exclude body set to no

Link a Project to Its Jira Project

Open the settings of a project in Knecht. The Jira panel has one field, "Jira project", listing the projects the account can see. Pick the one whose tickets belong to this repository. One Jira project links to one repository and the other way round. Only linked projects can have Jira triggers.

The Jira panel in the project settings, with the Jira project field set to a project

Check That Events Arrive

Edit any ticket in the linked Jira project. The status line in the Jira panel under Settings, Integrations switches to "Receiving events" with the last event and ticket key. If it does not:

Status line says	What to do
Wrong secret	Paste the secret from the panel into the webhook again.
Without a body	Uncheck "Exclude body" in the webhook.
No project is linked	Link the Jira project in the project settings, see step four.
Still "Waiting for Jira"	Check that the webhook URL is reachable from the internet and that the events are ticked.

Capabilities

Triggers

A Jira trigger watches the Jira projects linked to the selected projects and starts one run for the project whose Jira project the ticket belongs to. The project field only lists projects that are linked. In the form, "Fires when any of these happens" lists the events and "But only if" the conditions. Any ticked event fires the trigger, and one group of conditions has to hold. How the two sections work in general is on Triggers. What all issue trackers share, such as issues that are created with the label already set, is on Triggers.

The trigger dialog with Jira selected as source, two linked projects as chips, the events Assigned to Knecht and Label added with the label knecht ticked, and the conditions Issue type is Bug and Status is not Any Done

Events

Event	Fires when	Notes
Created	A new ticket appears in the project.
Assigned to Knecht	The ticket is assigned to the account behind the connection.	Ticked by default. Makes "give it to Knecht" a normal assignment in Jira. Knecht taking the ticket itself does not fire, see Triggers.
Label added	One of the picked labels is added to a ticket.	The labels are picked from the labels of the Jira site.
Status reached	A ticket moves into one of the picked statuses or status categories.	The default is "Any Done". A ticket created in a status does not fire.

Status Reached

The status list has two groups.

Category. "Any To Do", "Any In Progress", and "Any Done" stand for Jira's three status categories, whatever the columns of a board are called.
Exact status. The statuses on the boards of the selected projects.

Triggers explains when a category and when an exact status fires, Matching what happens with several projects. If the form warns about a missing status, pick a category, a status all projects share, or create a second trigger.

The trigger dialog with two projects selected, Status reached set to In Planning, and a warning that this status does not exist in the Jira project KAN

Conditions

Field	Compares against
Status	The status the ticket is in, as a category such as "Any Done" or an exact status.
Assignee	"Knecht", the account behind the connection.
Issue type	The type of the ticket, for example Bug or Task. The types are read from the linked Jira projects.
Label	The labels on the ticket, read from the Jira site.

Each condition takes "is" or "is not". Every value is picked from a list and compared exactly, upper and lower case included. The rules are the same for every source, see Matching.

Inputs

The ticket fills the run inputs: identifier is the key such as PROJ-123, title the summary, body the description converted to Markdown, url the ticket link, status the status name, labels the labels, assignee and author the display names of the assignee and reporter. event is issue. Pausing, versioning, and shared behavior are on Triggers.

Sessions on Tickets

A run started by a ticket joins the session of that ticket, like a run on a GitHub issue. The session keeps the checkout, the environment, and the agent conversation, so a second trigger on the same ticket or a mention continues the work. The session closes when the ticket reaches a status in the Done category or is deleted, its environment stops once no run needs it any more, and it opens again when the ticket is moved back.

The Agent on Tickets

When the run's session belongs to a ticket, the agent gets four commands inside the environment. The prompt of an AI step only has to name what to do with them.

Read the ticket. Type, status, reporter, assignee, labels, the description, and the last ten comments, live from Jira.
Reply. Posts a comment on the ticket. The agent writes Markdown, Knecht converts it to Jira's format and appends the preview link and, when one exists, the pull request link. An @Name of the reporter, the assignee, or a commenter becomes a real mention that notifies that person.
Set labels. Adds or removes labels of the Jira site. Knecht never creates labels. If a name does not exist, the agent gets the list of existing labels instead.
Move the ticket. Transitions the ticket to a status by name, for example "In Review". If no transition from the current status leads there, the agent gets the list of reachable statuses instead.

Opening a pull request works through the git steps or the agent's own command, see GitHub.

Mentions

Write a comment on a ticket of a linked Jira project, mention the Knecht account the way you mention a colleague, and add the instruction:

@Knecht fix the broken footer link

@knecht typed as plain text works as well. Knecht runs the comment as a follow-up and posts the answer as a comment.

Whoever can comment on the ticket can mention Knecht, the Jira site is the gate.

The one-time setup, what happens step by step, and what to check when Knecht stays silent is on Mentions.

Examples

The workflows below can be built in the editor or imported from YAML under Workflows, "Import". Triggers are added in the editor after the import. All of them assume the project is linked to its Jira project.

Software Factory

Three workflows that hand a ticket from one to the next. The triage checks every new ticket, sets the label bug or enhancement, and moves it to "To Do". That move fires the trigger of the workflow whose label condition matches. A bug comes back with a pull request and a ticket in review, an enhancement with a plan that a mention in the comments turns into a pull request.

All of it runs in the session of the ticket. The triage boots the site once and every later run finds it running, so only the triage has a boot step. The prompts do not repeat summary or description, because the agent reads the ticket of its session itself.

Make sure the labels bug and enhancement exist in Jira first. Jira has no label settings, a label exists once any ticket carries it. Knecht only applies labels that exist, and a trigger only offers labels that exist.

Triage

Source	Fires When	But Only If
Jira	Created	No conditions

jira-issue-triage.yaml

version: 1
name: Jira Issue Triage
description: Check every new ticket and label it as bug or enhancement.
steps:
  - type: ddev-start
    id: boot_project
  - type: ai
    prompt: >-
      Read the ticket of this session. Try to reproduce it in the preview and in
      the code. Do not fix anything. Then apply exactly one label: "bug" if
      something is broken, "enhancement" if it was never built and then move it
      to "To Do".

      If the ticket lacks the details to decide, apply no label and ask the
      reporter in a comment for clarification. 
    id: triage
    label: Triage

Bug Fix

Source	Fires When	But Only If
Jira	Status reached: `To Do`	Label is `bug`

jira-bug-fix.yaml

version: 1
name: Jira Bug Fix
description: Fix a ticket labeled as bug and open a pull request.
steps:
  - type: ai
    prompt: >-
      The ticket of this session was confirmed as a bug. When you are beginning
      your work move the Ticket to "In Progress". Then fix it on a work branch,
      verify the fix on the preview, commit in logical batches, and open a pull
      request. 

      Comment a short summary of the change on the ticket and move it to "In
      Review".
    id: bug_fix
    label: Bug Fix

Add Enhancement

Source	Fires When	But Only If
Jira	Status reached: `To Do`	Label is `enhancement`

jira-add-enhancement.yaml

version: 1
name: Jira Add Enhancement
description: Plan a ticket labeled as enhancement and post the plan.
steps:
  - type: ai
    prompt: >-
      The ticket of this session is an enhancement. 

      Work out how it would be built in this project: the files to touch, the
      steps in order, and what is open. 

      Do not change any files or the status. Just post the plan as a comment,
      written for the person who reported the ticket.
    id: plan_enhancement
    label: Plan Enhancement

When the team agrees with the plan, a comment that mentions the Knecht account, such as "implement it and open a PR", is enough. Knecht continues in the same session and answers with the pull request.

A ticket that a person labels and moves to "To Do" without the triage having seen it starts these workflows without a booted site. Add a boot step to them if that happens in your team.

Assign to Knecht

No label and no triage: the team assigns a ticket to the Knecht account like to any colleague, and Knecht implements it. This workflow stands on its own, so it boots the site itself.

Source	Fires When	But Only If
Jira	Assigned to Knecht	Issue type is `Bug, Task`

jira-assigned-ticket.yaml

version: 1
name: Jira Assigned Ticket
description: Implement a ticket that was assigned to Knecht.
steps:
  - type: ddev-start
    id: boot_project
    label: Boot the Site
  - type: ai
    prompt: The ticket of this session was assigned to you. Read it with its
      comments, implement it on a work branch, verify it on the preview, commit,
      and open a pull request. Comment a short summary on the ticket and move it
      to "In Review".
    id: implement
    label: Implement

Estimate Tickets

A ticket that is moved to "In Planning" gets an estimate and lands in "To Do". The agent reads the ticket, looks up the code it touches, and comments how big the work is and why. An estimate needs the code, not the running site, so there is no boot step. Pick the exact status of your board in the trigger, the names here are examples.

Source	Fires When	But Only If
Jira	Status reached: In Planning	No conditions

jira-estimate-ticket.yaml

version: 1
name: Jira Estimate Ticket
description: Estimate a ticket in planning and move it to To Do.
steps:
  - type: ai
    prompt: 'Estimate the ticket of this session. Find the code it touches and judge
      the effort. Do not change any files. Comment the estimate on the ticket: a
      size (S, M, L, or XL), the hours you expect, what drives the effort, and
      what is unclear. Then move the ticket to "To Do". If it is too vague to
      estimate, comment your questions and leave it where it is.'
    id: estimate
    label: Estimate

Was this page helpful?

Provide Feedback to this Page

GitHub

Everything you need to know about the GitHub integration. What it can do and how to set it up.

Plane

Everything you need to know about the Plane integration. What it can do and how to set it up.