Octbase User Guide

What is Octbase?

Octbase replaces Jira for task, sprint, and board work, includes its own wiki pages, and integrates with GitHub, GitLab, and Bitbucket (it does not host git) — one tool that does the core workflow really well. It is designed for a single team where every user is known and invited by an administrator.

Signing in

Octbase uses invitation-only registration — there is no public sign-up. An ADMIN or SUPER_ADMIN invites you by email and you set your own password when accepting the invitation link.

1. Open the app and you will see the login page.
2. Enter your email address and password, then click Sign in.
3. If your account has two-factor authentication enabled, a Two-factor verification step appears — enter the 6-digit code from your authenticator app (or one of your recovery codes) and click Verify.
4. After a successful login you land on the Dashboard.

Password requirements

Whenever you set a new password — accepting an invitation, using a reset link, or when an administrator creates your account — it must be at least 12 characters long, and trivially common passwords (e.g. password1234) are rejected. Existing passwords are not affected until you change them.

Dashboard

The Dashboard (My Work) is the first screen after login. It gives you a personal overview across all projects you are a member of.

Click any task or page title to open it directly. Use Ctrl+K to search across everything from any view.

Projects

A project is the top-level container for tasks, a board, releases, sprints, pages, and repository connections.

Creating a project

ADMIN and SUPER_ADMIN users can create projects. Click + New Project on the project list screen. Provide a name, an optional abbreviation, an optional description, and choose Public or Private visibility.

Editing and deleting

Every project card shows Edit and Delete buttons. Inside a project the same actions appear in the top bar. Deleting a project permanently removes all of its tasks, boards, pages, releases, and activity — a confirmation dialog warns you before proceeding.

Archiving

Archiving hides a project from the active list without deleting any data. Only a PROJECT_OWNER or PROJECT_ADMIN can archive a project. There is no button for it in the app yet — archiving is currently only available through the REST API (POST /api/v1/projects/{projectId}/archive).

Exporting a project

Any project member can export the whole project as a single ZIP archive. Click the settings gear icon in the project top bar and choose Export project (German UI: Projekt exportieren). The archive contains everything that makes up the project:

• All tasks with their comments (including reply threads), web links, and task relations
• All attachments — uploaded files are included with their original bytes, external links are preserved
• All wiki pages with their hierarchy and TASK-… cross-references
• A project.json manifest with the project metadata

The archive is re-importable: use it as a backup, or to move a project to another Octbase instance.

Importing a project

Members with a writer role (any project role except PROJECT_VIEWER) can import a previously exported archive. Open the settings gear menu and choose Import project (German UI: Projekt importieren), then select the ZIP file. The imported content is added to the current project — existing content is never modified or deleted.

• Everything is recreated with fresh IDs; task numbers are re-assigned using the target project's abbreviation, and comment threads, page hierarchy, task relations, and TASK-… references inside pages are re-linked automatically.
• People are matched by email address. If an assignee, reporter, or comment author doesn't exist on the target instance, the field is left empty (comments fall back to the importing user) and a warning is reported.
• Page slugs that already exist in the target project are de-conflicted with a numeric suffix.
• Imported files pass the same file-type and size checks as regular uploads; anything disallowed is skipped and reported.

Creating a new project from an export

Instead of importing into an existing project, you can create a brand-new project straight from an export archive: on the project list screen, click New project from export and select the ZIP file. The project's name, abbreviation, description, and visibility are taken from the archive, you become its PROJECT_OWNER, and all content is imported in one step. Like regular project creation, this requires the ADMIN or SUPER_ADMIN global role.

Kanban board

The board is the primary task view. Tasks are organised into columns (lanes) that map to a workflow status. Press B from inside any project to jump here.

A card's lane and its status are two views of the same thing and stay aligned both ways: dragging a card to another lane sets the task's status to that lane's status, and changing a task's status elsewhere (for example from the task panel) moves the card into the matching lane. A task not on the board, or one whose board has no lane for the new status, keeps its place.

Creating a board

A PROJECT_OWNER or PROJECT_ADMIN can create a board pre-filled with a default set of lanes. Choose a template:

• Kanban — To Do · In Progress · Done
• Scrum — To Do · In Progress · In Review · Done

The lane names are created in your current language (English or German), and you can rename them afterwards at any time. The first time a project's board is opened, Octbase auto-creates a default Scrum board for you.

Configuring the board

