API Settings

The API tab provides credentials and monitoring for programmatic access to your GitScrum project. Build custom integrations, automate workflows, and connect external systems using the REST API.

API Overview

GitScrum provides a comprehensive REST API for:

• Reading project data (tasks, sprints, members)
• Creating and updating resources
• Triggering actions programmatically
• Syncing with external systems
• Building custom dashboards

Rate Limits Section

Understanding Rate Limits

Rate limits prevent API abuse and ensure fair access for all users. Limits apply per project, per period.

Rate Limit Display

The API tab shows three key metrics:

Rate Limit Tiers

Rate Limit Response

When you hit the limit:

• API returns 429 Too Many Requests
• Retry-After header indicates wait time
• Available counter shows 0

Reset Timing

Rate limits reset on a rolling window:

• Period shows start and end times
• Counter replenishes gradually
• Full reset at period end

Usage Statistics

Request Chart

A visualization shows API usage over time:

• X-axis: Time (hours/days)
• Y-axis: Request count
• Helps identify usage patterns

Usage Analysis

Consistent line: Normal automated processes Spikes: Manual operations or batch jobs Near limit: May need to optimize or upgrade

Recent Requests Table

Request Log

The table shows recent API calls:

Method Indicators

Methods display with color coding:

• GET: Blue (read operations)
• POST: Green (create operations)
• PUT/PATCH: Yellow (update operations)
• DELETE: Red (remove operations)

Log Purpose

Use the request log to:

• Debug integration issues
• Identify unexpected API usage
• Monitor automation behavior
• Audit API access

API Credentials

Getting Credentials

Click "Get Credentials" to access your API key and secret:

1. Button triggers authentication verification
2. Modal displays credentials
3. Copy to use in your applications

Credential Components

API Key: Public identifier for your integration

• Safe to include in code (not truly secret)
• Used in API requests for identification

API Secret: Private authentication token

• Never share or commit to public repositories
• Used to sign requests

Credential Security

IMPORTANT:

• Store secrets in environment variables
• Never commit to version control
• Rotate if potentially exposed
• Use different credentials for dev/prod

Regenerating Credentials

If credentials are compromised:

1. Generate new credentials
2. Update all integrations
3. Old credentials invalidate immediately

Warning: Regenerating breaks all existing integrations until updated.

Making API Requests

Authentication

Include credentials in request headers:

Authorization: Bearer YOUR_API_KEY
X-API-Secret: YOUR_API_SECRET

Or use HTTP Basic Auth:

Authorization: Basic base64(API_KEY:API_SECRET)

Base URL

All API requests use:

https://services.gitscrum.com/v1

Request Format

Headers:

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_API_KEY

Example GET request:

curl -X GET "https://services.gitscrum.com/v1/projects/PROJECT_SLUG/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"

Example POST request:

curl -X POST "https://services.gitscrum.com/v1/projects/PROJECT_SLUG/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Task", "description": "Created via API"}'

Common Endpoints

Tasks

Sprints

Time Entries

Members

Response Format

Successful Response

{
    "data": {
        // Resource data
    },
    "meta": {
        "current_page": 1,
        "total_pages": 5,
        "total_count": 47
    }
}

Error Response

{
    "error": {
        "code": "validation_error",
        "message": "Title is required",
        "details": {
            "title": ["This field is required"]
        }
    }
}

HTTP Status Codes

Pagination

List endpoints return paginated results:

Query Parameters

Example

GET /tasks?page=2&per_page=50

Response Meta

{
    "meta": {
        "current_page": 2,
        "per_page": 50,
        "total_pages": 10,
        "total_count": 487
    }
}

Filtering

Many endpoints support filtering:

Task Filters

Time Entry Filters

Webhooks vs. Polling

When to Use API

• Reading data on demand
• Creating/updating resources
• One-time data sync
• User-initiated actions

When to Use Webhooks

• Real-time notifications
• Event-driven automation
• Continuous synchronization
• External system updates

SDK and Libraries

Official Support

GitScrum provides API documentation at:

https://docs.gitscrum.com/api

Community Libraries

Check the community for language-specific libraries:

• JavaScript/Node.js
• Python
• PHP
• Ruby

Troubleshooting

401 Unauthorized

Causes:

• Invalid API key
• Invalid or missing secret
• Credentials regenerated

Solutions:

• Verify credentials are current
• Check header format
• Re-copy credentials from settings

403 Forbidden

Causes:

• Role lacks permission for action
• Resource belongs to different project
• Action not allowed for resource state

Solutions:

• Verify user role
• Check project slug matches
• Review action requirements

429 Rate Limited

Causes:

• Too many requests in period
• Aggressive polling
• Inefficient integration

Solutions:

• Wait for reset period
• Implement exponential backoff
• Cache responses where possible
• Consider webhook for real-time needs

500 Server Error

Causes:

• GitScrum internal issue
• Temporary outage

Solutions:

• Retry after brief delay
• Check GitScrum status page
• Contact support if persistent

Best Practices

Efficient API Usage

Cache responses: Store data that doesn't change frequently Batch operations: Combine related requests Use webhooks: For real-time needs instead of polling Respect rate limits: Build in backoff logic

Security

Environment variables: Never hardcode credentials Principle of least privilege: Request only needed permissions Audit access: Review API logs regularly Rotate secrets: Periodically regenerate credentials

Error Handling

Expect failures: Networks fail, services timeout Implement retry: With exponential backoff Log errors: For debugging and monitoring Graceful degradation: Handle unavailability

Permissions

API permissions map to user roles—API can't exceed user's project permissions.

The API extends GitScrum's capabilities to any system or workflow you can imagine. Start with reading data, progress to creating resources, and build custom integrations that perfectly fit your team's needs.

Budget Settings

