Documentation
Set up aKanban against your GitLab Community Edition instance, learn the concepts, and deploy.
Guides
Getting started
Point the app at your GitLab instance and sign in with an access token.
- Requirements
- Access token scope
- First sign-in
Concepts
How tenants, boards, tasks, status and priority map onto GitLab.
- Groups, projects, issues
- Scoped labels
- Phases
Deployment
Build the Flutter app for web, mobile and desktop.
- Web build
- GitLab Pages pipeline
- Mobile and desktop builds
Known limitations
What GitLab CE does not provide and how aKanban works around it.
- Swimlanes
- Live updates
- Offline cache
Troubleshooting
Sign-in failures, empty boards and browser CORS errors.
- Token problems
- Missing labels
- CORS on web
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
apiscope. No OAuth application needs to be registered.
First sign-in
- Open the app and enter your GitLab instance URL, for example
https://gitlab.example.com. - Paste your access token. It is stored on the device only.
- 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::*andpriority::*. 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
apiscope 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.