Overview#

Twenty years ago, Git emerged as a version control system (VCS) to facilitate teamwork and track changes in a version history. Nowadays, Git is an essential tool for software developers, especially for those working in a team. Complementing Git, platforms like GitHub provide hosting for Git repositories, enabling collaboration and sharing.

In this post, I will show you how to setup a production-ready Git & GitHub workflow for your project. As you may know, this article is a part of the Flutter Ship series, which guides you in shipping a production-ready Flutter app. However, these principles can be applied to any language or framework.

By the end of this article, you will learn the following:

1. How to implement a simple but effective branching strategy.
2. How to adopt a commit message standard for a clean history and automated changelogs.
3. How to automatically generate and manage project changelogs.
4. How to use Git hooks to automate local checks, like formating & linting files, linting commits, and running tests.
5. How to implement a GitHub PR Checks with GitHub Actions to automate your workflow.

If this sounds like what you’re looking for, let’s dive in!

Branch Strategy#

A clear branching strategy is essential for any software project to prevent the chaos of direct commits to the main branch. Working directly on main can lead to frequent merge conflicts, broken builds, and lost code, especially in a team setting.

The solution is to use short-lived branches for every new piece of work, whether it’s a feature, bugfix, or chore. While there are many branching strategies, I recommend a strategy based on the popular and straightforward GitHub Flow. It’s simple to understand, promotes continuous delivery, and works exceptionally well for most projects.

The core idea is illustrated below:

Branch Types Explained

• Main Branch (main): This is the stable branch that always reflects the latest production-ready state of your project. All releases and deployments are made from here.
• Feature branches (feature-* or task-id-*): Used for developing new features, enhancements, bug fixings or tasks. If you use a task management tool (like Jira), you can integrate with it and name your branch after the task or ticket ID (e.g., ab-123-add-login). Each feature/task branch is short-lived and merged back into main via a pull request after review and testing.

This model also supports different development environments with ease. When you complete a feature or task, you open a pull request (PR). You can configure a GitHub Action (or any other CI/CD service) to run tests and automate the generation of APKs for Android and IPAs for iOS, and distribute them to testers or users via your chosen platforms. I’ll cover Flutter Continuous Delivery (CD) in detail in a future article.

Git & Github Cheat Sheet

I assume you already know the basics of Git and GitHub, so I won’t include basic Git commands here. If you need a refresher, check out my Git & GitHub Cheatsheet article.

Git Merge Recommendation

If you merge branches locally, merge --no-ff is highly recommended. The --no-ff flag causes the merge to always create a new commit object, even if the merge could be performed with a fast-forward. This avoids losing information about the historical existence of a feature branch and groups all commits that together added the feature.

Commit Messages#

Commit messages are your working history. While the probability of reading them is low, they are still valuable for maintaining a good commit history and understanding changes later on. At least once in a while, you need to read the history to get more details about an emerging issue. Furthermore, in most software projects, the changelog will be generated based on those commit messages to show the release changes between versions. So what could you find or generate if you have the following history?

1
* 4dcd0dc fix color
2
* 1e0acd7 fix issue
3
* 897cab6 Merge branch 'add-comment'
4
|\
5
| * 7b2c3f3 integration
6
|/
7
* 3d0b48d add feature
8
* 7287225 updated
9
* 1405829 update post
10
* dba0ea9 add post

To have team-level agreed standards for git commit messages, I highly recommend following Conventional Commits.

1
<type>[optional scope]: <description>
2

3
[optional body]
4

5
[optional footer(s)]

Check out the following example that uses conventional commit messages, which are much easier to understand and allow you to easily generate changelogs:

1
* 4dcd0dc Update themeColor fixed property to true
2
* 1e0acd7 fix(comment): Update check script to include biome CI
3
* 897cab6 Merge branch 'add-comment'
4
|\
5
| * 7b2c3f3 feat(comment): Integrate Giscus for comments and add styles
6
|/
7
* 8cbd821 fix(dependencies): Update astro and biome versions in pnpm-lock.yaml
8
* 3d0b48d feat: Add support for rendering mermaid codes in the markdown files
9
* 7287225 ci: Update code quality job
10
* 1405829 refactor(post): Update muslim data post and released
11
* dba0ea9 feat(post): Add the first draft of muslim data post
12
* 31a1ef8 build: Remove astro compress

Commit Structure

I highly recommend you to read the Conventional Commits documentation to get more information about the commit structure like type, scope, description, body, fotter, and breaking changes.

1
// ...existing settings
2

3
"github.copilot.chat.commitMessageGeneration.instructions": [
4
  {
5
    "text": "Generate a commit message that MUST follow the Conventional Commits format (feat, fix, docs, style, refactor, test, perf, build, ci, chore, revert). Include a brief description of the change in the subject line (under 72 characters) and a summarized explanation in the body, if necessary. Separate the subject and body with a blank line. Example: 'feat(auth): Add forgot password functionality to the login screen' or 'fix(products): Fix date format in the product list'."
6
  }
7
]
8

