How To Use

Follow these steps to set up Git Board Flow in your repository:

• Create a PAT

  Define a personal access token to interact with issues, pull requests and boards.

• Configure Branch Structure

  Set up your repository's branch structure:

  • Primary Branch: Default is master (or main for newer repositories)
  • Development Branch: Default is develop

  You can customize these branch names in the configuration. These branches will serve as the foundation for your development workflow, where feature, bugfix, hotfix, release, docs and chore branches will be created from and merged back into.

• Set Up Required Labels

  Configure the following essential labels in your repository:

  • Type Labels: For categorizing issues (e.g., feature, enhancement, bug, bugfix, hotfix, release, docs, documentation, chore, maintenance)
  • Action Labels: For performing different actions (e.g., branched, deploy, deployed)
  • Priority Labels: For issue prioritization (e.g., priority: high, priority: medium, priority: low)
  • Size Labels: For control task sizes (e.g., size: XS, size: S, size: M, size: L, size: XL, size: XXL)

  These labels will be used by the action to automate workflows and organize your tasks effectively.

• Implement Issue Templates

  Create issue templates to standardize task creation (in .github/ISSUE_TEMPLATE/):

  • Feature: feature_request.yml — use labels such as enhancement, feature; add branched when the user should get a branch, or set branch-management-always: true.
  • Bugfix: bug_report.yml — use labels bug, bugfix; add branched if needed.
  • Docs: doc_update.yml — use labels documentation, docs.
  • Chore / maintenance: chore_task.yml — use labels chore, maintenance.
  • Hotfix: hotfix.yml — use labels hotfix, branched (branch is created from main at latest tag).
  • Release: release.yml — use labels release, branched (branch is created from develop).
  • Help: help_request.yml — for support requests (no branch). Include the labels that match the labels table so the action creates the correct branches and applies the right workflow.
• Install Git Board Flow

  Add the GitHub Action to your repository by creating three workflow files (you can choose any names; common choices are gbf_commit.yml, gbf_issue.yml, gbf_pr.yml or names like "Git Board Flow - Commit", etc.):

  1. Push (commit) — runs on push to any branch: notifies issues of new commits, updates size and progress labels. Create e.g. .github/workflows/gbf_commit.yml.
  2. Issues — runs on issues (opened, edited, labeled, unlabeled): creates branches, links to projects, assignees. Create e.g. .github/workflows/gbf_issue.yml.
  3. Pull requests — runs on pull_request: links PR to issue, project, reviewers. Create e.g. .github/workflows/gbf_pr.yml. See the README for full YAML examples. These workflows will then automatically manage branches, project boards, and the relationship between issues and code.