Issues from a forge

A forge webhook used to record links only. It never made an item, and it never moved a card (COLLIERY-I-0009). KAIROS-A-0028 changes the first half of that rule, for issues only: an opened GitHub or GitLab issue that the forge filter of the repository admits becomes one support task. Webhooks still never move cards.

This page tells why, and what Kairos does not do with the issue after that.

Why issues become tasks

A public repository gets issues from people who do not use Kairos. Those issues need triage, and the team triages its work in Kairos. Before KAIROS-A-0028, a person read the issues on the forge and made the tasks by hand, or the issues were not triaged at all.

So the issue comes in as a request to the owner team of the repository: a task in the entry column of its delivery board, in the Support lane. That is the place where a request from another team arrives. The board triages it in its usual way. A person decides, or an agent decides when the board lets agents decide (KAIROS-T-0428). Kairos adds no second triage flow for issues.

Who makes the task

The forge system actor of the organization, Forge, makes the task (KAIROS-T-0481). It is not the person who connected the repository: that person did not ask for the work, and the history of the task must not say that they did. The login of the author of the issue is on the task and on its link. Forge is not a login. It has no password and no API key, and the server refuses it a login of each kind.

Forge is a member of the organization, so it has the right of each member: it can send a request to any delivery board. It has no other right.

One task for one issue

Forges send an event again when they think that it did not arrive, and the import of the open issues (KAIROS-T-0483) reads issues that a webhook took already. So the key of the intake is the forge’s own id of the issue. The first event or import takes the issue and makes the task. Each later one finds the key and makes nothing.

Issues without a webhook

A webhook needs the forge to reach Kairos. A private network cannot receive one (KAIROS-T-0670). So a repository can take its open issues on an interval instead. The server lists the open issues, and compares them with the record of the issues that it took. The record is the same key as above: the id of the issue on the forge.

An issue with no record becomes a task. No time decides what is new. So a missed run leaves no gap, and an old issue that is new to Kairos still becomes a task. The cost is that each run lists every open issue. The interval is meant for a repository with few open issues. See Connect a git forge.

What is not synced

After intake, Kairos does not read the issue again:

A close, a reopen or an edit on the forge does not change the task. An issue closed on the forge stays open in Kairos until a person closes the task.
A comment or a label on the forge does not come to Kairos.

Kairos writes to the issue in one direction only, and only with a write token on the repository (KAIROS-T-0575). The end of the task closes the issue:

A done task writes a comment with the code of the task, and closes the issue.
A cancelled task writes the reason, and closes the issue as not planned.
A reopened task opens the issue again.

Kairos writes no label, and it does not change the title or the text of the issue. See Turn on forge write-back.

This is on purpose. Two-way sync of two trackers needs a rule for each conflict, and the forge and Kairos have different states and different people. The task in Kairos is a copy of the request at the time it arrived. The link on the task goes back to the issue for what came after.

The forge filter is the control for noise

A public repository can fill a board with noise. The include and exclude patterns of issue_title and issue_author on the repository decide which issues Kairos takes (KAIROS-T-0479). The usual first rule excludes bots, for example ^dependabot\[bot\]$. The same filter decides which branches and pull requests Kairos records.