The Budget tab transforms time tracking data into financial insights. Track resource allocation, set custom hourly rates, configure cost alerts, and manage project budget settings all in one place.

Budget Sub-Tabs

Budget settings organize into four specialized sections:

Navigate between sub-tabs using the sidebar within Budget settings.

Allocation Section

The Allocation view shows how team members are spending their time on this project.

Allocation Table

Each row represents a team member with:

Reading Allocation Data

High billable percentage: Team member focused on client-deliverable work. Target varies by role—developers typically higher than managers.

Low billable percentage: More time on internal tasks, meetings, or overhead. Not inherently bad, but worth monitoring.

Uneven distribution: One member with significantly more hours might indicate workload imbalance or bottleneck.

Filtering and Sorting

Default view shows all members with time logged. Data reflects the project's complete history unless filtered.

Refresh Data

Click the refresh button to pull latest time entries. Useful if team members are actively logging time.

Key Metrics

The filter bar shows aggregate metrics:

• Total team members: Number of people with logged time
• Total billable hours: Sum across all members

Rates Section

Set custom hourly rates for individual team members. Custom rates override the project's default rate.

Default Rate

The project's default hourly rate applies to any member without a custom rate. Set this in the Settings sub-tab.

Custom Rate Table

Adding a Custom Rate

1. Click "Add Rate" button
2. Select team member from dropdown
3. Enter hourly rate
4. Click Save

Use cases for custom rates:

• Senior engineers with higher billing rates
• Junior team members at reduced rates
• Contractors with negotiated rates
• Consultants billed at premium rates

Editing Rates

Click the edit icon on any rate row to modify the amount. Changes apply to future calculations—historical costs don't retroactively update.

Removing Custom Rates

Delete a custom rate to revert that member to the default rate. Again, this affects future calculations only.

Rate Display

Rates display in your workspace's configured currency. The format follows locale settings (e.g., $125.00, €125,00).

Alerts Section

Budget alerts notify you when costs approach or exceed thresholds. Proactive notification prevents budget surprises.

Alert Types

Configured Alerts

The alert list shows all budget thresholds:

• Alert name/description
• Threshold amount or percentage
• Current status (OK, Warning, Critical)
• Last triggered timestamp
• Acknowledged status

Alert Behavior

When a threshold is reached:

1. Alert status changes to Warning or Critical
2. Notification sends (email, in-app)
3. Alert appears in dashboard
4. Remains until acknowledged or condition clears

Acknowledging Alerts

Click to acknowledge an alert. This:

• Marks the alert as seen
• Stops repeat notifications (until next trigger)
• Records who acknowledged and when

Acknowledgment doesn't resolve the underlying budget issue—it just confirms awareness.

Alert Configuration

Create alerts in the Settings sub-tab. Common alert thresholds:

• 75% of budget consumed (warning)
• 90% of budget consumed (critical)
• 100% of budget exceeded (critical)

Settings Sub-Tab

Core budget configuration for the project.

Project Budget

Total Budget: The project's overall budget in your currency. This is the number alerts compare against.

Setting a budget enables:

• Budget progress tracking
• Percentage-based alerts
• Cost vs. budget reports

Leave blank if the project doesn't have a fixed budget.

Default Hourly Rate

The rate applied to team members without custom rates. Recommendations:

Agency model: Use your standard client billing rate Internal projects: Use loaded cost (salary ÷ working hours + overhead) Fixed-price projects: May be less relevant—track for internal cost analysis

Alert Configuration

Create and manage budget alerts:

Add Alert:

1. Click "Add Alert"
2. Set threshold (amount or percentage)
3. Choose alert type (warning/critical)
4. Configure notification recipients
5. Save

Edit Alert: Click any alert to modify threshold, type, or recipients.

Delete Alert: Remove alerts no longer needed.

Billable by Default

Toggle whether new time entries default to billable. Team members can override per entry, but this sets the starting state.

Billable by default ON: Most time is client-billable Billable by default OFF: Most time is internal/overhead

Save Settings

Click "Save" to persist changes. Changes to rates and budgets affect future calculations immediately.

Cost Calculations

Understanding how costs calculate helps interpret the data correctly.

Basic Formula

Cost = Hours × Rate

Hours: From time tracking entries Rate: Custom rate if set, otherwise default rate

Billable vs. Non-Billable

Only billable hours factor into billing reports. All hours (billable + non-billable) factor into cost calculations.

Rate Precedence

1. User's custom rate (if set)
2. Project's default rate (if set)
3. Zero (if no rate configured)

Currency

All monetary values use the workspace's configured currency. Currency cannot differ per project—it's workspace-wide.

Historical Data

Rate changes don't retroactively recalculate historical costs. The cost at time of entry persists.

To update historical costs after rate changes, you would need to manually adjust time entries.

Reports and Analysis

Budget data feeds into GitScrum's reporting system:

Available Reports

Cost by Team Member: Who's consuming budget Cost by Task: Which tasks are expensive Cost Over Time: Budget burn rate trends Billable vs. Non-Billable: Utilization analysis

Exporting Data

Export budget data to CSV or Excel for external analysis or client billing.

Integration with Invoicing

If using GitScrum invoicing, budget data can auto-populate:

• Time entries → line items
• Rates → pricing
• Project → invoice grouping

Best Practices

Budget Planning

Set realistic budgets: Include buffer for scope changes and unexpected work.

Review monthly: Don't wait for alerts—proactively check budget status.

Communicate with stakeholders: Share budget status in project updates.

Rate Management

Document rate logic: Note why rates differ between team members.

Review annually: Rates should reflect current costs and billing realities.

Consider loaded costs: For internal projects, include overhead in calculations.

Alert Strategy

Multiple thresholds: Use warning at 75%, critical at 90%.

Right recipients: Alert people who can take action.

Don't ignore alerts: Acknowledged isn't the same as addressed.

Time Tracking Discipline

Budget accuracy depends on time tracking accuracy:

• Log time daily
• Use correct billable flags
• Associate time with correct tasks

Permissions

Regular team members see their own allocation but not team-wide rates or alert configuration.

Troubleshooting

Costs showing $0: Check that default rate is set and time entries exist.

Alerts not triggering: Verify alert is enabled and threshold hasn't been acknowledged.

Wrong currency: Currency is workspace-level—contact workspace admin to change.

Rates not applying: New rates apply to future entries only. Check entry timestamp vs. rate change timestamp.

Missing team members in allocation: Members must have logged time to appear.

Budget settings transform time data into actionable financial insights. Configure once, monitor regularly, and stay ahead of budget issues before they become problems.

Project Details Settings

The Details tab controls your project's fundamental identity and feature availability. This is where you configure what your project is called, what it does, and what GitScrum capabilities it uses.

Basic Information Section

Project Name

The primary identifier for your project throughout GitScrum. This name appears in:

• Sidebar navigation
• Project headers and breadcrumbs
• Notifications and emails
• Reports and exports
• Search results

Best practices:

• Keep it concise (2-4 words)
• Make it recognizable to your team
• Avoid generic names like "Project 1"
• Consider prefixes for related projects (Client-Web, Client-Mobile)

Character limit: 255 characters maximum

Project Description

Optional explanatory text about the project's purpose, scope, or current focus. Useful for:

• Onboarding new team members
• Distinguishing between similar projects
• Documenting project phase or objectives

The description displays on the project overview and in project listings.

Category

Categories organize projects at the workspace level. Select from existing categories or leave uncategorized.

Category benefits:

• Filter project lists by category
• Group related projects in reports
• Organize workspace dashboard

Categories are managed at the workspace level—you select from available options here, you don't create new ones.

Project Features Section

Toggle individual GitScrum features on or off for this project. Each toggle controls visibility of that feature in the project sidebar and throughout the interface.

Available Features

Feature Toggle Behavior

When disabled:

• Feature disappears from project sidebar
• Related menu items hide
• Existing data remains preserved
• Links to that feature return errors

When re-enabled:

• Feature reappears immediately
• All historical data restores
• No data is ever deleted by disabling

Why Disable Features?

Not every project needs every feature. A documentation project might only need Wiki and Documents. A simple task tracker might only need the Kanban board (which is always enabled).

Benefits of disabling unused features:

• Cleaner sidebar navigation
• Reduced cognitive load for team
• Faster onboarding for new members
• Focused workflow without distractions

Default State

New projects have all features enabled by default. Adjust during initial setup or anytime during the project lifecycle.

Branding Section

Customize your project's visual identity with a custom logo.

Upload Project Logo

Supported formats: PNG, JPG, GIF Recommended size: 256×256 pixels (square) Maximum file size: 2MB

Upload methods:

1. Drag and drop: Drag an image file onto the upload area
2. Click to browse: Click the upload area to open file picker

Logo Display Locations

Your uploaded logo appears in:

• Project sidebar (small icon)
• Project header
• Project selection lists
• Notifications (some email clients)

Upload Progress

A progress indicator shows during upload. Large files or slow connections may take a few seconds.

Remove Logo

Click the remove/delete button to revert to the default project icon (a colored square with project initials).

Logo Tips

• Use transparent backgrounds: PNG with transparency looks cleanest
• Simple icons work best: Detailed images become unrecognizable at small sizes
• Consistent branding: Match your organization's visual identity
• Test in dark mode: Ensure visibility on dark backgrounds

Danger Zone Section

Irreversible actions that significantly impact the project. These controls require explicit confirmation to prevent accidental activation.

Delete Project

Permanently removes the project and all associated data:

What gets deleted:

• All tasks (open, closed, archived)
• All sprints and sprint history
• All time entries
• All wiki pages and revisions
• All documents and folders
• All discussion channels and messages
• All user stories and epics
• All project settings
• All integration configurations
• All webhook settings
• All API access logs

What gets preserved:

• Workspace settings (unaffected)
• User accounts (unaffected)
• Other projects (unaffected)
• Billing history (if project had associated invoices)

Delete Confirmation

The confirmation dialog requires typing the exact project name:

1. Dialog shows warning about permanent deletion
2. Text field requires exact project name match
3. Case-sensitive: "My Project" ≠ "my project"
4. Delete button only enables when name matches

Who Can Delete

Only users with Agency Owner role can delete projects. Managers and regular members see the Danger Zone but cannot activate delete.

Before You Delete

Consider alternatives:

• Archive: Hide project from active lists while preserving data
• Export: Download project data before deletion
• Transfer: Hand off to another workspace owner

Verify with stakeholders:

• Confirm with project stakeholders
• Ensure no critical data needs preservation
• Check if any integrations depend on this project

After Deletion

• Project immediately disappears from all views
• Members lose access instantly
• Any scheduled reports for this project fail
• Webhooks stop firing
• API calls return 404

Recovery: Deletion cannot be undone. There is no trash or restore mechanism. The data is permanently removed from GitScrum servers.

Saving Changes

Save Button

The header contains a Save button that becomes active when changes are detected:

Button states:

• Save: Changes detected, ready to save
• Saving...: Save in progress (with spinner)
• Saved: Successfully saved (briefly shows before resetting)

Automatic Detection

The form tracks changes automatically:

• Modified text fields
• Toggled features
• Uploaded/removed logo

Navigating away with unsaved changes prompts a confirmation dialog.

Save Errors

If save fails:

• Error message displays
• Changes remain in form
• Retry save after checking network connection

Common causes:

