GitScrum / Docs

How GitScrum Works

GitScrum organizes work in a three-level hierarchy: Workspaces contain Projects, Projects contain Tasks. This structure maps directly to how agencies operate — the workspace is your agency, projects are client engagements, and tasks are the actual work.

Understanding this hierarchy is key to using GitScrum effectively. Everything flows from workspace settings down to individual tasks. Team members can belong to a workspace and be assigned to specific projects with different permission levels.

The Workspace Hierarchy

Workspace

The workspace is the top-level container. Think of it as your agency or company inside GitScrum. It holds all your projects, team members, billing information, and global settings.

When you create an account, GitScrum automatically creates your first workspace. Most agencies need just one. Create additional workspaces only if you need complete data isolation between business units or if you manage multiple separate agencies.

Workspace settings affect all projects inside it: work schedule, timezone, billing plan, integrations with GitHub or GitLab. Changes here propagate down.

Project

A project is where actual work happens. Each project gets its own Kanban board, sprints, user stories, wiki, discussions, file storage, and time tracking. Team members are assigned to projects with specific roles.

For agencies, one project per client engagement makes sense. A client might have multiple projects over time — a website launch, then a mobile app, then ongoing maintenance. Each is a separate project with its own board and timeline.

Projects can be public (visible to anyone with the link) or private (team members only). Public projects are useful for open-source work or client dashboards where stakeholders just need to see progress.

Task

Tasks are the atomic units of work. They live on the Kanban board and move between columns as work progresses. Each task has a unique code (like PRJ-123), title, description, assignee, due date, labels, time estimates, and time tracked.

Tasks can have checklists, attachments, comments, and activity history. They can be linked to user stories for Scrum workflows or exist independently for simpler Kanban-only setups. Time tracking integrates directly — start a timer, work, stop when done.

The Kanban Board

Every project has a Kanban board as its central view. Tasks are displayed as cards in columns. Drag cards between columns to update their status. This is where developers spend most of their time.

Default columns are Backlog, To Do, In Progress, and Done. You can customize them — add Review, QA, Blocked, whatever fits your workflow. Each column can have work-in-progress limits to prevent overload.

The board supports filtering by assignee, label, sprint, and due date. Advanced search finds tasks by number or content. Keyboard shortcuts make navigation fast. Real-time sync means everyone sees changes instantly.

Sprints and User Stories

For teams following Scrum, GitScrum supports sprints and user stories. User stories describe features from the user perspective — "As a user, I want to..." — and group related tasks together.

Sprints are time-boxed iterations, typically two weeks. You plan what to accomplish, work through the sprint, then review results. GitScrum tracks velocity (how many story points you complete per sprint) and generates burndown charts showing progress.

Story points are estimated during backlog refinement. GitScrum includes planning poker for collaborative estimation. Drag user stories to prioritize them. When a sprint starts, committed stories lock in — you can see what was planned versus what was actually delivered.

Not doing Scrum? No problem. Sprints and user stories are optional. Many teams use GitScrum as a pure Kanban tool with just tasks and columns.

Time Tracking

Time tracking is built into every task. Click the play button to start a timer. Work. Click stop when done. The time is logged automatically with the current date and optional notes.

You can also add time entries manually — useful for logging work done offline or adjusting entries. Time tracked feeds into project reports, showing hours spent per task, per team member, per date range.

Work schedules defined at the workspace level (working days and hours per day) affect capacity calculations. If someone is assigned 40 hours of work in a week and they work 8-hour days, GitScrum shows them at full capacity. Over-allocation triggers warnings.

Time data exports to reports. Agencies use this for client billing, capacity planning, and understanding where time actually goes.

Roles and Permissions

GitScrum has four roles with different permission levels:

  • Agency Owner — Full access to everything. Manages billing, workspace settings, all team members, all projects. Can delete the workspace. Usually the founder or account holder.
  • Manager — Can manage projects, create and assign tasks, view all reports. Cannot access billing or remove Agency Owners. Typically project managers or team leads.
  • Developer — Can work on assigned projects, complete tasks, track time, comment on work items. Cannot change project settings or access other projects. The standard role for developers and contractors.
  • Client — Limited read-only access. Sees project progress and can comment on tasks they are invited to. Cannot see internal discussions, time tracking details, or other projects. Perfect for stakeholders who need visibility without full access.

Permissions are enforced at both workspace and project levels. A Developer in the workspace can be assigned to specific projects — they only see and interact with those projects.

Roles can be overridden per project. A team member might be a Developer in one project but a Manager in another, depending on their responsibilities.

Integrations

GitHub and GitLab

Connect your repositories to automatically link commits, branches, and pull requests to tasks. Reference a task code in your commit message (like "Fix login issue #PRJ-123") and GitScrum shows that commit on the task.

When a pull request is merged, GitScrum can automatically move the task to Done. Branch information appears on task cards so the team knows who is working on what.

VS Code Extension

The VS Code extension brings GitScrum into your editor. See your assigned tasks, start and stop time tracking, update task status, add comments — all without switching to the browser.

Create tasks from TODO comments in your code. The extension reads your files and lets you convert inline notes into tracked tasks with one click.

Chrome Extension

Capture screenshots and create tasks from any webpage. Found a bug on staging? Screenshot it, add a description, assign it to yourself — done. The screenshot attaches to the task automatically.

Quick task creation without leaving your current context. Useful for support teams, QA, or anyone who finds issues while browsing.

MCP Server for AI Assistants

GitScrum provides an MCP (Model Context Protocol) server that connects to AI assistants like Claude, GitHub Copilot, and others. The AI can read your tasks, update status, log time, and manage projects using natural language.

Ask "What are my open tasks?" or "Log 2 hours on PRJ-123" and the assistant executes it directly. Works from VS Code, terminal, or any MCP-compatible client.

A Typical Workflow

Here is how a typical week looks for a development agency using GitScrum:

  1. Monday morning — Team opens the Kanban board. Each developer grabs tasks from To Do and moves them to In Progress. Time tracking starts.
  2. During the day — Developers work on tasks, logging time as they go. Comments on tasks capture decisions and blockers. PRs reference task codes.
  3. Daily standup — The board serves as the standup agenda. What is in progress? What is blocked? What moved to Done yesterday?
  4. Pull request merged — The GitHub integration moves the task to Done automatically. Time spent is logged.
  5. End of sprint — Velocity reports show how many story points were completed. Burndown chart shows if the team hit the target. Retrospective uses the data to improve.
  6. Client check-in — Share a read-only link to the project. The client sees progress without needing to log in. Or add them as a Client role for comments.

This workflow scales from solo developers to 50-person teams. The hierarchy and permissions keep things organized as you grow.

Next Steps

Now that you understand the architecture: