Documentation

Set up aKanban against your GitLab Community Edition instance, learn the concepts, and deploy.

Home Documentation

Guides

Concepts

How tenants, boards, tasks, status and priority map onto GitLab.

  • Groups, projects, issues
  • Scoped labels
  • Phases
Read guide

Deployment

Build the Flutter app for web, mobile and desktop.

  • Web build
  • GitLab Pages pipeline
  • Mobile and desktop builds
Read guide

Known limitations

What GitLab CE does not provide and how aKanban works around it.

  • Swimlanes
  • Live updates
  • Offline cache
Read guide

Troubleshooting

Sign-in failures, empty boards and browser CORS errors.

  • Token problems
  • Missing labels
  • CORS on web
Read guide

Getting started

Requirements

  • A GitLab Community Edition instance you can reach from the device running aKanban.
  • A top-level group for your team. aKanban treats each top-level group as a tenant.
  • A Personal or Group Access Token with the api scope. No OAuth application needs to be registered.

First sign-in

  1. Open the app and enter your GitLab instance URL, for example https://gitlab.example.com.
  2. Paste your access token. It is stored on the device only.
  3. Pick the tenant (group) you want to work in. Each project in the group appears as a board.

Run the web build locally against your instance

cd apps/kanban_app
flutter run -d chrome --dart-define=GITLAB_INSTANCE_URL=https://gitlab.example.com

Concepts

  • Tenant = a GitLab top-level group.
  • Board = a GitLab project inside that group.
  • Task = a GitLab issue.
  • Status and priority = scoped labels named status::* and priority::*. Moving a card changes the status label.
  • Effort = shown as a badge on each card from the issue's effort label.
  • Phases = Business Analysis, Development, QA and Deployment groupings derived from status labels.

Because the board is a view over GitLab data, anything you change in GitLab's own issue UI shows up on the board at the next refresh.

Deployment

Web

Build with flutter build web and serve the output from any static host. The monorepo's GitLab CI pipeline publishes the web build and this marketing site to GitLab Pages.

Mobile and desktop

Standard Flutter builds for Android, iOS, macOS, Windows and Linux are supported from the same codebase. Store submission is a manual step.

Known limitations

  • Swimlanes: GitLab CE has no native epic-based swimlanes. Phase grouping is derived from status labels instead.
  • No push updates: GitLab CE has no websocket API for issues, so boards poll every 15 to 20 seconds.
  • Offline cache: an SQLite cache package exists but is not yet wired into the app. Boards need a network connection today.
  • Token-based auth: each user creates and pastes an access token rather than using an SSO-style redirect.

Troubleshooting

  • Sign-in fails: confirm the token has the api scope and has not expired, and that the instance URL has no trailing path.
  • Board is empty: the project has no issues with status::* labels yet. Create the labels in GitLab or add them from the app.
  • CORS errors in the browser: the web build calls the GitLab API directly. Serve the app from the same origin as GitLab, or allow the app's origin in your GitLab reverse-proxy configuration.

Need more help?

Tell us what you were trying to do and which platform you were on.