• Network disconnection
• Session expired (re-login required)
• Permission changes (role modified by admin)

Form Validation

Project Name Validation

• Required: Cannot be empty
• Unique: Must be unique within workspace
• Length: Maximum 255 characters
• Characters: Any Unicode characters allowed

Description Validation

• Optional: Can be empty
• Length: Maximum 1000 characters
• Formatting: Plain text only (no markdown)

Keyboard Shortcuts

Loading States

Initial load:

• Spinner displays while fetching project data
• Form appears once data loads
• Error state shows if load fails with retry option

Logo upload:

• Progress bar during upload
• Spinner during processing
• Success state briefly flashes

Save operation:

• Button shows spinner
• Form stays interactive (but save disabled)
• Success/error feedback on completion

Error States

Load Error

If project data fails to load:

• Error icon and message display
• "Retry" button attempts reload
• Check network and permissions if persists

Save Error

If changes fail to save:

• Toast notification shows error
• Changes preserved in form
• "Save" button remains active for retry

Upload Error

If logo upload fails:

• Error message below upload area
• Previous logo remains (if any)
• Try smaller file size or different format

Project Details establishes the foundation of your project's identity and capabilities. Configure thoughtfully at project creation, then adjust as your project evolves.

Integrations Settings

The Integrations tab connects GitScrum to the tools your team already uses. Send notifications to chat platforms, link version control systems, and automate workflows through third-party services.

Integration Categories

GitScrum integrations divide into two groups:

Native Integrations

Built directly into GitScrum with deep functionality:

• Slack: Team messaging
• Microsoft Teams: Enterprise communication
• Discord: Community-focused chat
• GitHub: Version control (Pro)
• GitLab: Version control (Pro)
• Bitbucket: Version control (Pro)

External Integrations

Connect through third-party platforms:

• Zapier: 5,000+ app connections
• Make (Integromat): Advanced workflow automation

Integration Interface

Sidebar Layout

The left sidebar lists all available integrations:

• Integration icon and name
• Connection status indicator
• Pro badge for premium features

Click any integration to view its configuration panel on the right.

Status Indicators

Active Count

The header shows total active integrations, giving quick visibility into how connected your project is.

Communication Integrations

Slack

Connect Slack to receive project notifications in your workspace channels.

Setup Process:

1. Click Slack in the sidebar
2. Click "Connect to Slack"
3. Authorize GitScrum in Slack's OAuth flow
4. Select the workspace to connect
5. Choose default notification channel
6. Save configuration

Configuration Options:

• Channel: Which Slack channel receives notifications
• Events: Select which events trigger notifications
• Format: Rich or simple message format

Notification Events:

• Task created, updated, completed
• Sprint started, completed
• Team member added/removed
• Comments and mentions
• Time entries logged

Testing: Click "Send Test Message" to verify the connection works. A sample notification appears in your configured channel.

Disconnecting: Click "Disconnect" to remove the Slack integration. Notifications stop immediately. Historical messages in Slack remain.

Microsoft Teams

Teams integration mirrors Slack functionality for Microsoft 365 environments.

Setup Process:

1. Click Microsoft Teams in sidebar
2. Click "Connect to Teams"
3. Sign in with Microsoft account
4. Grant permissions to GitScrum
5. Select team and channel
6. Configure notification preferences

Webhook Option: Alternatively, use an incoming webhook:

1. Create incoming webhook in Teams
2. Copy webhook URL
3. Paste URL in GitScrum configuration
4. Select events to send

Events and formatting match Slack capabilities.

Discord

Connect Discord for community or team notifications.

Setup Process:

1. Click Discord in sidebar
2. Choose connection method:

• OAuth (recommended)
• Webhook URL (simpler)

1. For OAuth: Authorize and select server/channel
2. For Webhook: Paste Discord webhook URL
3. Configure events

Discord-specific options:

• Rich embeds with task details
• @role mentions for critical events
• Custom bot name and avatar

Note: Discord webhooks don't support all formatting options OAuth provides.

Version Control Integrations (Pro)

Link Git repositories to connect commits, branches, and pull requests with GitScrum tasks.

GitHub

Requirements:

• Pro subscription
• GitHub account with repository access
• Organization or personal repositories

Setup Process:

1. Click GitHub in sidebar
2. Click "Connect GitHub Account"
3. Authenticate via GitHub OAuth
4. Grant repository access permissions
5. Select repositories to link

Configuration:

• Repositories: Choose which repos connect to this project
• Auto-linking: Enable smart commit message parsing
• Pull Request Status: Show PR status on tasks

Commit Linking: Include task identifiers in commit messages:

git commit -m "Add login validation [GS-123]"

GitScrum automatically links the commit to task GS-123.

Supported identifiers:

• [GS-123] or GS-123
• #123 (if configured)
• Task UUID (for API integrations)

Pull Request Integration:

• PR creation notifies on linked tasks
• PR status shows in task view
• Merge closes linked tasks (if configured)

GitLab

Identical functionality to GitHub for GitLab users.

Setup Process:

1. Click GitLab in sidebar
2. Click "Connect GitLab Account"
3. Authenticate via GitLab OAuth
4. Select projects/repositories
5. Configure linking preferences

Self-hosted GitLab: Enterprise users can connect self-hosted GitLab instances:

1. Enter GitLab instance URL
2. Create personal access token
3. Configure permissions
4. Complete connection

Bitbucket

Atlassian users can connect Bitbucket repositories.

Setup Process:

1. Click Bitbucket in sidebar
2. Authenticate via Bitbucket OAuth
3. Select repositories
4. Configure commit linking

Bitbucket-specific:

• Supports both Cloud and Server
• Works with Bitbucket Pipelines
• Integrates with Jira migrations

External Integration Platforms

Zapier

