Since its inception, Thirdbridge has used a self-hosted version of GitLab to manage the vast majority of its Git repositories. This approach has served us well until now, but it’s becoming increasingly limiting and hinders our ability to integrate various services into our DevOps workflows. Therefore, we’ve decided to migrate all our active projects to GitHub during this quarter. Furthermore, we’ve chosen to manage our organization using Terraform.

Most developers enthusiastically welcomed the move to GitHub, but were much more skeptical about the use of Terraform. This text serves both as an internal memo and a public article to share the reasoning behind this decision.

The Mistakes of the Past

Our GitLab instance currently holds 233 Git repositories created over the years, featuring a bewildering variety of configurations:

• Naming conventions: PascalCase, snake_case, kebab-case… every style is represented.

• Main branches: dev, main, master, develop… something for everyone.

• Merge strategies: merge commit, rebase, squash… our Git trees are more diverse than the Amazon rainforest.

• And more: minimum number of reviewers, branch protection rules, etc.

We don’t have particularly strong opinions on these choices (except for rebase, clearly the superior approach ). The real problem is the lack of consistency: in general, the specific choice matters less than having a coherent and unified approach. Thanks to Terraform, we can preserve our chosen configurations over time for each new project — without depending on human discipline!

<img src="https://s3.ca-central-1.amazonaws.com/assets.prod.thirdbridge.ca/blog_images/terraform-base-repo.png" alt="Responsive Image" style="width: 95vw; max-width: 95%; height: auto; display: block; margin: 0px auto;" media="(max-width: 768px)" onload="this.style.width='95vw'; this.style.maxWidth='95%';">

The Good Shepherd

An overly rigid structure creates friction, harms the developer experience, and ultimately slows down innovation and productivity. Using Terraform allows us to strike a valuable balance between structure and freedom.

By default, all new GitHub repositories inherit the same baseline configurations, predefined by our team. But without guardrails, chaos inevitably creeps in. One simple solution would be to lock these configurations and forbid any changes. While this would be effective in maintaining order, it would be too rigid and bring the negative side effects mentioned earlier.

Whether it’s for temporarily testing a feature or making emergency adjustments, we believe some team members should have elevated permissions to make changes when necessary. The problem is that temporary changes often become permanent… simply because we forget to revert them.

Our solution: periodically reapply the Terraform configuration to guide strayed repositories back onto the right path. With GitHub Actions, this automation is straightforward and effective! And if a specific configuration truly needs to become permanent, it only takes a change in Terraform. Bonus: this modification — along with its justification — will be recorded in the Git history of the Terraform project, preserving a clear and lasting trace of why the change was made.

<img src="https://s3.ca-central-1.amazonaws.com/assets.prod.thirdbridge.ca/blog_images/terraform-repos.png" alt="Responsive Image" style="width: 95vw; max-width: 95%; height: auto; display: block; margin: 0px auto;" media="(max-width: 768px)" onload="this.style.width='95vw'; this.style.maxWidth='95%';">

Better safe than sorry

Trying to anticipate all future needs is often a futile exercise. A better approach is to create a structure that makes changes easy. Another advantage of using Terraform is the ability to apply large-scale changes across all repositories quickly and efficiently.

To that end, we’ve defined a base repository used as a template for the creation of every new project.

Conclusion

Entropy always wins! No matter how rigorous and careful we are, chaos eventually sets in. That doesn’t mean we should surrender — rather, we must implement systems and processes that help us maintain an acceptable level of order, while leaving enough flexibility to foster innovation. This reality applies to many domains — and in the case of Git, we believe Terraform enables us to achieve that delicate balance.

We’re confident that our next 233 Git repositories will be far better structured than the first 233!

Note: Of course, this is a hyperbole — around 16,000 tree species have been recorded so far in the Amazon rainforest.

https://en.wikipedia.org/wiki/Amazon_rainforest