- workflow de desenvolvimento
- Arquitetura de Software
- Projetos Pessoais
- TDD
- qualidade de software
Git Flow to GitHub Flow
Why We Don't Stick to Trunk-Based Development
A while ago I started considering opening my own tech company. I quickly realized that writing good code is not enough to sustain a business. I was missing what surrounds the software: infrastructure, cloud, and the process that takes code from my machine to production. That is how I arrived at Trunk-Based Development as a possible answer. And it was while trying to implement it that I found out the workflow I actually use is a different one: GitHub Flow. In this post I explain why I left Git Flow, why I did not stay with Trunk-Based Development, and what my routine looks like today.
Beyond Features: Why I Went Into Infrastructure and Git Workflows
I have a degree in Business Administration and IT Management, so management was never my weak spot. Software architecture was not either, since I have worked in development for years and contribute to open source projects. What I was missing was something else: the areas that never show up in application code but decide whether a product survives in production.
I started by studying cloud computing. From there, version control and Git workflows were the next piece. It was not a lack of technical confidence. It was a deliberate expansion of scope with a concrete goal: if I ever run my own startup, I need to understand not only how to build the product, but how the team ships it continuously and reliably.
That is when Trunk-Based Development came into my research. Not as a trend, but as the answer to a practical question: how do high-performing teams organize code delivery? Before getting there, though, I had to deal with what was no longer working.
Why Git Flow Stopped Making Sense in My Personal Projects
Many posts on this topic oversimplify this point. I did not leave Git Flow because I think it is bad. I left because it stopped fitting the context I was using it in.
Git Flow was created by Vincent Driessen in 2010. It has two permanent branches (master and develop) and supporting branches for features, releases, and hotfixes. It was designed for versioned software that has to support several versions in production at the same time. Driessen himself, in a note added years later to the original post, acknowledged this and started recommending simpler workflows for teams practicing continuous delivery.
How Git Flow ended up in my projects
Not through careful analysis. Through habit. When I joined the company where I work today, there was no structured Git workflow. The team was quick to integrate and ship, but it did not yet have the formal processes needed to keep a trunk always healthy.
I went looking for a fix for that specific chaos. I studied Git Flow in depth, learned its pros and cons in practice, and rolled it out at the company. For that context, it worked.
The problem with copying a workflow into another context
My mistake was bringing the same structure into my personal projects, just because it was what I already knew. There I worked alone, with the technical discipline I know I have, and Git Flow turned into process standing in my way. I wanted agility, and the develop, release, and hotfix branches created friction that no benefit justified on a one-person team.
That friction is what made me look for an alternative. The first one I found, still in the research phase, was Trunk-Based Development.
What Trunk-Based Development Is (and Why It Made Me Uneasy)
Trunk-Based Development (TBD) is a branching model in which the team collaborates on a single main branch, the trunk (usually main), and avoids long-lived branches. Paul Hammant, a reference on the subject, puts it this way: developers collaborate on code in a single branch called trunk and resist any pressure to create other long-lived development branches. Merging into the trunk at least once a day is what the community itself calls a key enabler of Continuous Integration.
DORA (DevOps Research and Assessment, now part of Google Cloud) defines three signs that TBD is healthy:
- three or fewer active branches in the repository;
- merging into the trunk at least once a day;
- no code freezes and no dedicated integration phases.
DORA's research links TBD to high-performing delivery teams. One caveat: blogs often quote figures about how many times more likely elite teams are to use TBD, but I could not find that number in DORA's primary material. So I do not repeat it. What is confirmed is the correlation: TBD is the branching practice of teams that ship more often and with less friction.
I decided to migrate with enthusiasm. But the more I read about the canonical practice, with fast integration into the trunk and minimal ceremony, the riskier it looked to me, even with tests and CI. I wanted TBD's agility, but I also wanted a formal safety layer before anything touched the main branch. And that layer, as I found out later, I already had.
The Discovery: While Implementing TBD, I Realized I Use GitHub Flow
Only when I reviewed what I was actually doing did I notice the naming mistake. I thought I was applying TBD, but what I use is GitHub Flow. The official GitHub documentation defines the workflow in six steps:
- create a branch;
- make changes;
- open a pull request;
- address review comments;
- merge the pull request;
- delete the branch.
The key point is that changes do not reach the default branch until the merge. In other words, the main branch only receives code after the pull request has been reviewed and approved.
The difference between GitHub Flow and TBD
According to a technical comparison I found during my research, the difference is not branch lifetime, since both use short-lived feature branches. It is the review requirement. GitHub Flow requires the pull request as a formal gate before integration. "Pure" TBD favors merging into the trunk quickly, with minimal ceremony. That exact detail is what resolved my unease.
GitHub's documentation treats this review as an established practice, not a formality:
"Pull request review is so valuable that some repositories require an approving review before pull requests can be merged."
In other words: review is a requirement, not a nice-to-have, before code reaches the main branch.
Compared to Git Flow, GitHub Flow also removes the multiple permanent branches. You keep one production branch and temporary feature branches, created for a single change and deleted after the merge.
I see GitHub Flow as part of the same family of continuous delivery practices as TBD, with one extra safety gear. And that gear fits my profile: I trust my technical discipline, but I prefer my code to be reviewed before it touches the trunk, even when the reviewer is me at another moment or an AI I use in the process. If you want to see how AI fits into that process, I wrote about it in my AI development workflow.
My Routine with GitHub Flow: Required PRs, Short Branches, Continuous Deployment
Today I use GitHub Flow in both personal projects and commercial client projects. In practice, that means:
- a short branch for each change;
- small, frequent pull requests;
- a main branch ready to deploy as soon as a PR is merged.
What I have not used yet: feature flags
I have not used feature flags in practice yet. They are more tied to pure TBD, as a way to handle unfinished work that has to land in the trunk before it is ready for users. Martin Fowler and Pete Hodgson describe feature toggles as a powerful technique that lets teams change system behavior without changing code.
Since in GitHub Flow a PR only goes in when the change is ready for review, I never needed to merge something unfinished. Even so, it is something I need to try to understand the implications in practice, not just in theory.
None of these practices holds up on its own, though. They depend on guardrails.
Discipline as a Prerequisite: Tests, CI, and Guardrails
The first guardrail, and the most important one for me, is something I already practiced before researching TBD or GitHub Flow: unit, integration, and regression tests on everything I write. I told that story in my TDD journey.
With the new workflow, those tests stopped being just a quality habit and became a structural part of the process. Any major mistake I make breaks the tests and automatically blocks the merge in CI, before the PR is even approved.
Beyond CI, the other guardrails are behavioral:
- Consistent branch naming, even for branches that live only a few hours.
- Small PRs, to avoid large, slow reviews.
- Fast integration, without letting work pile up outside the main branch.
As for whether this kind of workflow depends more on discipline or on team size, I would rather be clear about the limits of what I know. I do not have enough experience with large teams to speak confidently about how TBD or GitHub Flow behave at that scale. What I can say, because I live it, is that for small, disciplined teams the model works very well.
Which leads to the opposite question: when not to use it.
Trade-offs: When Git Flow Is Still the Right Choice
Acknowledging the limits of what I learned also means acknowledging that Git Flow is still excellent in some contexts. Regulated industries, such as banks and fintechs, tend to prefer more controlled workflows, with an explicit audit trail, manual approvals, and well-defined promotion environments between development, staging, and production.
Leaner workflows like TBD and GitHub Flow depend on strong automated test coverage and quick reviews. Even then, a bug that slips past the automated checks gets close to production fast. That risk profile is not always compatible with compliance requirements.
In the end, this is not a purely technical decision. It is a leadership decision. Every company has its own context, and it is up to whoever leads technically to weigh the pros and cons based on what they know about the company and the team, and then decide what makes the most sense there. The models work well, each in the right place.
Conclusion
I left Git Flow because it became friction in a context it was not built for. I went after Trunk-Based Development for its agility, and I did not stay with it because I wanted a formal review before merging. Along the way, I found out that this combination already had a name: GitHub Flow.
If you are torn between Git Flow, GitHub Flow, and Trunk-Based Development, my advice is to test them. Start with personal projects or lower-risk client work. Watch whether the workflow holds up with the discipline you and your team have today, not the discipline you wish you had.
And if, during your research, you find out, like I did, that you use a different workflow than you thought, that is fine. The workflow's name matters less than understanding why it works in your context.
References
- GitHub Docs. "GitHub flow".
- Hammant, Paul. "Trunk-Based Development". trunkbaseddevelopment.com.
- Mergify. "Trunk-Based Development vs Gitflow: Which Branching Model Actually Works?".
- Driessen, Vincent. "A successful Git branching model". nvie.com, 2010.
- Fowler, Martin; Hodgson, Pete. "Feature Toggles (aka Feature Flags)". martinfowler.com.
- DORA / Google Cloud. "Trunk-based development". dora.dev.
- DataCamp. "Git Branching Strategy: A Complete Guide".
- Mierzwa, Matheus. "Minha Jornada com TDD".
- Mierzwa, Matheus. "Meu Fluxo de Desenvolvimento com IA".