Connect GitScrum to 5,000+ apps through Zapier's automation platform.

What Zapier enables:

• Create tasks from form submissions
• Sync with CRM systems
• Notify via SMS or email
• Update spreadsheets from task data
• Trigger actions in any Zapier-supported app

Getting Started:

1. Click Zapier in sidebar
2. Opens Zapier's GitScrum integration page
3. Create account or sign in
4. Build "Zaps" connecting GitScrum to other apps

Popular Zaps:

• Gmail → GitScrum: Email creates task
• Google Sheets → GitScrum: Row creates task
• GitScrum → Google Calendar: Task deadline creates event
• Typeform → GitScrum: Form submission creates task

Authentication: Zapier connects via GitScrum API. You'll enter API credentials when setting up the Zap.

Make (Integromat)

More advanced automation with visual workflow builder.

What Make enables:

• Complex multi-step scenarios
• Conditional logic and branching
• Data transformation between apps
• Scheduled and triggered workflows

Getting Started:

1. Click Make in sidebar
2. Opens Make's GitScrum module page
3. Create scenarios connecting GitScrum

Make vs. Zapier:

• Make: More powerful, steeper learning curve
• Zapier: Simpler, more expensive at scale

Event Reference

Task Events

Sprint Events

Time Entry Events

Project Events

Troubleshooting

Slack Not Connecting

OAuth errors:

• Ensure you have Slack workspace admin permission
• Check browser allows popups for OAuth flow
• Try disconnecting and reconnecting

Messages not appearing:

• Verify correct channel selected
• Check Slack app permissions
• Send test message to confirm

Wrong channel:

• Edit integration and change channel
• Note: Changing channel doesn't move historical messages

GitHub Not Linking Commits

Commits not showing:

• Verify repository is connected
• Check commit message includes task ID
• Ensure pusher has GitScrum account linked

Wrong task linked:

• Task ID format matters: [GS-123] not GS 123
• Multiple IDs? First match wins

Permission denied:

• Re-authorize GitHub connection
• Check repository visibility settings
• Verify organization permissions

Integration Disconnected

Automatic disconnection causes:

• Token expired (re-authenticate)
• Permissions revoked in external service
• Password changed on external account

Fix: Disconnect then reconnect the integration to refresh tokens.

Events Not Firing

Checklist:

1. Is the integration connected? (green indicator)
2. Is the event type enabled?
3. Check rate limits on external service
4. Review error logs if available

Best Practices

Notification Management

Don't over-notify:

• Choose critical events only
• Use separate channels for different event types
• Consider digest notifications vs. real-time

Channel organization:

• Project-specific channels work well
• Separate channels for different teams
• Archive channels for completed projects

Version Control

Commit message standards:

• Establish team convention for task references
• Document expected format
• Use commit hooks to enforce if needed

Branch naming: Consider including task IDs in branch names:

feature/GS-123-add-login

Security

API credentials:

• Don't share API keys in public channels
• Rotate keys periodically
• Use minimum required permissions

OAuth connections:

• Review connected apps periodically
• Disconnect unused integrations
• Audit who has integration admin access

Permissions

Pro Features

GitHub, GitLab, and Bitbucket integrations require a Pro subscription. The integration panel shows a "PRO" badge next to these options.

What Pro adds:

• Full version control integration
• Commit and PR linking
• Repository sync
• Branch status tracking

Non-Pro users see the options but cannot complete setup.

Integrations connect GitScrum to your existing workflow. Start with communication notifications, add version control if you're using Git, and explore automation platforms for advanced workflows.

Members Settings

The Members tab controls who has access to your project. Assign entire teams or add individual members to ensure the right people can collaborate while maintaining access control.

Access Model

GitScrum uses a layered access model:

1. Workspace membership: User must belong to workspace
2. Team or individual assignment: User gets project access via team or direct assignment
3. Role permissions: User's workspace role determines capabilities

Project access doesn't override workspace roles—permissions come from workspace-level role assignment.

Members Interface

Filter Bar

The header displays:

• Current view title
• Count of team assignments
• Count of individual members
• Search input for filtering

Search

Type to filter by:

• Team name
• Member name
• Email address

Results update in real-time as you type.

Add Members Button

Click to open the member/team assignment dialog. Available to Agency Owners and Managers with appropriate permissions.

Team Assignments Section

Expandable Section

Click the "Team Assignments" header to expand/collapse. Shows count in parentheses.

Team Table

When expanded, a table displays assigned teams:

Team Row Expansion

Click a team row to expand and see individual members within that team:

• Member avatar and name
• Member email
• Role within team
• Joined date

Assigning Teams

1. Click "Add Members"
2. Select "Teams" tab
3. Choose team(s) to add
4. Confirm assignment

All team members immediately gain project access.

Team Access Behavior

When a team is assigned:

• Current members: Get immediate access
• Future additions: Automatically get access when added to team
• Removed members: Lose access when removed from team

This makes team assignment self-maintaining.

Removing Team Assignment

Click the remove button on a team row:

1. Confirmation dialog appears
2. Confirm to remove
3. All team members lose access immediately

Note: Members with individual assignment retain access even if their team is removed.

Individual Members Section

Expandable Section

Click "Individual Members" header to expand/collapse. Shows count in parentheses.

Member Table

Individual assignments display:

Adding Individual Members

1. Click "Add Members"
2. Select "Members" tab
3. Search or browse available members
4. Select member(s) to add
5. Confirm

Individual vs. Team Assignment

When to use individual:

• Temporary project contributor
• Cross-functional collaborator
• Special access cases

When to use team:

• Permanent project team
• Role-based access (all developers)
• Self-maintaining access

Removing Individual Members

Click remove button on member row:

1. Confirmation dialog
2. Confirm removal
3. Member loses immediate access