9
// ...existing settings

Changelog#

A CHANGELOG.md is a way to tell your consumers what has changed between versions. One of the most effective ways to do this is to generate it based on your git commit messages, which contain all your change history. There are many tools for generating changelogs, but one of my favorite tools is Git Cliff, which is a highly customizable changelog generator. It only takes three simple steps from installation to generation, as explained below:

1
brew install git-cliff

1
git-cliff --init

1
git-cliff -o CHANGELOG.md

1
[changelog]
2
# template for the changelog header
3
header = """
4
# Changelog\n
5
All notable changes to this project will be documented in this file.\n
6
"""
7

8
# template for the changelog footer
9
footer = """
10
<!-- generated by git-cliff -->
11
"""

1
[git]
2
# parse the commits based on https://www.conventionalcommits.org
3
conventional_commits = true
4
# filter out the commits that are not conventional
5
filter_unconventional = true
6
# process each line of a commit as an individual commit
7
split_commits = false

1
# regex for parsing and grouping commits
2
commit_parsers = [                                            # Group Ordering
3
  { message = "^feat", group = "<!-- 0 -->🚀 Features" },     # 0
4
  { message = "^fix", group = "<!-- 1 -->🐛 Bug Fixes" },     # 1
5
  { message = "^doc", group = "<!-- 3 -->📚 Documentation" }, # 3
6
  { message = "^perf", group = "<!-- 4 -->⚡ Performance" },   # 4
7
  { message = "^refactor", group = "<!-- 2 -->🚜 Refactor" }, # 2 <- ordered to 2
8
  { message = "^style", group = "<!-- 5 -->🎨 Styling" },
9
  { message = "^test", group = "<!-- 6 -->🧪 Testing" },
10
  # ...
11
]

1
# regex for parsing and grouping commits
2
commit_parsers = [
3
  # ...
4
  { message = "^perf", group = "<!-- 4 -->⚡ Performance" },
5
  { message = "^refactor", group = "<!-- 2 -->🚜 Refactor" },
6
  { message = "^style", group = "<!-- 5 -->🎨 Styling" },
7
  { message = "^test", group = "<!-- 6 -->🧪 Testing" },
8
  { message = "^chore\\(release\\)", skip = true }, # <-- skipped group
9
  # ...
10
]

1
# Organize commits within sections by oldest or newest order
2
sort_commits = "oldest"

Git Hooks#

Git hooks are scripts that automatically execute before or after specific Git actions, like committing, pushing, or merging. They allow you to customize Git’s behavior, automate tasks, enforce policies, and streamline your workflow. read more

We can take advantage of Git hooks to automate the following tasks:

1. pre-commit: Before a commit is created.
   • Apply dart fix to automatically fix issues.
   • Apply dart format to reformat staged files.
   • Run the Flutter linter to check for analysis issues.
2. commit-msg: After a commit message is written, but before the commit is created.
   • Validate the commit message to ensure it follows the Conventional Commits standard.
3. pre-push: Before pushing code to a remote repository.
   • Run all Flutter tests to prevent pushing broken code.

Keep Git Hooks Fast and Reliable

Regarding the pre-push hook, if you have a large test suite that makes your git push command too slow, you can skip this hook and set up a PR check in your CI/CD pipeline as an alternative.

1
pre-commit:
2
  parallel: true
3
  commands:
4
    auto-fix:
5
      run: dart fix --apply && git add {staged_files}
6
    pretty:
7
      glob: '*.dart'
8
      run: dart format {staged_files} && git add {staged_files}
9
    linter:
10
      run: flutter analyze {staged_files} --no-fatal-infos --no-fatal-warnings
11

10 collapsed lines
12
commit-msg:
13
  commands:
14
    validate:
15
      run: 'scripts/validate_commit_msg.sh'
16

17
pre-push:
18
  parallel: true
19
  commands:
20
    tests:
21
      run: flutter test

1
#!/bin/bash
2

3
# Path to the commit message file
4
COMMIT_MSG_FILE=".git/COMMIT_EDITMSG"
5

6
# Check if the commit message file exists
7
if [ ! -f "$COMMIT_MSG_FILE" ]; then
8
  echo "Commit message file does not exist."
9
  exit 1
10
fi
11

12
# Read the commit message
13
COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
14

15
# Define the Conventional Commits regex pattern
16
PATTERN='^(feat|fix|build|chore|ci|docs|style|refactor|perf|test)(\([^)]*\))?(!)?: .+'
17

18
# Validate the commit message
19
if [[ "$COMMIT_MSG" =~ $PATTERN ]]; then
20
  echo "👍 Valid commit message!"