Click the ⚙ Board settings button above the board to customise it. You can rename the board, add lanes, rename existing lanes, reorder them, and remove lanes you no longer need (between 1 and 10 lanes). A custom lane name becomes a usable task status, so the board's columns and the available task statuses always stay in sync.

Linked columns

You can mirror a single column from another board so its content is visible alongside your own work — including boards in other projects you have read access to, which is handy when each project has just one board. Click the linked column button above the board and pick a source column; the picker groups columns by project · board. The linked column appears on the right of your board, labelled with its source (and source project when it differs from yours), and is read-only — its tasks cannot be moved or edited from here, since the source board stays authoritative. Use the × on a linked column to remove it (this never affects the source).

Backlog column

Toggle the backlog button above the board to show or hide the backlog as a separate column on the left of your board. This keeps unstarted work in view while you plan — drag an item from the backlog column straight into a lane to put it on the board. The toggle is remembered per board on your device, so the backlog stays shown or hidden the way you left it.

Creating a task inline

Press N while the board is visible. An inline creation row appears in the first column — type a title and press Enter. Press Esc to cancel without creating.

Moving tasks

Drag a card to a different column to update its status. Or open the task panel and change the Status field.

Filtering

Use the filter bar above the board to narrow by status, priority, assignee, or label. Active filters are encoded in the URL — a filtered board view is bookmarkable and shareable.

The search box on the board narrows the lanes as you type. It matches the card title and — see Finding a task by its ID — the task ID printed on the card.

Task cards

Each card shows its type badge and sequence number along the top, with the assignee avatar (and the pin button) at the top right, then the title. Below it sits a row of tags, each shown only when it applies: the priority dot, the effort estimate, the due date (red when past due), the release, and — if the task is assigned to a sprint — a green sprint tag.

A card always shows the current state of its task: anything you change in the task panel — assignee, priority, type, due date, release, sprint, or the title — appears on the card straight away, with no need to reload the page.

Pinning a card

Hover a card and click the pin button to pin it. Pinned cards float to the top of their lane (and show a coloured left border) so important work stays in view. Click the pin again to unpin. Pinning needs write access and works on a task in any status — including DONE or ARCHIVED.

Backlog

The backlog lists all tasks that are not yet placed on the board (unstarted work), grouped by release. Use it for grooming and sprint planning. Press L to navigate here from inside a project. You can also show the same backlog as a column directly on the board — see Backlog column.

Sorting. Click any column header to sort the whole backlog by that column — the release grouping collapses into one flat, sorted list. Click the same header again to reverse the direction (an ▲/▼ arrow marks the active column), and a third click clears the sort and returns to the release grouping. The Backlog and the Task list view remember their sort independently.

Searching. The search box above the list narrows it as you type, matching both the task title and its description.

Finding a task by its ID

Every task carries an ID made of the project abbreviation and a number — OCT-202 — shown on its board card, its backlog row, and at the top of its task panel. Typing that ID into the search box on the Backlog, the Task list, or the Board jumps straight to that one task, so an ID quoted in a chat message or a commit can be pasted back in to find the work it refers to.