Exception: If member's team is also assigned, they retain access through team membership.

Add Members Dialog

Dialog Structure

Two-tab interface:

• Teams: Available teams to assign
• Members: Individual workspace members

Teams Tab

Shows workspace teams not already assigned:

• Team name and color
• Member count
• Multi-select capability

Members Tab

Shows workspace members not individually assigned:

• Search by name or email
• Avatar and name display
• Role indicator
• Multi-select capability

Bulk Selection

Select multiple teams or members before confirming. Useful when setting up new projects or large access changes.

Permission Requirements

Who Can View

All project members can see:

• Team assignments
• Individual member list
• Their own access type

Who Can Manage

Managers can add individuals but typically cannot manage team assignments.

Self-Removal

Users cannot remove themselves from a project. This prevents accidental lockout. Request another authorized user to remove your access if needed.

Access Implications

What Access Provides

Project members can:

• View project in sidebar
• Access enabled features (Kanban, Wiki, etc.)
• See tasks and project data
• Interact based on role permissions

What Access Doesn't Provide

• Elevated permissions beyond workspace role
• Access to other projects (separate assignment)
• Administrative capabilities (unless role permits)

Role Capabilities

Access + Role determines actual permissions:

Loading States

Initial Load

Spinner displays while fetching:

• Team assignments
• Individual members
• Team member details

Team Expansion

When expanding a team, additional loading may occur to fetch team members.

Save Operations

Adding or removing shows inline loading. Operations complete before UI updates.

Common Scenarios

Setting Up New Project

1. Add core project team
2. Add individual stakeholders
3. Verify all expected members appear

Team Member Changes

New hire joins existing team:

• Automatically gets access to team's projects
• No action needed

Contractor engagement:

• Add individually to specific projects
• Remove when engagement ends

Project Phase Change

Transitioning to maintenance:

• Remove development team
• Add support team
• Keep key individuals

Access Audit

Review periodically:

• Do all assigned teams still need access?
• Are individual assignments still relevant?
• Anyone missing who should have access?

Troubleshooting

Member Can't Access Project

Check:

1. Member exists in workspace
2. Member is assigned (team or individual)
3. Member's role permits project access
4. Project is active (not archived)

Team Assignment Shows No Members

Possible causes:

• Team itself is empty
• Loading still in progress
• Permissions prevent viewing team details

Can't Add Certain Members

Possible causes:

• Already assigned (individually or via team)
• User not in workspace
• Insufficient permissions to add

Removed Member Still Has Access

Check:

• Are they assigned via a team that wasn't removed?
• Did the removal save successfully?
• Have they refreshed their session?

Best Practices

Use Teams When Possible

Benefits:

• Self-maintaining access
• Easier auditing
• Role-based organization
• Consistent across projects

Individual for Exceptions

Use for:

• One-off collaborations
• Cross-team contributors
• Temporary access

Regular Audits

Monthly review:

• Remove access for departed members
• Add access for new team members
• Verify team assignments are current

Document Access Decisions

Track:

• Why teams were assigned
• Special individual access reasons
• Access changes and dates

API Access

Manage members programmatically:

GET /projects/{slug}/members
POST /projects/{slug}/members
DELETE /projects/{slug}/members/{uuid}

GET /projects/{slug}/teams
POST /projects/{slug}/teams
DELETE /projects/{slug}/teams/{uuid}

Useful for automated access provisioning.

Members settings ensure the right people have access to collaborate on your project. Use teams for systematic access, individuals for exceptions, and audit regularly to keep access aligned with reality.

Work Schedule Settings

The Work Schedule tab defines when work happens on this project. Configure working days, daily hours, and holidays to ensure capacity calculations, sprint planning, and time tracking reflect reality.

Schedule Hierarchy

GitScrum uses a hierarchy for work schedules:

1. Workspace default: Applies to all projects unless overridden
2. Project override: This project uses custom schedule

The toggle "Override workspace schedule" controls which applies.

Override Workspace Schedule

When Disabled (Default)

The project uses workspace-level schedule settings. An info box displays:

• Current workspace working days
• Hours per day from workspace settings

Any schedule changes require workspace admin access.

When Enabled

The project uses its own custom schedule. Full configuration options appear:

• Working days grid
• Hours per day slider
• Project-specific holidays

Working Days Configuration

Day Selection Grid

Seven buttons represent each day of the week:

Selecting Working Days

Click a day to toggle:

• Active (highlighted): Work day
• Inactive (muted): Non-work day

Most organizations use Monday-Friday. Some scenarios require different configurations:

• Weekend coverage: Include Sat/Sun
• Religious observance: Exclude specific days
• Compressed schedule: Four 10-hour days

Working Days Count

Below the grid, a summary shows: "X working days per week"

This affects:

• Weekly capacity calculations
• Sprint day counts
• Resource availability forecasting

Hours Per Day

Setting Daily Hours

A slider or input controls hours worked per day:

• Range: 1-24 hours (practical range: 4-12)
• Default: 8 hours
• Increments: 0.5 hours

Weekly Capacity

The configuration shows calculated weekly capacity:

Hours per day × Working days = Weekly capacity
8 hours × 5 days = 40 hours/week

Impact on Planning

Hours per day affects:

• Sprint capacity: Total available hours
• Effort-to-hours conversion: Story points to hours ratio
• Time tracking expectations: What counts as a "full day"
• Burndown calculations: Expected daily progress

Project Holidays

Holiday List

View and manage project-specific holidays that exclude days from working time.

Adding Holidays

1. Click "Add Holiday"
2. Select date from date picker
3. Click "Add" to confirm

Holidays appear in chronological list:

• Date displayed in locale format
• Delete button to remove

Removing Holidays

Click the remove icon next to any holiday. It's deleted immediately.