21
  exit 0
22
else
23
  echo "👎 Invalid commit message format."
24
  echo "Commit message should follow the Conventional Commits format."
25
  exit 1
26
fi

1
chmod +x scripts/validate_commit_msg.sh

10 collapsed lines
1
pre-commit:
2
  parallel: true
3
  commands:
4
    auto-fix:
5
      run: dart fix --apply && git add {staged_files}
6
    pretty:
7
      glob: '*.dart'
8
      run: dart format {staged_files} && git add {staged_files}
9
    linter:
10
      run: flutter analyze {staged_files} --no-fatal-infos --no-fatal-warnings
11

12
commit-msg:
13
  commands:
14
    validate:
15
      run: 'scripts/validate_commit_msg.sh'
16

5 collapsed lines
17
pre-push:
18
  parallel: true
19
  commands:
20
    tests:
21
      run: flutter test

15 collapsed lines
1
pre-commit:
2
  parallel: true
3
  commands:
4
    auto-fix:
5
      run: dart fix --apply && git add {staged_files}
6
    pretty:
7
      glob: '*.dart'
8
      run: dart format {staged_files} && git add {staged_files}
9
    linter:
10
      run: flutter analyze {staged_files} --no-fatal-infos --no-fatal-warnings
11

12
commit-msg:
13
  commands:
14
    validate:
15
      run: 'scripts/validate_commit_msg.sh'
16

17
pre-push:
18
  parallel: true
19
  commands:
20
    tests:
21
      run: flutter test

GitHub PR Checks#

In this section, we won’t do a deep dive into CI/CD, as we have already planned a dedicated article for it. Instead, we will set up a basic but essential GitHub Actions workflow to automatically analyze and test our code whenever a pull request (PR) is opened against the main branch.

GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. You can create workflows that build and test every pull request to your repository, or deploy merged pull requests to production. read more

TIP

If you are new to CI/CD, I highly recommend reading the GitHub Actions documentation to get familiar with the core concepts.

1
name: Flutter PR CI
2

3
# This workflow runs on pull requests targeting the main branch.
4
on:
5
  pull_request:
6
    branches:
7
      - main
8

9
jobs:
10
  analyze_and_test:
11
    name: Analyze & Test
12
    runs-on: ubuntu-latest
13
    steps:
14
      # 1. Check out the repository code
15
      - name: Checkout code
16
        uses: actions/checkout@v4
17

18
      # 2. Set up the Flutter environment
19
      - name: Set up Flutter
20
        uses: subosito/flutter-action@v2
21
        with:
22
          # Use the Flutter version from pubspec.yaml
23
          flutter-version-file: pubspec.yaml
24
          # Enable caching for faster builds
25
          cache: true
26

27
      # 3. Install project dependencies
28
      - name: Install dependencies
29
        run: flutter pub get
30

31
      # 4. Run static analysis to check for code quality
32
      - name: Analyze code
33
        run: flutter analyze --no-fatal-infos --no-fatal-warnings
34

35
      # 5. Run all tests to ensure the PR is stable
36
      - name: Run tests
37
        run: flutter test

1
version: 2
2
updates:
3
  - package-ecosystem: "pub"
4
    directory: "/"
5
    schedule:
6
      interval: "weekly"
7
      day: "sunday"
8
      time: "00:00"
9
      timezone: "Asia/Baghdad"
10
    labels:
11
      - "dependencies"

Source Code#

To see all the concepts from this article implemented in a real Flutter project, check out the Simple Todo App repository. Switch to the 01-git-github-workflow branch to see all in action.

1
# Clone and explore the implementation
2
git clone https://github.com/kosratdev/simple_todo.git
3
cd simple_todo
4
git checkout 01-git-github-workflow
5

6
# Install Lefthook and see the hooks in action
7
lefthook install

This repository serves as a practical reference for implementing everything we covered in this article. Feel free to fork it and use it as a starting point for your own Flutter projects!

We’ve covered a lot of ground in this article, from establishing a solid branching strategy to automating our entire workflow. By implementing GitHub Flow, Conventional Commits, automated changelogs with Git Cliff, local quality checks with Lefthook, and a basic CI pipeline with GitHub Actions, you’ve built a robust foundation for any Flutter project.

This setup isn’t just about following rules; it’s about creating a predictable, high-quality, and efficient development process. It ensures that every piece of code is consistent, tested, and ready for collaboration, freeing you up to focus on what matters most: building great features.

This is just the beginning of our journey. In the next article of the Flutter Ship series, we’ll take this foundation and build upon it by setting up different flavors for different environments.

I hope this guide has been helpful. If you have any questions, suggestions, or want to share your own workflow tips, please leave a comment below.

Happy coding!🚀