Best Practices for Using Git with Kanban Boards

Want to streamline your development process? Combining Git with Kanban boards can help you track tasks, link code changes directly to progress, and improve team collaboration. Here’s a quick summary of how to make it work:

• Sync Git and Kanban: Use Git actions (like branch creation or commits) to automatically update Kanban cards.
• Organized Branch Naming: Match branch names to Kanban tasks (e.g., feature/CARD-123-new-feature).
• Automate Updates: Use Git hooks to move cards across Kanban stages (e.g., "In Progress" to "Review").
• Clear Commit Messages: Include task IDs (e.g., CARD-123: Add login feature) for better traceability.
• Use Tools: Platforms like GitHub Projects or GitLab Boards simplify Git-Kanban integration.

Matching Git Workflow to Kanban Steps

Linking Git Branches to Board Columns

Aligning Git branches with Kanban columns helps streamline your workflow. Here’s a suggested structure:

Kanban Column	Git Branch Type	Naming Pattern	Purpose
To Do	Feature Branch	feature/CARD-123	New features waiting for development
In Progress	Working Branch	wip/CARD-123	Work actively being developed
Review	Review Branch	review/CARD-123	Code ready for peer review
Done	Main/Release	main/release-v2.3	Completed, verified work

When a card moves from "To Do" to "In Progress", developers should create and switch to the corresponding working branch.

Effective Commit Message Systems

Clear commit messages are essential for tracking progress and keeping Kanban cards updated. Here’s a simple system to follow:

• Start with the Kanban card ID.
• Use present-tense action verbs like "Add", "Fix", or "Update."
• Provide a brief description of the change.

Example format:

CARD-123: Add user authentication system
- Implement OAuth2 flow
- Create login/logout endpoints
- Add session management

Including phrases like Fixes CARD-123 in commit messages can automatically update the associated Kanban card.

Branch Naming Rules

Stick to consistent branch naming conventions that directly connect branches to Kanban cards. Use this format:

<type>/<card-id>-<description>

Examples:

• feature/CARD-456-user-profiles
• bugfix/CARD-789-login-timeout
• hotfix/CARD-234-security-patch

Keep branch names lowercase and use hyphens instead of spaces.

For features involving multiple cards, create a parent branch:

feature/PROJECT-123-payment-system
  ├── feature/CARD-457-stripe-integration
  └── feature/CARD-458-payment-ui

This structure allows parallel work on related tasks. Once branches are merged, update the Kanban card to reflect progress.

This setup also lays the groundwork for automating transitions between Kanban stages using Git hooks. Up next: how to use Git hooks for automating updates.

Related video from YouTube

Git Hooks for Automatic Kanban Updates

Streamline your development workflow by using Git hooks to automatically update Kanban cards. This ensures your Kanban board stays in sync with your development progress without manual intervention.

Git Hook Configuration Steps

1. Create a post-commit hook

Go to your repository’s .git/hooks directory and create a file named post-commit:

#!/bin/bash
BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD)
CARD_ID=$(echo $BRANCH_NAME | grep -oE 'CARD-[0-9]+')
COMMIT_MSG=$(git log -1 --pretty=%B)

if [[ ! -z "$CARD_ID" ]]; then
    curl -X POST "your-kanban-api/cards/$CARD_ID/move" \
    -H "Content-Type: application/json" \
    -d '{"status": "in_progress"}'
fi

2. Set up a pre-push hook

Create a pre-push hook to ensure branch names follow the required format for linking to Kanban cards:

#!/bin/bash
BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD)
if [[ ! $BRANCH_NAME =~ ^(feature|bugfix|hotfix)/CARD-[0-9]+ ]]; then
    echo "Error: Branch must match type/CARD-XXX"
    exit 1
fi

Make these hooks executable by running chmod +x on the files.

Auto-Moving Kanban Cards

Once the hooks are set up, Git actions can automatically trigger updates on your Kanban board:

Git Action	Kanban Update	Trigger
Branch Creation	Move to "In Progress"	post-checkout hook
Pull Request	Move to "Review"	GitHub/GitLab webhook
Merge to Main	Move to "Done"	post-merge hook

For example, you can create a post-merge hook to handle updates when changes are merged into the main branch:

#!/bin/bash
if [[ $(git rev-parse --abbrev-ref HEAD) == "main" ]]; then
    CARD_ID=$(git log -1 --pretty=%B | grep -oE 'CARD-[0-9]+')
    curl -X POST "your-kanban-api/cards/$CARD_ID/complete"
fi

This ensures that Kanban cards reflect the completion of tasks as soon as they are merged.

Error Management

To prevent disruptions, integrate error handling into your hooks. This includes logging errors, retrying failed operations, and notifying the team about persistent issues:

#!/bin/bash
# Error handling function
handle_error() {
    local exit_code=$1
    local error_message=$2

    if [ $exit_code -ne 0 ]; then
        echo "Error: $error_message"
        echo "$(date '+%Y-%m-%d %H:%M:%S') - $error_message" >> hook-errors.log
        curl -X POST "your-notification-endpoint" -d "message=$error_message"
        exit $exit_code
    fi
}

# Use in hooks
API_RESPONSE=$(curl -s "your-kanban-api/cards/$CARD_ID")
handle_error $? "Failed to update Kanban card $CARD_ID"

To ensure recovery from failures:

• Save unsuccessful operations in a local queue file.
• Use a retry mechanism with exponential backoff to reattempt failed updates.
• Set up monitoring to notify the team about recurring issues.
• Keep an audit log of all automation attempts to track changes and debug problems effectively.

These steps will help maintain a reliable and efficient automated workflow.

sbb-itb-608da6a

Pull Request and Kanban Workflow Connection

Auto-Creating Cards from PRs

You can set up a webhook to automatically create Kanban cards whenever a pull request (PR) is opened. Here’s an example webhook configuration:

{
    "name": "web",
    "active": true,
    "events": ["pull_request"],
    "config": {
        "url": "https://your-kanban-api/webhooks/github",
        "content_type": "json"
    }
}

With the webhook in place, use the PR payload to generate a Kanban card. The card can include details like the title, description, assignee, branch name, and initial status:

function createKanbanCard(payload) {
    const card = {
        title: payload.pull_request.title,
        description: payload.pull_request.body,
        assignee: payload.pull_request.assignee,
        branch: payload.pull_request.head.ref,
        status: "Review"
    };
    return kanbanAPI.createCard(card);
}

PR Status and Card Position

The connection between PR statuses and Kanban columns ensures a smooth workflow. Here’s how you can map them:

PR Status	Kanban Column	Automated Actions
Draft	In Progress	Move card to the "In Progress" column
Open	Review	Add reviewer labels, notify the team
Changes Requested	Revisions	Move card to the "Revisions" column
Approved	Ready to Merge	Add an approval checkmark
Merged	Done	Archive the card and update workflow metrics

To automate these updates, integrate your CI/CD pipeline. For example, when a PR is approved, the Kanban card can be updated automatically:

on:
    pull_request_review:
        types: [submitted]

jobs:
    update_kanban:
        if: github.event.review.state == 'approved'
        runs-on: ubuntu-latest
        steps:
            - name: Update Kanban Card
              run: |
                  curl -X PATCH "your-kanban-api/cards/${CARD_ID}" \
                  -d '{"status": "Ready to Merge"}'

This setup ensures that PR statuses are always in sync with your Kanban board, streamlining your workflow.

Code Review Guidelines

Before a code review begins, ensure that the following areas are checked: code style, test coverage, documentation, performance, and security.

During the review process, you can integrate comments directly into your Kanban system. For instance:

async function addReviewComment(comment, cardId) {
    const subtask = {
        type: "review_comment",
        content: comment.body,
        location: `${comment.path}:${comment.line}`,
        status: "pending"
    };
    await kanbanAPI.addSubtask(cardId, subtask);
}

Before moving a card to the "Done" column, ensure these criteria are met:

• All review comments have been addressed
• CI/CD pipeline has passed successfully
• Documentation is updated
• Release notes are prepared
• Deployment has been verified

This approach keeps your workflow organized and ensures quality at every step.

Git-Kanban Integration Software Options

When it comes to connecting Git with Kanban workflows, a few software solutions stand out.

Top Integration Tools

These tools simplify workflows and reduce errors by combining Git and Kanban functionalities. Two popular choices are GitHub Projects and GitLab Boards.

Tool	Features
GitHub Projects	Seamless Git integration, automated workflows to streamline development
GitLab Boards	Built-in CI/CD tools, efficient issue tracking for better collaboration

Key Features to Look For

The right integration tool should include:

• Real-time task tracking: Keep tabs on progress and access analytics instantly.
• Ease of updates: Ensure users can submit updates without hassle.
• Responsive support: Fast help when issues arise.

These features are crucial for keeping your team efficient and minimizing disruptions.

How to Choose the Right Tool

When selecting a Git-Kanban integration tool, consider these factors:

• Team Size
  Smaller teams can stick with straightforward tools, while larger teams might need advanced features for scalability.
• Workflow Complexity
  If your workflow involves complex branching or detailed task tracking, opt for tools that can handle those needs.
• Compatibility
  Ensure the tool works well with your current software and systems to avoid integration headaches.
• Cost
  Factor in all expenses, including licensing, setup, training, and maintenance. A free trial can help determine if the tool meets your needs.

Conclusion: Improving Workflow with Git and Kanban

Combining Git with Kanban boards makes development more efficient and improves team collaboration.

Key Principles

To successfully integrate Git with Kanban, focus on these three principles:

• Organized Branch Management: Match branch names to Kanban card titles, ensuring a clear link between tasks and code changes.
• Automated Updates: Use Git hooks or tools to automatically update Kanban boards when changes happen in the code.
• Consistent Communication: Use standardized commit messages to clearly show task progress and updates.

How to Get Started

Follow these steps to bring Git and Kanban together in your workflow:

1. Set Up Your Integration Tools

Pick a tool that works for your team. For example, if you’re using GitHub Projects, enable GitHub Actions to sync repository activities with your Kanban board.

2. Create a Branch Naming System

Use a naming convention that connects branches to specific Kanban cards. Examples include:

feature/KAN-123-user-authentication
bugfix/KAN-456-login-error

3. Automate Board Updates

Set up triggers to move Kanban cards automatically based on Git actions:

• Creating a branch → Move the card to "In Progress"
• Opening a pull request → Move the card to "Review"
• Merging code → Move the card to "Done"

These steps make your workflow smoother and help your team stay aligned while working efficiently.

Related Blog Posts

• Git Mirroring vs. Other Network Solutions
• Best Practices for Large-Scale Repositories
• Custom API Integration: Git and Jira
• Asana-GitHub Integration: Step-by-Step Guide