Holiday Impact

Holidays affect:

• Sprint planning: Day excluded from sprint duration
• Capacity calculations: Reduced available hours
• Calendar views: Day marked as non-working
• Deadline calculations: Account for holidays

Common Holidays to Add

Consider adding:

• National/public holidays
• Company closure days
• Team off-site events
• Extended breaks (holiday season)

Bulk Holiday Management

For many holidays, consider:

1. Manage at workspace level (applies to all projects)
2. Use project-level only for project-specific closures

Saving Changes

Save Button

Click "Save" in the header to persist changes. The button shows:

• Save Changes: Changes detected
• Saving...: Save in progress
• Successfully saved returns to normal state

When to Save

Changes require explicit save:

• Modified working days
• Changed hours per day
• Added or removed holidays
• Toggle override setting

Navigating away with unsaved changes prompts confirmation.

Schedule Source Indicator

The header shows current schedule source:

• "Using workspace schedule": Project inherits workspace settings
• "Using project schedule": Override is active

This helps quickly identify which configuration applies.

Impact Visualization

Capacity Preview

When planning sprints, the schedule affects:

Example calculation:

• Working days: Mon-Fri (5 days)
• Hours per day: 8 hours
• Sprint length: 2 weeks
• Holidays in sprint: 1 day

Available days: (5 days × 2 weeks) - 1 holiday = 9 days
Total capacity: 9 days × 8 hours = 72 hours

Time Tracking Context

Schedule affects how logged time displays:

• Daily totals compare against hours per day
• Weekly totals compare against weekly capacity
• Overtime calculated when exceeding schedule

Common Configurations

Standard Work Week

Days: Mon, Tue, Wed, Thu, Fri
Hours: 8 per day
Weekly capacity: 40 hours

Compressed Work Week

Days: Mon, Tue, Wed, Thu
Hours: 10 per day
Weekly capacity: 40 hours

Six-Day Week

Days: Mon, Tue, Wed, Thu, Fri, Sat
Hours: 7 per day
Weekly capacity: 42 hours

Part-Time Project

Days: Mon, Tue, Wed
Hours: 6 per day
Weekly capacity: 18 hours

Best Practices

Accuracy Over Optimism

Set realistic hours: If team actually works 6 productive hours, don't set 8.

Include holidays early: Add known holidays at project start.

Review periodically: Adjust as team patterns change.

Consistency

Match reality: Schedule should reflect how work actually happens.

Team awareness: Ensure team knows the configured schedule.

Update promptly: Adjust when circumstances change.

Override Wisely

Use workspace defaults when projects follow standard schedule.

Override only when needed:

• Client in different timezone/region
• Project with unique requirements
• Temporary different schedule

Permissions

Regular members see the schedule but cannot modify it.

Troubleshooting

Capacity Calculations Wrong

Check:

• Working days correctly set
• Hours per day accurate
• Holidays properly entered
• Override toggle in expected state

Schedule Not Applying

If using workspace schedule:

• Verify override is disabled
• Check workspace settings for correct values

If using project schedule:

• Confirm override is enabled
• Save after making changes

Holidays Not Excluded

• Verify holiday is in correct date format
• Check holiday falls within relevant period
• Ensure holiday was saved (not just added)

Sprint Capacity Mismatch

Sprint capacity combines:

• Work schedule settings
• Team member availability
• Individual time off

All three factor into final capacity. Check each if numbers seem wrong.

Technical Notes

Timezone Handling

Holidays and working days use project timezone. Ensure project timezone is correctly configured for accurate date handling.

Date Format

Holiday dates display in your locale's format. The system stores dates in ISO format (YYYY-MM-DD) regardless of display.

API Access

Work schedule is accessible via API:

GET /projects/{slug}/settings/schedule
PUT /projects/{slug}/settings/schedule

Useful for programmatic schedule management.

Work Schedule ensures GitScrum's planning and tracking features reflect how your team actually works. Configure accurately, maintain diligently, and your capacity planning stays grounded in reality.

Webhooks Settings

Webhooks send HTTP POST requests to your endpoints when events occur in GitScrum. Build custom integrations, trigger external workflows, and keep external systems synchronized with project activity.

Webhook Fundamentals

What Webhooks Do

When a configured event happens:

1. GitScrum detects the event
2. Constructs a JSON payload with event data
3. Sends HTTP POST to your endpoint URL
4. Logs the response for debugging

Use Cases

• Custom notifications: Send to proprietary chat systems
• Data synchronization: Update external databases
• Workflow triggers: Start CI/CD pipelines
• Audit logging: External event recording
• Third-party integrations: Connect unsupported services

Webhook Interface

Table Layout

Webhooks organize by event category in an expandable table:

Event Categories

Click category headers to expand/collapse:

Tasks: Task lifecycle events Sprints: Sprint management events Time Entries: Time tracking events Projects: Project configuration events

Stats Display

Header shows webhook metrics:

• Total configured webhooks
• Active webhooks count

Configuring Webhooks

Adding an Endpoint

1. Find the event type you want to monitor
2. Enter your endpoint URL in the input field
3. Press Enter or click away to save

URL requirements:

• Must be a valid HTTP or HTTPS URL
• Must be publicly accessible (or within your network)
• Should return 2xx status to confirm receipt

Endpoint Format

https://your-domain.com/webhooks/gitscrum
https://api.yourservice.com/hooks/incoming
https://hooks.slack.com/services/T00/B00/xxx (for Slack)

URL Validation

Invalid URLs show an error state:

• Red border on input
• Validation message appears
• Save blocked until corrected

Removing an Endpoint

Clear the URL field and save. The webhook deactivates immediately.

Event Reference

Task Events

Sprint Events

Time Entry Events

Project Events

