# Pipelines

**iKAgent → Pipelines** shows each task's way from the agent run to dev, live: one row per task, and under it one **lane per run**: a pull request, a branch, or one agent's run. Each lane goes Task → Agent run → PR → Checks → Merge → Build → Deploy dev → Smoke. Grey "Not yet" is the next step, blue runs, green passed, red failed, amber is held. A run that failed, was cancelled, is held or sent nothing for a day ends at its last stage: the steps it can no longer reach are not drawn. A run queued for more than a day shows **Stuck in queue**. Click a box to see its log.

**Plans:** Pipelines come with Pro (180 days of history) and Pro+ (365 days). On Starter the page
says so, and the pipeline endpoints answer 402: `ikanban pipeline run` and `ikanban pipeline event`
print a note and exit with the build's own result, so your CI never fails because of the plan.

Two runs never overwrite each other: a laptop build and a GitHub build, Claude and Gemini, or an agent's PR and a person's PR each keep their own lane and log. Each lane says what it is and who and where: "PR #159 · sam · github".

Search by task key or title; the list shows 50 tasks a page. **Running** counts running stages and runs queued in the last day; **Failed** counts tasks with a failed stage.

## Where the stages come from

| Stage | Comes from |
| --- | --- |
| Agent run, PR | iKanban itself: the agent's run and the pull request it opened |
| Checks, merge, build, deploy, smoke, … | your CI, which reports each stage to iKanban |

Any CI can report: GitHub Actions, GitLab CI, Bitbucket Pipelines, Jenkins or a script. iKanban needs no plug-in for your git host.

## Report a stage from your CI

Use an API key of a member of the task's team (Settings → API keys), kept as a CI secret.

```bash
curl -X POST https://api.i-kanban.com/api/teams/<team-id>/pipeline-events \
  -H "Authorization: Bearer $IKANBAN_API_KEY" -H "Content-Type: application/json" \
  -d '{"task":"IKA-123","stage":"build","status":"running","url":"https://ci.example.com/run/1"}'
```

- **task**: the task key (IKA-123) or its id. The task must be in that team.
- **stage**: 1–32 characters, a–z, 0–9, `-` and `_`. `agent`, `pr`, `checks`, `merge`, `build`, `deploy`, `smoke` and `release` are drawn in that order; other names follow. `checks-backend` sits with `checks`.
- **status**: `queued`, `running`, `passed`, `failed`, `skipped`, `held` or `cancelled`.
- **url** (optional): a link to the run, `https://` only, at most 500 characters.
- **detail** (optional): one line for people, at most 300 characters.
- **commit_sha** (optional): 7–40 hex characters.
- **run** (optional): which run of the task: `pr-159` for a pull request, else the branch name. At most 64 characters: letters, digits and `. _ - / # : @`. Without it, the stage joins the task's "Earlier reports" lane.
- **source** and **actor** (optional): where it ran (`github`, `gitlab`, `laptop`, `ci`) and who (an agent's name or a person). Same characters, 32 and 64 at most. These are labels: the lane also shows **reported by** the account whose key sent the stage, whenever that differs.
- **at** (optional): when it happened, for a late report or a backfill. Past only (5 minutes of clock skew allowed), at most 30 days ago. None means now.

A pull request opened or merged on GitHub fills the **PR** and **Merge** stages of its task by itself, in the PR's own lane (`pr-<number>`), through iKanban's GitHub App, when the PR title or branch names the task (IKA-123). When an agent's PR is green but its automation rule has **Merge the agent's pull request when every check passes** turned off, **Merge** turns amber: *Held · merge is off*. A person merges it, or turns that setting on in the rule. **GitLab:** merge requests are not read yet; report them from your CI with `stage` `pr` or `merge` and `run` `pr-<iid>`.

The newest event of a stage is its state; earlier ones count as tries.

## Stream a stage's log

Send the step's output in chunks while it runs; the open log follows them live, with colours:

```bash
curl -X POST https://api.i-kanban.com/api/teams/<team-id>/pipeline-logs \
  -H "Authorization: Bearer $IKANBAN_API_KEY" -H "Content-Type: application/json" \
  -d '{"task":"IKA-123","stage":"build","text":"Compiling...\n"}'
```

The `ikanban` CLI does this for you: `ikanban pipeline run --task IKA-123@pr-159 --stage build --source gitlab -- <command>` runs the command, prints its output as usual, streams it to that run's lane, reports running → passed or failed, and keeps the command's exit code. Send the same `run` with log chunks (`"run":"pr-159"`) so they open in the right lane.

## GitHub Actions: the job graph

A stage whose link is a GitHub Actions run (`https://github.com/<owner>/<repo>/actions/runs/<id>`) gets **Show jobs**. It opens the run's jobs as a graph under the row: one box per job, in columns by `needs`, matrix jobs folded into one box you can open. Hover or focus a job to light up what it waits for and what waits for it. Click a job to see its steps and its log. **Open run** shows the same graph on its own page.

- iKanban reads the run, its jobs and steps from GitHub, and the `needs` from the workflow file at the run's commit. A job it cannot match to the file is drawn without lines, with a note.
- The status changes live while the run goes: iKanban's GitHub App receives each job's start and end, for teams whose project or wiki links the repository. Otherwise the page asks GitHub every 15 seconds.
- The repository must be linked to the team (a project's **Repositories**, or **Agent settings → Git connections**), and you must be a member of the team. iKanban calls GitHub with your own GitHub connection.
- **Your GitHub App installation must accept the Actions permission.** When iKanban's app asks for **Actions: read**, accept it in GitHub (org **Settings → GitHub Apps → iKanban → Review request**). Without it there are no live job updates.

## Limits and safety

| Gate | Value | Where to change it |
| --- | --- | --- |
| Who may report | a member of the task's team; read-only and Security-only keys are refused | the key's scopes, Settings → API keys |
| One log chunk | at most 16 KB | send more chunks |
| Log kept | the newest ~2 MB per run and stage, for 7 days | — |
| History kept (stages) | your plan's limit: Starter and Free 3 months, Pro 6 months, Pro+ and Enterprise 1 year; deleted once a day | an owner or admin can choose less in a browser: **Agent settings → Pipelines** (an API key cannot change it) |
| List | 50 tasks a page, newest first; search by key or title | — |
| Job graph: workflow file | at most 256 KB and 256 jobs; above that the graph is refused with a message | split the workflow |
| Job graph: job log | the last 1 MB of the job's log | open the job on GitHub for the rest |

- **Secrets**: the CLI replaces the values of environment variables named like a secret (`TOKEN`, `SECRET`, `PASSWORD`, `*_KEY` …) with `***` before a line leaves your machine; add others with `--mask NAME`. The server also replaces known key shapes. A plain `curl` sends what you give it: mask it first.
- A log is shown as terminal text, never as a web page. Links open only if they are `https://`.
- Reporting never deletes anything. The MCP tool `get_pipeline` reads pipelines; it cannot write.
- Agents read a task's pipeline with the MCP tool `get_pipeline` (team, optional task key), and a GitHub run's job graph with `get_github_run_graph` (team, run URL). Both only read.
- A job log passes the same secret masking as a reported log before it is shown.