In the fast-paced world of agency life, managing client projects efficiently is paramount. For many development teams, the cornerstone of this efficiency lies in a well-defined Git workflow. However, we once faced a recurring nightmare: tangled branches, conflicting changes, and the frantic scramble to prepare for client demos, often leading to missed features or accidental inclusions. This chaos prompted us to forge a Git workflow specifically designed to tackle the unique demands of agency client work.

The Unique Git Predicament for Agencies

Traditional Git workflows often fall short when applied to agency projects due to several distinct characteristics:

• Variable Team Sizes: Projects can scale from a single developer to a larger team, requiring a flexible workflow.
• Unpredictable Release Cycles: Unlike internal products with fixed sprints, client deployments are often dictated by external events like trade shows or audits.
• Intense Client Feedback Loops: Continuous review, feedback, and iteration cycles demand a robust system for managing changes on staging environments.
• Urgent Hotfixes: Critical production issues can emerge at any moment, necessitating immediate deployment without disrupting ongoing feature development.
• Diverse Environments: Projects commonly involve multiple environments (development, staging, production, demo), each needing clear branch mapping.
• Seamless Developer Handoffs: Clear conventions are crucial when projects shift between team members.
• Client Visibility: Professional and transparent commit history is important, as clients may occasionally review code or branch names.

Our Solution: A Robust Three-Branch Git Strategy

After significant trial and error, we standardized on a workflow centered around three permanent branches:

• main: The Production Sentinel
  • Exclusively holds code currently live in production.
  • Highly protected, requiring strict pull request approvals for merges.
  • Each deployment is version-tagged for easy rollback and history tracking.
  • Direct commits are strictly forbidden.
• staging: The Client Review Hub
  • Contains all features deemed ready for client review and maps directly to the client-facing staging environment.
  • Serves as the bridge for features before they advance to production.
  • Can be reset or rebased under careful coordination, if necessary.
• development: The Integration Crucible
  • The primary working branch for the development team, where all feature branches first integrate.
  • May contain features not yet complete or polished enough for client eyes.
  • Maps to our internal development environment.

All active development takes place in temporary Feature Branches, adhering to clear naming conventions:

• feature/[short-description]: For new functionalities.
• bugfix/[short-description]: For resolving bugs identified during development.
• hotfix/[short-description]: For urgent fixes to production issues.
• chore/[short-description]: For refactoring, updates, and maintenance.

The Workflow in Action: From Feature to Production

Our code’s journey from concept to live deployment follows a predictable path:

1. Developers create a feature branch directly from development.
2. Once a feature is complete and reviewed, it merges into development.
3. When a set of features is ready for client review, development merges into staging, which is then deployed to the client review environment.
4. Upon client approval, staging merges into main, triggering a production deployment and a version tag.

Rapid Response: The Hotfix Protocol

For critical production issues, a hotfix branch is created directly from main. After the fix, it merges back into main for immediate deployment. Crucially, this hotfix is then backported to staging and development to ensure consistency across all environments.

Evolving with Feedback: Client Review Iterations

Client feedback on features in staging leads to a dedicated feedback branch, created from staging. Once changes are made and approved, this branch merges back into staging for re-review, and eventually follows the standard path to main.

Best Practices and Hard-Earned Wisdom

Our experience has taught us invaluable lessons, translated into these practical guidelines:

• Keep Feature Branches Lean and Agile: Aim for short-lived branches (days, not weeks) to prevent merge conflicts. Break down large features, merge frequently to development, and use feature flags for incomplete functionalities.
• Preserve History: Avoid Force Pushes: Never force push to shared branches (main, staging, development), as it rewrites history and creates chaos. A rare exception is a coordinated reset of staging.
• Synchronize Before You Contribute: Always pull the latest changes from your base branch before pushing your own work to resolve conflicts locally.
• Craft Professional Commit Messages: Write clear, descriptive, and client-appropriate commit messages. They serve as a crucial historical record.
• Maintain a Tidy Repository: Branch Cleanup: Delete feature branches promptly after they are merged to keep the repository clean and avoid confusion.
• Version Control Discipline: Tagging Releases: Tag every production deployment with a version number (e.g., v1.2.0) for easy reference and potential rollbacks.

Navigating Complex Scenarios

Our workflow adeptly handles common agency challenges:

• Multiple Features in Development: Developers work on parallel feature branches, all integrating into development. Features move to staging only when ready for client eyes.
• Deploying Select Features: When only specific features are approved, feature flags are preferred over complex cherry-picking or temporary release branches, offering cleaner control.
• Staging Bugs and Urgent Hotfixes: Dedicated branches for these issues ensure rapid resolution and proper propagation across all environments.

Empowering the Workflow with Tools

To streamline our process, we leverage:

• Pull Request Templates: Ensure consistent information and adherence to review standards.
• Branch Protection Rules: Enforce rigorous requirements for merges to critical branches (like requiring reviews for main).
• Automated Deployments (CI/CD): Ensure branches and environments stay synchronized, automating deployments to development, staging, and production on respective branch pushes.
• Git Aliases: Custom shortcuts for common, complex Git commands, boosting developer efficiency.

Tailoring the Workflow to Your Agency

While this workflow serves us well, its strength lies in its adaptability. Smaller projects might simplify by merging directly to staging. Larger teams might introduce more stringent review processes. The core principles, however, remain universal:

• A clear, logical mapping between branches and deployment environments.
• A commitment to short-lived, manageable feature branches.
• Rigorous protection of your production codebase.
• The capability for swift and seamless production hotfixes.
• A consistently professional and trackable commit history.

The Bottom Line

The quest for the ideal Git workflow isn’t about blindly following a theoretical model; it’s about crafting a system that genuinely supports your team’s operational realities. For agencies navigating unpredictable client demands, a robust workflow is not a luxury but a necessity. Our three-branch system, complemented by disciplined practices, has transformed our development process, eliminating the “Friday afternoon scramble” and allowing our team to focus on innovation rather than wrestling with version control.

The best workflow is ultimately the one that prevents disasters, provides clarity, and empowers your team to deliver exceptional software with confidence.