Payload Structure

All webhooks send JSON payloads with consistent structure:

{
  "event": "task.created",
  "timestamp": "2024-01-15T14:30:00Z",
  "project": {
    "uuid": "proj-uuid-123",
    "name": "Project Name",
    "slug": "project-name"
  },
  "data": {
    // Event-specific data
  },
  "triggered_by": {
    "uuid": "user-uuid-456",
    "name": "John Doe",
    "email": "john@example.com"
  }
}

Task Payload Example

{
  "event": "task.created",
  "timestamp": "2024-01-15T14:30:00Z",
  "project": {
    "uuid": "proj-abc123",
    "name": "Web Development",
    "slug": "web-development"
  },
  "data": {
    "uuid": "task-xyz789",
    "title": "Implement user authentication",
    "description": "Add login and registration",
    "status": {
      "name": "To Do",
      "slug": "todo"
    },
    "priority": "high",
    "assignee": {
      "uuid": "user-456",
      "name": "Jane Smith"
    },
    "due_date": "2024-01-20",
    "effort": 5,
    "labels": ["feature", "security"]
  },
  "triggered_by": {
    "uuid": "user-123",
    "name": "John Doe"
  }
}

Sprint Payload Example

{
  "event": "sprint.started",
  "timestamp": "2024-01-15T09:00:00Z",
  "project": {
    "uuid": "proj-abc123",
    "name": "Web Development"
  },
  "data": {
    "uuid": "sprint-def456",
    "name": "Sprint 5",
    "goal": "Complete authentication module",
    "start_date": "2024-01-15",
    "end_date": "2024-01-29",
    "task_count": 12,
    "total_effort": 45
  },
  "triggered_by": {
    "uuid": "user-123",
    "name": "John Doe"
  }
}

Testing Webhooks

Test Button

Each configured webhook has a test button. Click to send a sample payload:

1. GitScrum sends test payload to your endpoint
2. Response displays inline:

• Success (2xx): Green confirmation
• Failure: Error message with status code

Test Payload

Test payloads clearly identify as tests:

{
  "event": "webhook.test",
  "timestamp": "2024-01-15T14:30:00Z",
  "test": true,
  "message": "This is a test webhook from GitScrum"
}

Test All

"Test All" button in header sends test payloads to all configured webhooks simultaneously. Useful for verifying entire webhook configuration at once.

Response Handling

Expected Response

Your endpoint should return:

• Status 2xx: Webhook received successfully
• Response time: Under 30 seconds

Timeout

GitScrum times out after 30 seconds. Long-running processes should:

1. Return 202 Accepted immediately
2. Process asynchronously

Retry Logic

Failed webhooks retry automatically:

• 1st retry: 1 minute after failure
• 2nd retry: 5 minutes after 1st retry
• 3rd retry: 30 minutes after 2nd retry
• Final retry: 2 hours after 3rd retry

After all retries fail, the webhook logs as failed.

Status Codes

Security

Endpoint Security

HTTPS recommended: Always use HTTPS endpoints in production.

IP whitelisting: GitScrum webhooks originate from documented IP ranges. Contact support for current list.

Signature verification: Coming feature—will sign payloads for verification.

Securing Your Endpoint

1. Secret tokens: Add query parameter or header for verification

`` https://yoursite.com/webhooks?token=secret123 ``

1. IP restriction: Only accept from GitScrum IPs

1. Rate limiting: Protect against replay attacks

1. Input validation: Always validate payload structure

Common Integrations

Slack Incoming Webhook

1. Create Incoming Webhook in Slack
2. Copy webhook URL
3. Paste as endpoint for desired events

Note: Native Slack integration provides richer formatting.

Discord Webhook

1. Create webhook in Discord channel settings
2. Use webhook URL directly
3. Discord accepts standard JSON payloads

Custom Server

Example Node.js endpoint:

app.post('/webhooks/gitscrum', (req, res) => {
  const { event, data } = req.body;
  
  // Process based on event type
  switch(event) {
    case 'task.created':
      handleNewTask(data);
      break;
    case 'sprint.completed':
      handleSprintComplete(data);
      break;
  }
  
  res.status(200).send('OK');
});

Troubleshooting

Webhooks Not Firing

Checklist:

1. Is endpoint URL saved (not empty)?
2. Is URL reachable from public internet?
3. Does endpoint return 2xx status?
4. Check endpoint server logs

Wrong Data Received

Verify:

• Correct event type configured
• Payload structure matches expected
• No middleware transforming the request

Duplicate Events

Possible causes:

• Retry after timeout (but endpoint processed)
• Multiple webhooks for same event type

Solution: Implement idempotency using event UUID or timestamp.

Connection Refused

Common causes:

• Firewall blocking GitScrum IPs
• Endpoint not listening on specified port
• SSL certificate issues (for HTTPS)

Debugging:

1. Test endpoint from external source
2. Check firewall rules
3. Verify SSL certificate validity

Best Practices

Endpoint Design

Return quickly: Acknowledge receipt, process async Handle failures gracefully: Don't crash on malformed payloads Log everything: Aid debugging and audit

Event Selection

Be specific: Only subscribe to events you need Avoid redundancy: task.completed includes task.updated info Consider volume: High-activity projects generate many events

Maintenance

Monitor endpoint health: Alert on failures Test after changes: Re-verify after endpoint updates Document integrations: Record why each webhook exists

Permissions

Regular project members cannot access webhook configuration.

Rate Limits

Webhooks share project API rate limits:

• Standard: 1000 requests/hour
• Pro: 5000 requests/hour

High-volume events may hit limits. Consider batching or selective events.

Webhooks extend GitScrum's reach to any system that can receive HTTP requests. Configure thoughtfully, test thoroughly, and build the custom integrations your workflow requires.