# Automations

An automation is a rule: **when** something happens, **then** it does one thing, within limits you
set. Rules can update a task, notify people, or start an AI agent (Claude or Gemini) on the work.

**Plans:** Automations come with Pro and higher plans. On Starter, the team's **AI Agent works its
tasks** rule runs (a task given to the AI Agent starts an agent); any other rule is kept, shows
**Paused: Automations need Pro**, and runs again after an upgrade. Creating a rule on Starter
answers 402, and an incoming webhook for a paused rule answers 402.

Open **iKAgent → Automations**. The **Personal** tab lists your own rules; **Team** lists the rules
your team shares. Each row has an on/off switch.

## Personal or Team

| | Personal | Team |
|---|---|---|
| Acts as | you | "iKanban Automation", only inside the rule's scope |
| Reaches | only projects you can open | only the projects in its scope |
| Agent on GitHub | uses your GitHub connection | uses the iKanban GitHub App installed on the repository's organization |
| Agent on a laptop | your own iKanban app | any team member's runner with **Accept team work** on |

A rule can only name projects you can open, so making a rule never widens anyone's access.

## The AI Agent rule every team starts with

Each team has a member called **AI.Agent**. A task created with no assignee goes to it, and you can
hand any task to it by making it the assignee. Every team starts with one Team rule, **AI Agent
works its tasks**, that puts the AI Agent to work:

- **When:** *A task is given to the AI Agent*: a new task goes to it, or a task is reassigned to it.
  Tasks the AI Agent already holds do not start by themselves; reassign one to start it.
- **Then:** Claude on GitHub, through the iKanban GitHub App, with instructions to make the change,
  test it, and open a pull request that names the task.
- **Merge:** when every check on that pull request passes, iKanban merges it and moves the task to
  **Done**.
- **Limits:** at most 20 runs a day, 2 at once, 2 minutes between runs.

It is an ordinary rule: open it in **Automations → Team** to change the agent, the instructions or
the limits, to turn merging off, or to switch it off. A task you give to a person never starts it.

## When: triggers

| Kind | Fires when | It acts on |
|---|---|---|
| **Board event** | a task is created, changes status, assignee or priority, is marked done, or is given to the AI Agent | that task |
| **Schedule** | every day, every weekday, or one day a week, at a time in a time zone | a new task (agent), or the open tasks of a saved view (update, notify; up to 50) |
| **GitHub** | a pull request is opened or merged, or a PR comment mentions @claude, @copilot or @gemini | the task the PR names |
| **Incoming webhook** | another tool calls the rule's own address with its secret | a new task |
| **Security finding** | a scan adds a new finding at or above the rule's severity (code, AI endpoint or dependency) | the finding's fix task, filed in the rule's project (one per finding; an existing one is reused) |

A rule uses board/GitHub triggers **or** schedule/webhook triggers, not both: the first act on a
task, the second have no task to start from.

## Then: actions

- **Update the task**: set status, priority or assignee, or add a label.
- **Notify people**: the assignee, the task's creator, or the whole team, in their inbox.
- **Dispatch an agent**: Claude or Gemini, on GitHub or on a laptop, with your instructions
  (1 to 4000 characters). On a GitHub trigger the instructions also name the pull request.

## The rules that decide whether a run starts, waits, is skipped or merges

These are deliberate. Each one says what you will see, and where to look.