• Both spellings work: the full ID (OCT-202, in any capitalisation, with an optional leading #) and the bare number (202).
• The ID has to be complete — OCT-20 finds task 20, not 202.
• An ID from a different project is not matched: searching ABC-202 inside project OCT returns nothing rather than the wrong task.
• The text search keeps running alongside it, so a query like 202 also lists tasks that mention 202 in their title or description.

Each view searches what it shows: the Backlog searches unstarted work, the Board searches the cards on its lanes, the Task list searches both. To search across projects — or for pages and projects too — use the global search (Ctrl+K), described under Search.

Task panel

Click any task card or list row to open the slide-in task panel. The URL updates to include ?task=TASK_ID — reloading the page restores the panel exactly.

Editing fields

Click any field in the Details tab to edit it inline. Changes save immediately. The title in the panel header is editable too: click it (or the pencil button next to it, or press E) to start editing, then Enter saves and Esc reverts. Press A to assign the task to yourself.

The Board Column field in the Details tab lets you move a task to any column without using drag-and-drop — useful when the board is not currently in view.

The Assignee and Reviewer lists offer the project's members plus your instance's global admins, who appear marked (admin) — they administer the instance without being members of any particular project. Someone who has since left the project, or whose account was disabled, stays visible on the tasks they still hold, marked (no longer a member).

Picking an admin who is not a member offers to add them to the project as a Viewer: administering the instance does not by itself grant access to a project, so without a membership they could not open the task. If you are not allowed to add members, you are told so and can ask someone who is. Super Admins reach every project already and are never asked about.

Created by records who created the task. It is set once, at creation, and cannot be edited afterwards.

Rich-text description

The task description is a rich-text editor with a formatting toolbar: Bold, Italic, Bullet list, Numbered list, Heading, Code block, Insert link, and Attach file. You can also use Ctrl/Cmd+B and Ctrl/Cmd+I for bold and italic. Edits are saved with the Save button below the editor; the status line shows whether you have unsaved changes.

Quick actions

At the bottom of the Details tab sit the task-level actions:

• Move to Backlog — removes the task from the board and places it in the backlog (only shown when the task is currently on the board).
• Archive / Reopen — archives an open task or reopens an archived one.
• Delete — permanently deletes the task after a confirmation dialog (unlike archiving, this cannot be undone).

Task statuses

PLANNED → IN_PROGRESS → IN_REVIEW → DONE → ARCHIVED. Tasks in DONE or ARCHIVED cannot be modified, with one exception: they can still be moved under a different parent, sprint or release, so a project can be reorganized into an epic/story hierarchy after the work is finished and completed work can be attributed to the sprint and release it belongs to. A DONE task is auto-archived 30 days after it was completed so finished work clears off the board on its own; archived tasks are never deleted — they move to the Archive view, where any of them can be reopened. The task panel shows this directly: on a DONE or ARCHIVED task the frozen editors — status, type, effort estimate and due date — are disabled and a hint explains that the task must be reopened to be edited, while the placement fields (parent, release, sprint, board column) stay live. In the mobile companion app, tapping the status of a DONE or ARCHIVED task offers a single Reopen action (back to PLANNED) instead of the status list.

Types, hierarchy, and priorities

Types: EPIC · STORY · TASK · SUBTASK (plus the optional THEME and INITIATIVE levels — see below)
Priorities: LOW · MEDIUM · HIGH · CRITICAL · BLOCKER (a project may define more)

Types form a strict hierarchy: epics contain stories, stories contain tasks, tasks contain subtasks. Set a task's place in it with the Parent field (task panel or create dialog): a subtask always needs a parent task, everything else may live without a parent, and the top level of the hierarchy never has one. The panel lists a task's children on the Relations tab (only when it has any), and the parent options always show only the tasks one level up.

Changing a task's Type in the panel keeps the hierarchy consistent for you: turning a task into a subtask first asks you to pick the parent task (the change is saved once you choose it in the Parent field), and changing to a type the current parent no longer fits under clears the parent automatically.

Per-project task settings (admins)

Project owners and admins can tailor the type hierarchy and the priority list for their project from the project menu (the gear button in the top bar) → Task types & priorities.

• Extra hierarchy levels. Switch Theme and Initiative on to extend the hierarchy upward — the full chain becomes Theme → Initiative → Epic → Story → Task → Subtask. Each level is independent: with only Theme enabled, a theme sits directly above epics. Once a level is on, its type appears in the create dialog, filters and parent pickers. A level cannot be switched off while any task (or template) of that type still exists — convert or delete those first.
• Custom priorities. Add your own priorities on top of the built-in five (for example URGENT). Names are stored in upper case and must not clash with a built-in. Custom priorities are then selectable everywhere the built-ins are — create dialog, task panel, filters and bulk actions. A custom priority cannot be deleted while a task or template still uses it.
• Effort estimation. Choose whether the project estimates effort, and in which unit: No estimation (the default), Story points, or Hours. See Effort estimation below.

These settings belong to the project: they travel with a project export/import, and they do not affect any other project.

Effort estimation

A project can give its tasks an effort estimate, measured either in story points or in hours. It is off by default: until an owner or admin picks a unit under Task types & priorities → Effort estimation, no estimate field appears anywhere in the project — no box on the task, no badge on the cards. A team that does not estimate never has to look at one.

Once a unit is on, every story, task and subtask gains an estimate field in that unit — in the task panel and in the create dialog — and shows it as a small badge on board cards and backlog rows. In the story-points case the panel also offers Fibonacci shortcut chips (1 · 2 · 3 · 5 · 8 · 13 · 21); they are a convenience only — you can type any whole number from 0 to 100, so a team on a different scale is not forced onto Fibonacci. Hours accept up to two decimal places, from 0 to 1000. Clicking the chip that is already selected clears the estimate again.

• Empty is not zero. A task with no estimate is unestimated, which is a different statement from an estimate of 0 (“this costs nothing”). Both are allowed, and Octbase keeps them apart. Clear the field to go back to unestimated.
• Epics, initiatives and themes are not estimated. They are containers — their effort is whatever they contain. Octbase refuses an estimate on them, and refuses to change an already-estimated task into one of those types until you clear its estimate first.
• Switching units loses nothing. If you move a project from story points to hours, the points you already entered are kept — they are simply hidden while hours are the active unit, and they come back unchanged if you switch back. The same is true of switching estimation off entirely.
• Hours are an estimate, not a timesheet. This is what you expect the work to take. Octbase does not track logged or remaining time.
• Estimate as you create, or later. The Create task dialog carries the estimate field too, so work can be created already estimated instead of needing a second edit. Leave it empty and the task starts unestimated. The field appears there under the same rules as everywhere else — only when the project estimates, and only while the chosen type can carry an estimate, so switching the type to an epic takes the box away again.
• On the phone too. The mobile companion app (/m/) shows the estimate on its task cards and on the task detail, and lets you change it: tap the estimate row to get the Fibonacci shortcuts and a number field, or Clear estimate to go back to unestimated. Mobile's create form carries the field as well.

Changing the unit is recorded in the project's Activity, and changing a task's estimate in the task's. Estimates travel with a project export/import and are carried by Copy task. Task templates do not carry a default estimate. The sprint burndown still counts tasks rather than effort.

Bulk actions

Select multiple tasks using the checkboxes on the board or task list, then use the bulk action bar that appears at the bottom to apply a change to all selected tasks at once.

Available bulk operations: set status, priority, or assignee; move the selection onto a board column or back to the backlog; archive; and delete (delete is only offered if your role permits it). Both archive and delete ask for confirmation first.

Task list view

The task list is a tabular alternative to the Kanban board — every task in the project is shown in a single scrollable table, grouped by status. It is useful for quickly scanning status across all work or applying bulk changes to a large set of tasks.

Use the filter bar above the table to narrow by type, priority, or status. Filters are encoded in the URL the same way as the board — the view is bookmarkable. The search box next to them matches the title and description of a task, or its ID — see Finding a task by its ID.

Sorting. Click any column header to sort the whole table by that column — the status grouping collapses into one flat, sorted list. Click the same header again to reverse the direction (an ▲/▼ arrow marks the active column), and a third click clears the sort and returns to the status grouping.

Select rows with their checkboxes to use bulk actions across many tasks at once. Each row also has a delete button (shown only if your role permits it) to remove a single task after a confirmation. A task that still has subtasks cannot be deleted directly — delete or detach its subtasks first, and the app tells you when this is why.

Mindmap

The Mindmap entry in the project sidebar renders the project's open tasks as a left-to-right map: the project at the root, then epics → user stories → tasks → subtasks. It gives you a one-screen picture of how the work hangs together. Click any node to open its task panel; double-click a node to fold or unfold its children — a folded node shows a +N badge with the number of hidden children. Folding is a view setting only and lasts until you leave the app.

The hierarchy follows each task's Parent field: a story nests under its epic, a task under its story, a subtask under its task.

Archive

The Archive view lists every task in the project that has the ARCHIVED status — both tasks you archived by hand and tasks Octbase archived automatically. Open it from the Archive entry in the project sidebar.

Click a task's title to open its panel. Use Reopen on any row to bring a task back to the PLANNED status and onto the board again.

Project activity

The project activity view shows a reverse-chronological event log for everything that has happened across the entire project — task changes, comments, page publishes, sprint transitions, and more.

Each entry shows the event type, the actor, a human-readable description, and the timestamp (hover for the exact date and time). Entries that relate to a task are clickable and open that task panel directly.

Activity entries are purged automatically after a retention period (365 days by default; the operator can configure or disable this), so the log shows recent history rather than the project's full lifetime.

Releases

A release is a long-horizon target that groups tasks into a shippable product increment. Press R from inside a project to open the Releases view.

Lifecycle

• PLANNED — work in progress toward this release
• CLOSED — all tasks done; the release has shipped

A release cannot be closed if it still has open tasks — Octbase will show which tasks are blocking the transition.

Sprints

Sprints are time-boxed iterations (typically 1–2 weeks) used to execute toward a release step by step. Only one sprint can be ACTIVE per project at a time. Press S to open the Sprints view.

Sprint states

• PLANNED — created but not yet started; this is when you plan the scope by adding tasks to its board
• ACTIVE — currently running (shown with a blue left border on the card); the scope is locked
• COMPLETED — finished; unfinished tasks are automatically moved back to the backlog

The sprint board

Every sprint gets its own sprint board the moment it is created (its lanes are copied from the project's default board). Open it from the Plan board / Open board button on the sprint card; the board's banner shows the sprint name and links back to the Sprints view. The sprint board exists from creation until the sprint is completed.

Planning the scope (before starting)

While a sprint is PLANNED, open its board and turn on the backlog column (toolbar toggle), then drag tasks from the backlog onto a lane. Dragging a task onto the sprint board adds it to the sprint. Plan all the work you intend to commit to before you start.

Starting and completing a sprint

Click Start Sprint on any PLANNED sprint to activate it. Once a sprint is ACTIVE its scope is locked: you can no longer drag new tasks onto its board (you'll see a "scope is locked" message), but tasks already in the sprint move freely between lanes. At the end of the iteration click Complete Sprint — a confirmation dialog warns that any unfinished tasks will be moved back to the backlog.

Completing a sprint records its result as done / committed — for example 2/5 means 5 tasks were on the board and 2 were DONE. The count reflects what was on the board, and the completed sprint card keeps showing it even after the unfinished tasks return to the backlog.

Assigning tasks to a sprint

The primary way to add tasks is to drag them onto the sprint board while planning (above). You can also set a task's sprint directly from a task panel → Details tab → Sprint field; only PLANNED and ACTIVE sprints appear in the selector.

Sprint reports: burndown & velocity

Every ACTIVE or COMPLETED sprint card has a Report button that expands two charts:

• Burndown — remaining tasks per calendar day of the sprint window against the ideal straight line to zero. It counts tasks, one per task, and does so even in a project that estimates in story points or hours — burning down the estimate is not implemented yet. For a running sprint, future days are blank and the current day updates live.
• Velocity — committed vs. completed task counts of the project's last completed sprints (up to six), so you can see throughput trend across iterations.

Reports are a desktop feature; the mobile companion app does not include them.

Comments & mentions

Add comments on any task from the Comments tab of the task panel.

@mentions

Type @ followed by a team member's name to mention them. A dropdown suggests matching members. Mentioning someone creates an in-app notification and optionally sends them an email.

Replies

Use Reply on any comment to respond to it directly; replies are threaded underneath the comment they answer. You can edit or delete your own comments and replies — deleting a comment that has replies removes the whole thread beneath it.

Notifications

The bell icon in the top bar shows your unread notification count. Click it to see the full list.

Notifications are delivered in-app and optionally by email. You can toggle per-type preferences (in-app / email / both) on your Settings page.

Notification preferences

Notification preferences live on your Settings page (/#/settings), between the language/theme preferences and the two-factor authentication panel. Open the notification panel and click Preferences at the bottom to jump straight there. You choose — per notification kind — whether to receive in-app notifications, email notifications, both, or neither.

For each kind you can independently toggle In-App and Email delivery. Changes take effect immediately.

Real-time updates

Octbase uses Server-Sent Events (SSE) to push live updates to all users viewing the same project. When a teammate moves a task, changes a status, or posts a comment, a “This content has changed” banner appears within about a second on the Board, Backlog and Tasks views, with a Reload button.

The page deliberately does not redraw on its own: a view that repaints while you are reading it costs you your scroll position, your selection, and your place in a half-finished edit. You reload when it suits you. Your own changes never raise the banner — they are already on your screen.

The green dot in the top bar indicates an active live connection. If it drops, the app reconnects automatically with exponential backoff (1 s → 2 s → 4 s → max 30 s).

Wiki pages

Each project has a built-in wiki. Pages are written in AsciiDoc with a live split-pane preview that updates as you type (debounced 300 ms). Press P to open the Pages view, and use the Syntax help button in the editor for a quick reference.

Supported AsciiDoc

The editor renders genuine AsciiDoc: section titles (= through ======), bold *text*, italic _text_, monospace `text`, links (https://site[label], link:target[label]) and bare URLs, unordered (*/-) and ordered (.) lists with nesting, code blocks (---- or [source,lang]), block quotes (____), admonitions (NOTE:, TIP:, WARNING:, IMPORTANT:, CAUTION:), tables (|===), and relative block images (image::/path[alt]). TASK-<id> mentions become links to the task.

For safety, raw-HTML passthrough and external image sources are intentionally not supported, and all rendered output is sanitized on the server, so a page can never run injected scripts. Note that the bold marker is a single * as in standard AsciiDoc (the older Markdown-style **double** form now renders as ordinary bold via AsciiDoc's unconstrained marker).

Page statuses

• DRAFT — work in progress, not yet visible to readers
• PUBLISHED — visible to all project members; each publish creates a revision snapshot
• ARCHIVED — hidden from the active page list

Table of contents

When a published page has three or more headings, a sticky TOC sidebar is generated automatically on the read view.

Revision history

Every publish action creates an immutable revision. Open the revisions panel to see who changed what and when.

Task cross-references

Type a task reference in the form TASK-<id> (the task's full ID, as in TASK-00000000-0000-0000-0000-000000000abc) in page content to create a cross-link. On publish, the reference appears in the task panel under the Activity tab as Referenced in.

Repository connections

Connect a Git repository to a project so that you can create branches and open pull/merge requests for tasks directly from Octbase, with PR status shown on task panels. Supported providers: GitHub, GitLab, and Bitbucket. You can connect more than one repository to a project — useful when a project spans multiple repos (e.g. a separate frontend and backend) — and choose which one to branch in per task.

Adding a repository connection

Open your project and select Repositories from the project navigation. Fill in the form:

• Display name — a friendly label shown in the UI (e.g. backend)
• Repository URL — the full HTTPS clone URL
• Provider — GitHub, GitLab, or Bitbucket
• Default branch — typically main or master
• Access token — a Personal Access Token (PAT) for the provider, used to create branches and pull/merge requests on your behalf (see required permissions below). The token is encrypted at rest and never shown again.

Click Add. When a token is supplied, Octbase validates the repository against the provider on save and adopts its real default branch. The connection then appears in the list and is immediately available in the Branches tab of any task panel in this project.

Access token permissions

The token only needs to read the repository, create branches, and open pull/merge requests. A token that is missing these is rejected on save with "SCM provider rejected the access token".

GitHub — create a token under Settings → Developer settings → Personal access tokens (see GitHub's guide: Managing your personal access tokens):

• Classic token — enable the repo scope (or public_repo for public repositories only).
• Fine-grained token — grant access to the specific repository, then set Contents: Read and write (branches) and Pull requests: Read and write (the mandatory Metadata: Read-only is selected automatically).
• If the repository belongs to an organization with SAML SSO enabled, authorize the token for that organization (Configure SSO), or GitHub returns a 403.

GitLab — create a project or personal access token with the api scope.

Bitbucket — create an access token with Repositories: Read & Write and Pull requests: Read & Write.

Creating a branch for a task

Open the task panel → Branches tab. Select the repository, choose a branch type (feature / bugfix / hotfix / release), and enter the branch name. Octbase suggests a name based on the task type and title — for example feature/dp-42-improve-search. Click Link Branch and Octbase creates the branch on the remote (from the repository's default branch) and records it on the task. Use the copy button if you instead just want the suggested name for your terminal.

Opening a pull request

Once a branch is linked, use Open PR on the branch to open a pull request (GitHub/Bitbucket) or merge request (GitLab) from that branch into the repository's default branch. The PR link and status then appear on the task.

PR status

Once a webhook is configured (see below), PR status updates appear automatically on the task panel: open, merged, or declined, with a direct link to the PR in your provider.

Administrator setup

Two server-side settings are required before repository connections work:

• Token encryption key — set OCTBASE_SCM_ENC_KEY to a 32-byte key (base64- or hex-encoded; generate with openssl rand -base64 32). Access tokens are encrypted at rest with this key, so adding a connection fails with "access token encryption is not configured" until it is set. Do not change it once tokens are stored — existing connections would need to be re-added.
• OAuth apps (optional, only for Connect with OAuth) — register an OAuth app with each provider and set OCTBASE_OAUTH_<PROVIDER>_CLIENT_ID / _CLIENT_SECRET (e.g. OCTBASE_OAUTH_GITHUB_CLIENT_ID) plus OCTBASE_OAUTH_REDIRECT_BASE (the public origin that serves the API). The callback URL to register with the provider is:

<OCTBASE_OAUTH_REDIRECT_BASE>/api/v1/oauth/<github|gitlab|bitbucket>/callback

It must match the OAuth app's registered callback exactly. The default authorize/token endpoints and scopes are GitHub's, GitLab's, and Bitbucket's public ones; for self-hosted instances override them with OCTBASE_OAUTH_<PROVIDER>_AUTH_URL / _TOKEN_URL / _SCOPE.

Webhooks

Configure a webhook in your Git provider to send push and PR events to Octbase. The receiver endpoints are:

• POST /api/v1/webhooks/bitbucket
• POST /api/v1/webhooks/github

Both use HMAC-SHA256 signature validation. Enter the shared secret in your provider's webhook settings and set the matching environment variables on the server (OCTBASE_WEBHOOK_SECRET_BITBUCKET / OCTBASE_WEBHOOK_SECRET_GITHUB). Ask your administrator to configure these.

Import & export

Octbase project archives

The recommended way to back up a project or move it between Octbase instances is the whole-project ZIP export/import in the project's settings gear menu (Export project / Import project). It round-trips tasks, comments, files, and wiki pages — see Projects for details.

Migrating from Jira

Import existing Jira data per project via the Jira CSV import (availability depends on your edition).

Jira CSV import

Export your Jira project as CSV (Project → Export → Export Excel CSV). Then open the project's settings gear menu and choose Import Jira CSV. Octbase maps Jira statuses and priorities to Octbase equivalents and stores the original Jira issue key in the external_ref field for cross-referencing during the transition period. Comments and attachments round-trip too: repeating Comment columns become task comments, and repeating Attachment columns become attachment entries on the imported tasks.

Import report

The import response is a report: how many tasks and attachment links were imported, how many rows were skipped, and a per-row list of warnings (with row number and Jira issue key) for anything that needed a fallback — unknown statuses or priorities, users that could not be matched by email, or malformed attachment/comment cells. The import also appears as a single entry in the project's Activity view.

Dry run

The importer supports a dry run mode that shows a preview of what would be created without writing anything to the database. Use it to verify the mapping before committing the import.

Roles & permissions

Octbase has two layers of roles: a global role (set once per user for the whole platform) and a project role (set per project membership). Authorization is enforced server-side on every request.

Global roles

Project roles

Every project always has at least one PROJECT_OWNER. When a project is created, the creator becomes its owner. Ownership can be transferred to another member by first promoting them to OWNER (only an existing owner can do this), then optionally stepping down.

Admin panel

The admin panel (/#/admin) is visible only to SUPER_ADMIN users. It provides:

• User management — list all users, change global role, enable/disable accounts, delete users. Disabling a user immediately invalidates all their active sessions.
• Audit log (/#/admin/audit-logs) — immutable record of all privileged actions: logins, user changes, project deletes, and more.
• Invitations — generate accept links for new team members.

User management

The user list page opens with a row of statistics cards showing total users, active users, disabled accounts, and a breakdown by global role (SUPER_ADMIN / ADMIN). Use the search box and the role / status filter dropdowns to narrow the list. For each user you can:

• Edit their display name, email address, or global role — after an email change, a security notice is sent to the previous address so a hijacked change doesn't go unnoticed
• Enable or disable their account (disabling immediately invalidates all active sessions)
• Delete the account

Audit log

The audit log at /#/admin/audit-logs is an immutable, append-only record of privileged actions. Each entry shows the timestamp, the actor (user or system), the action type, the target, and metadata such as the affected IP address or changed field values.

Filter by action type using the dropdown to focus on a specific category (e.g. all LOGIN_FAILED events, or all PROJECT_DELETED events). The list is paginated — use the previous / next controls at the top.

For data-protection reasons, audit entries are purged automatically after a retention period (365 days by default; the operator can configure or disable this).

Inviting users

There is no self-registration. ADMIN and SUPER_ADMIN users invite teammates by email. Project OWNERs and ADMINs can also invite users directly to their project.

1. Go to the Admin panel → Invitations, or open a project's Members settings as a PROJECT_OWNER or PROJECT_ADMIN.
2. Enter the invitee's email address and optionally select a project and role. Only an existing PROJECT_OWNER can invite someone directly as PROJECT_OWNER.
3. Octbase generates an accept link and emails the invitation to the invitee automatically (when SMTP is configured on the server). The link is also shown on screen and copied to your clipboard so you can share it manually.
4. The invitee opens the link, enters their name and a password, and their account is created and they are logged in immediately.

Adding an existing user (Super Admin)

A SUPER_ADMIN can add someone who already has an Octbase account straight into a project — no invitation email and no accept step. Open the project's Members settings; under Add an existing user, pick the account, choose a project role, and click Add to project. The user becomes a member immediately. Accounts that are already members, and disabled accounts, are not offered in the list.

Personal settings

The Settings page collects the preferences that belong to you rather than to a project. Open it with the user icon in the top bar's right corner, or navigate to /#/settings. (The gear icon next to it is different — it holds the project settings of the project you are in.)

Language and theme are saved to your account, not just to the browser — sign in on another device or browser and your choices follow you. Changing the language or theme from the top-bar switchers keeps the account preference in sync automatically.

Two-factor authentication

Two-factor authentication (2FA) adds an extra layer of security to your account: after entering your password, you also enter a 6-digit time-based code from an authenticator app (Google Authenticator, 1Password, Authy, …). Each user enables it for their own account on the Settings page.

Enabling 2FA

1. Open Settings and click Enable two-factor authentication.
2. A QR code and a setup key are shown. Scan the QR code with your authenticator app, or add the key manually as a new account (use the copy button to copy it).
3. Enter the 6-digit code your app now generates and click Confirm and enable.
4. Octbase shows your recovery codes — save them somewhere safe (there is a copy button). They are shown only this once. Confirm with I've saved these codes.

From then on, every sign-in asks for a code from your authenticator app after the password step.

Recovery codes

Recovery codes are your fallback if you lose access to your authenticator app. At the sign-in verification step, enter a recovery code instead of the 6-digit code. Each code works exactly once; letter case and the hyphen don't matter when typing one in.

Use Regenerate recovery codes on the Settings page to get a fresh set at any time — this invalidates all previous codes.

Disabling 2FA

Click Disable two-factor authentication on the Settings page. Disabling — like regenerating recovery codes — always requires you to re-prove your identity first: enter your current password, or a code from your authenticator app / a recovery code.

Administrator setup

MFA enrollment requires one server-side setting: OCTBASE_MFA_ENC_KEY, a 32-byte key (base64- or hex-encoded; generate with openssl rand -base64 32) used to encrypt users' authenticator secrets at rest. It is deliberately separate from the SCM token key. Until it is set, users cannot enable two-factor authentication. Do not change it once users are enrolled — they would have to re-enroll.

Requiring 2FA

Administrators can make two-factor authentication mandatory with the server-side setting OCTBASE_REQUIRE_MFA: off (default — 2FA stays voluntary), admins (required for ADMIN and SUPER_ADMIN accounts), or all (required for everyone). When an account in scope signs in without 2FA enabled, the login is interrupted by a forced-enrollment step: the user scans the QR code, saves their recovery codes, and confirms a code from their authenticator app before continuing. Users who already have 2FA enabled just see the normal verification step.

Keyboard shortcuts

Press ? at any time to show the full shortcut overlay inside the app.

Navigation

Task actions

General

Command palette

Press Ctrl+K (or Cmd+K on Mac) from any view to open the command palette.

Type three or more characters to search across tasks, pages, and projects in one box. Navigate results with ↑ ↓ and open with Enter. Press Esc to close.

Search

Octbase has two ways to search:

• Command palette (Ctrl+K) — fast, keyboard-driven, stays in context. Best for quickly jumping to a known task or page.
• Search page (/#/search) — a dedicated full-screen search that queries tasks, pages, and projects together and groups results by type. Useful when you need to scan broadly or share a search URL with a teammate.

On the search page, type a term and press Enter or click Search. Results are grouped into Tasks, Pages, and Projects. Click any result to navigate directly to it. Search terms need at least three characters — shorter ones return no results.

Language

Octbase ships with the interface available in English and German. Use the language switcher in the top bar — or the Settings page — to change the display language. The choice is saved to your account, so it follows you across devices and browsers.

Changing the language affects all UI labels, buttons, and messages immediately. Content created by users (task titles, comments, page text) is not translated.

Appearance & themes

Octbase ships several colour themes. Click the theme button in the top bar to cycle through them, or pick one directly on the Settings page; your choice is saved to your account and follows you across devices.

Themes change only how the interface looks; they have no effect on your data or on what other users see. The mobile companion app supports all the same themes, including Octopus (without the corner mascot, to save space on phone screens).

Bookmarkable URLs

Every view in Octbase has a stable, shareable URL. Filter state and the open task panel are encoded in the URL hash so you can bookmark or share an exact state.

Copy the URL from the browser address bar to share an exact view with a team member — filters, sorting, and open panels are all preserved.