Version 1.7.0 · Redmine 5.1 and 6 · GPLv2
This manual covers installation, configuration and daily use of the atori Kanban Board plugin.
The plugin adds a per-project Kanban view that maps directly onto the issue statuses defined in your Redmine instance. There is no parallel workflow, no separate status model and no shadow data: columns are issue statuses, cards are issues, and every change on the board is a regular Redmine operation with the corresponding journal entry.
Key concepts:
IssueStatus. Columns can be hidden or reordered inside the board settings; hidden columns still exist in Redmine but do not appear on the board.IssueQuery. Using a saved query gives you arbitrarily complex filtering without reimplementing a query language in the plugin.Version) counts as a sprint. The plugin doesn't invent its own sprint model; it reuses Redmine versions with their optional start and due dates.cd /path/to/redmine
unzip at_kanbanboard-1.7.0.zip -d plugins/
bundle exec rake redmine:plugins:migrate NAME=at_kanbanboard RAILS_ENV=production
# restart Redmine (passenger/puma/systemd unit)After restart, log in as an administrator and open Administration → Plugins. The Kanban Board plugin should appear with version 1.7.0 and no error banner.
A Redmine update is harmless for the plugin only if the order is right. Redmine loads every plugin at start-up; if a plugin does not match the new version, the whole instance fails to start until the plugin folder is removed. The data in the plugin tables is never affected.
Rule: every plugin version supports the current and the previous Redmine line (currently 5.1 and 6). Which plugin version is tested with which Redmine version is listed in the compatibility overview on redmine-plugins.atori.de.
Order of operations:
redmine:plugins:migrate, restart) and verify briefly on the old Redmine version. This bridging version runs on both Redmine versions.bundle exec rake redmine:plugins:migrate RAILS_ENV=production again and restart.Fallback when no bridging version exists (for example because the new Redmine requires a newer Ruby):
cd /path/to/redmine
mv plugins/at_kanbanboard ../at_kanbanboard.old # set the folder aside, do NOT migrate
# update Redmine
# unpack the new plugin version into plugins/at_kanbanboard
bundle exec rake redmine:plugins:migrate NAME=at_kanbanboard RAILS_ENV=production
# restart RedmineThe plugin tables stay untouched in the database; the new plugin version brings the schema up to date with its own migrations.
> Never run VERSION=0 as part of an update. Rolling the migrations back > to version 0 drops the plugin tables and with them all plugin data. It > belongs to a final uninstall only (see below).
cd /path/to/redmine
bundle exec rake redmine:plugins:migrate NAME=at_kanbanboard VERSION=0 RAILS_ENV=production
rm -rf plugins/at_kanbanboard
# restart RedmineThe rake task above reverses all plugin migrations, dropping the three tables the plugin owns (kanban_boards, kanban_board_columns, kanban_issue_positions). Existing Redmine data (issues, statuses, queries) is untouched.
Kanban is implemented as a project module and is off by default.
The plugin exposes three independent permissions under Administration → Roles and permissions → Kanban board:
| Permission | Scope | Typical role |
|---|---|---|
| View Kanban board | See the board, read-only | Reporter |
| Edit issues on Kanban board | Drag & drop, reorder within columns | Developer |
| Manage Kanban board | Change board settings (card source, swimlanes, WIP, column visibility) | Manager |
Separating view from edit lets you give read-only stakeholders access without risking accidental status changes.
The first time any user with the View Kanban board permission opens the Kanban tab, the board record is created automatically. One column per issue status is generated in the order Redmine defines; closed statuses are included but can be hidden later from the board settings.
Inside a project with the Kanban module enabled, a Kanban entry appears in the project menu (after Issues). Clicking it renders the board with the project's current issues arranged by status.
Users with Edit issues on Kanban board can drag a card from one column to another. The drop triggers a status update on the underlying issue, which goes through Redmine's normal workflow checks – meaning workflow restrictions defined per role and tracker are respected. A journal entry is written exactly as if the status had been changed through the standard issue form.
Reordering cards within a column is saved to the plugin's own position table (kanban_issue_positions) and does not touch issue data. This is how you indicate priority on the board without using the priority field.
Rejected move. If the workflow does not allow the status change, or the move would exceed the target column's WIP limit, the move is rejected: the card returns to its original column and a persistent message at the top of the board explains why. The page is not reloaded and the message stays until you dismiss it with its close (×) button.
By default the board shows all issues of the project. To narrow the set:
The board now shows only the issues that the saved query returns. Use this to scope the board to a sprint, a release, an area owner, or any other dimension you already express with queries.
Under board settings, choose a Swimlane field. Supported values:
An empty selection disables swimlanes and renders the default single-row layout. Swimlanes are purely a view concern; turning them on or off does not change issue data.
Collapsing rows. Every swimlane has a chevron on the left to collapse and expand it; collapsed, only the label and the number of cards remain visible. Collapse all / Expand all in the header row switches every row at once. The state is stored per project in the browser and restored on the next visit; it is a display setting of the individual user only. Cards cannot be dropped into a collapsed row – expand it first.
Per column, set a positive integer limit. When the card count exceeds the limit the column header marks the column. A drag-and-drop move that would push the target column over its limit is rejected: the card snaps back and a persistent message appears at the top of the board (see 5.2). A column that is already over its limit through filtering or direct status changes is only marked, not retroactively enforced.
To disable a WIP limit on a column, clear the field.
In board settings:
The sprint filter at the top of the board narrows the visible cards to a single Redmine target version. The dropdown lists every open version visible to the project (shared_versions.open), sorted by due date. "All (no filter)" removes the constraint.
Once a sprint is selected, a strip below the filter shows:
The strip is colour-coded: green when on track, amber when fewer than two days remain, red when overdue. The numbers are recomputed from the version's tickets on every page load — there is no separately maintained sprint state to drift.
Tickets without a sprint assignment (fixed_version_id IS NULL) form the backlog. There are two ways to view it:
Backlog page. Next to the board tab, the contextual area carries a Backlog link. The page lists every unassigned ticket with its subject, tracker, priority, assignee, estimated hours and a per-row sprint dropdown. Pick an open sprint from the dropdown → the issue is moved into that version and the row disappears. This is the bulk sprint-planning workflow without having to open each ticket. Closed versions are hidden from the dropdown — they're history, not planning options.
"Unassigned" swimlane. When the swimlane mode is Assignee, the board grows an extra row at the top labelled Unassigned (yellow background) showing every ticket without an assignee. Below it, every project member gets their own swimlane even when they currently hold no tickets — each person becomes a drop target. So you can drag from the Unassigned row straight onto a person's lane to assign without opening the ticket (see next section). This swimlane mirrors the assignee field only, not the sprint mapping — tickets show up here even when they already belong to a version.
When the swimlane mode is Assignee, dragging a card between swimlanes updates not just the column (status) but also the assignee field of the destination row — in both directions:
Both flows run through Redmine's safe_attributes and new_statuses_allowed_to checks, so the same workflow rules apply as anywhere else in Redmine: a status or assignment change forbidden for the user's role snaps the card back and is logged on the server.
If you want to assign a ticket and move it into a sprint at the same time, the backlog page (5.8) remains the direct route — board drag-and-drop only ever changes assignee and status, never the sprint mapping.
Every card move is a status change on the issue, so the full audit trail lives in the issue's journal – no separate log needs to be consulted or exported. Swimlane group changes follow the same path (the underlying field is updated). Sprint assignments made from the backlog page also land as journal entries on the ticket.
Drag & drop does nothing / reverts. Verify that the logged-in user has the Edit issues on Kanban board permission and that Redmine's workflow allows the transition from the source status to the target status for that user's role. Rejected moves snap the card back to its original column; the exact reason (a forbidden transition or a reached WIP limit) is shown in the message at the top of the board. An immediate revert with no message points to the missing permission.
A column is missing that I know has issues. Open board settings and check whether the column is marked as hidden or whether Hide closed statuses is active. Status columns are created for every existing IssueStatus, but hidden ones are invisible by design.
Cards don't appear although issues exist. If a saved query is configured as the card source, check the query's filters – cards that fall outside the query are not shown. Remove the query in board settings to return to the default (all project issues).
Performance on large projects. The board renders every card it finds. For projects with thousands of open issues, define a saved query that limits the set to what is actually in play (e.g. "this sprint" or "open + assigned to team"), and use that as the card source.
A new issue status I just created isn't on the board. The column list is reconciled on every board load. Reload the board page (or the project) and the new column will appear at the end of the sequence.
A version I expect doesn't show up in the sprint dropdown. The dropdown only lists open versions visible to the project (own version or shared via the version's sharing setting). A locked or closed version disappears from the list. Check the version's status under Roadmap → Version → Edit or create a new one.
The backlog page is empty although unassigned tickets exist. The list filters on fixed_version_id IS NULL over the same scope as the board (saved query and the "hide closed statuses" toggle). If the card source is a query that excludes all unassigned tickets, they won't appear in the backlog either. Clear the card source in the board settings and re-check.
Support is included for twelve months from the date of purchase and covers bug reports, configuration questions and compatibility issues.
E-mail: support@atori.de Initial response: within 48 hours on business days.
When reporting issues, please include:
log/production.log, if available