| Rule | What happens | Where you see it | Change it |
|---|---|---|---|
| **On/off switch** | Off: nothing runs. A run already waiting stays waiting until the rule is on again. Nothing is deleted. | the switch on the row | the switch |
| **At most N runs per hour or day** (default 20 per hour) | A run over it waits, and starts when the hour or day has room. | **Recent runs**: *Queued — over its limit* | Guardrails |
| **At most N agent runs at once** (default 2; never more than the run limit) | A run over it waits for an earlier agent run of this rule to end. | **Recent runs**: *Queued* | Guardrails |
| **Wait N minutes between agent runs** (counted from when a run ends; default 2; 0 to 120) | The next agent run starts only after this pause. | **Recent runs**: *Queued* | Guardrails |
| **When an agent run ends** | A laptop run ends when the runner finishes; if it opened a pull request, its task waits **In review** until that PR is merged. A GitHub run ends when it answers without a PR, fails, or **its pull request is merged**. | the task's agent card | — |
| **Auto-merge** (agent rules with **Merge the agent's pull request when every check passes** on, the default) | After the agent finished, iKanban merges its pull request once **every check passed**, then moves the task to **Done**. GitHub runs: the PR the agent's workflow opened. Laptop runs: a GitHub PR the run opened in the task's repository, after the run started, not from a fork. A PR with no checks, a failing check, a conflict or a required review is not merged; it is retried every 30 seconds. A run a person started is never merged for them. The merge uses the GitHub connection of the person the run belongs to (a Team rule: its creator); without one, the iKanban GitHub App merges only if it has **Contents: write**. GitLab and Bitbucket PRs wait for a person. | a task comment: *iKanban Automation merged PR #N* | the switch in the rule's **Then**; fix the checks or merge it yourself |
| **Waiting runs per rule: 100** | A run past 100 waiting is skipped (a webhook caller gets 429). | **Recent runs**: *Skipped* | raise the limits, or slow the sender |
| **An agent is already working on the task** | A new agent run on the same task is skipped. | **Recent runs**: *Skipped* | wait for the first run to end |
| **The task is Done or Cancelled** | No agent starts on finished work. | **Recent runs**: *Skipped* | reopen the task |
| **Copilot** | Not offered to automations: it needs Copilot seats. | the Agent list shows Claude and Gemini | — |
| **Personal rule, creator lost access** | The rule stops acting in that project. | **Recent runs**: *Skipped* | the creator regains access, or make it a Team rule |
| **Laptop run, no runner online** | The run waits until your iKanban app (Personal) or a team runner with *Accept team work* (Team) is online. | **Recent runs**: *queued: no runner available* | open the app |
| **Schedule saved after its time** | A time slot fires only if the rule was saved before it, and only up to 30 minutes late. | nothing for that day | save at least a minute before the time |
| **AI Agent rule, no repository** | The rule starts nothing when the task's project links no GitHub repository, or the iKanban GitHub App is not installed on its organization. | **Recent runs**: *Failed* with the reason | link the repository to the project; install the app (**Docs → GitHub runs**) |
| **GitHub trigger, no linked task** | Nothing runs when the PR names no task key (e.g. `IKA-123`) in its title or branch, or the task's project does not link that repository. | **nothing is logged** | put the key in the PR title or branch; link the repository to the project |
| **Security finding: severity and per-scan cap** | Only new findings at or above **Severity at least** count, and only the most severe **up to N per scan** (1 to 50, default 1) get a fix task; the rest wait on Security. A rescan files only new findings, so an open one never fires twice. A finding a rescan closes or re-opens fires no rule, and its fix task stays as it is. | **Security → Findings**; **Recent runs** | the rule's trigger |
| **Security finding: whose scans** | A Personal rule acts only on scans its creator uploaded; a Team rule on any member's. | **Recent runs** | Personal / Team |
| **Webhook** | No secret yet: make it after the first save. Wrong secret: 404. Rule off: 409. Body over 4 KB: refused. | the caller's response | **Make secret** / **Replace secret** in the rule |

For an agent's pull request to open at all, a repository admin ticks **Settings → Actions → General → Allow GitHub Actions to create and approve pull requests** (see **Docs → GitHub runs**).

For an agent's pull request to get checks at all:

- **Claude and Gemini on GitHub:** their workflow opens the PR with GitHub's own token, and GitHub starts no workflows from that. Set the repository variable **IKANBAN_CI_WORKFLOW** to your CI workflow's file name (it needs a `workflow_dispatch` trigger); the workflow then starts it on the agent's branch.
- **Claude and Gemini, changes under `.github/`:** if the agent's branch changes any file under `.github/`, the workflow starts no CI. That pull request waits for a person instead of being auto-merged.
- **Copilot:** GitHub holds CI on Copilot's pushes until a maintainer approves. A repository admin can turn this off: **Settings → Copilot → Cloud agent → Require approval for workflow runs → Off**. GitHub warns that unreviewed agent code then runs in CI with access to the repository's secrets.

The queue is checked every minute, so a waiting run starts within about a minute of its slot
freeing.

## Check a rule

- **Recent runs** in the rule lists each run: *Ran*, *Queued*, *Skipped* or *Failed*, with the task
  and the reason.
- A dispatched agent adds a **GitHub Issue Created** comment to the task, and its agent card shows
  the run until it ends.
- Notifications arrive in the **Inbox** of the people the rule names.

## Tips

- To have the AI Agent work a task, assign it to **AI.Agent** (or leave the assignee empty when you create it).
- Try a rule on one test task first, then widen its scope.
- For "one agent at a time, each starting from the last one's merged code": set **at once = 1** and
  keep the wait at 2 minutes or more.
- Switch a rule off before you change it, if it is busy.