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_dispatchtrigger); 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.