A 14-person AI agency in Denver lost an entire Friday because two engineers pushed conflicting model pipeline changes to main, breaking the staging environment for their largest client. The rollback took six hours. The client demo scheduled for Monday had to be postponed. The account manager spent the weekend writing apology emails instead of preparing the quarterly business review that was supposed to expand the contract by forty percent.
The root cause was not incompetence. Both engineers were talented. The root cause was that the agency had no agreed-upon git workflow. Everyone committed directly to main. Nobody used pull requests consistently. Branch naming was a free-for-all. And the result was a delivery process that worked fine at five people but collapsed at fourteen.
If your AI agency is growing beyond a handful of engineers, git workflow standards are not optional. They are the backbone of predictable delivery.
Why AI Agency Work Creates Unique Git Challenges
Standard software development already benefits from structured git workflows. But AI agency work adds layers of complexity that make disciplined version control even more critical.
Model artifacts and data pipelines sit alongside application code. Your repositories are not just application logic. They contain training scripts, evaluation notebooks, configuration files for model serving, and sometimes large data processing pipelines. A casual merge can silently change model behavior without anyone noticing until the client reports degraded performance in production.
Multiple client projects run simultaneously. Unlike a product company with one codebase, your team juggles five, ten, or twenty repositories at once. Without standards, each project develops its own conventions, making it harder for engineers to context-switch between clients.
Client environments have different deployment constraints. One client runs on AWS, another on Azure, a third on-premise. Your branching strategy needs to accommodate environment-specific configurations without creating a mess of long-lived branches that diverge beyond repair.
Turnover and subcontractors are common. Agency teams shift. When a new engineer picks up a project mid-stream, clear git history and branch conventions are the difference between a productive first day and a week of archaeology.
The Branch Strategy That Works for Most AI Agencies
After watching dozens of agencies struggle with overly complex branching models, the pattern that works best for most teams is a simplified trunk-based approach with short-lived feature branches.
Here is the structure:
- main is always deployable. Nothing merges to main without passing CI checks and at least one code review.
- Feature branches are created for every unit of work, whether that is a bug fix, a new model endpoint, or a pipeline change. They live for hours or days, not weeks.
- Release branches are optional and only used when a client requires a formal release process with staging, UAT, and production gates.
- Hotfix branches branch from main and merge back to main, with the fix cherry-picked to any active release branch.
Why not Gitflow? Gitflow was designed for products with scheduled releases. Agency work is typically continuous delivery or client-triggered deployments. The overhead of maintaining develop, release, and hotfix branches in parallel creates more confusion than value for most agency teams.
Why not pure trunk-based with no branches? Because AI agencies need the review step. When you are shipping to a client's production environment, you cannot afford to skip the pull request. The review is your safety net.
Branch Naming Conventions That Scale
Naming branches consistently sounds trivial until you have forty open branches across eight projects and nobody can find anything.
Adopt a convention and enforce it:
- feature/CLIENT-TICKET-short-description for new work. Example: feature/ACME-142-add-sentiment-endpoint
- fix/CLIENT-TICKET-short-description for bug fixes. Example: fix/ACME-157-null-response-handling
- hotfix/CLIENT-TICKET-short-description for production emergencies
- chore/CLIENT-TICKET-short-description for non-functional changes like dependency updates or CI configuration
The CLIENT prefix matters in an agency context. When an engineer runs git branch and sees twenty branches, the client prefix immediately tells them which project each branch belongs to, even in a monorepo or shared-services repository.
Enforce it with a pre-commit hook or CI check. Do not rely on memory or good intentions. A simple regex validation in your CI pipeline rejects branches that do not match the pattern. This costs five minutes to set up and saves hours of confusion over the life of a project.
Pull Request Standards That Protect Delivery Quality
The pull request is where quality happens in an agency workflow. Treat it as a first-class operational process, not a checkbox.
Every PR needs a description that answers three questions:
- What does this change do?
- Why is this change needed?
- How should the reviewer test it?
For AI-specific work, add a fourth question: What is the expected impact on model behavior or data pipeline output? This forces the author to think about downstream effects before the reviewer even opens the diff.
Set minimum review requirements by project risk level:
- Standard projects: One approving review from a team member
- High-stakes projects: Two approving reviews, one from a senior engineer or tech lead
- Production model changes: Two reviews plus a passing evaluation suite before merge
Require CI to pass before merge. This is non-negotiable. If your CI pipeline runs linting, type checking, unit tests, and integration tests, no PR should merge with a red build. The moment you make exceptions, the exceptions become the norm.
Set a maximum PR size. Large PRs do not get reviewed well. Aim for PRs under 400 lines of changed code. If a feature requires more, break it into sequential PRs that each represent a logical unit of work. This also makes rollbacks cleaner when something goes wrong.
Commit Message Standards for Client-Facing Work
Commit messages are documentation. In an agency, they are documentation that might be read by a client's technical team during a handoff, an audit, or a troubleshooting session.
Adopt conventional commits or a similar structured format:
- feat: for new features
- fix: for bug fixes
- refactor: for code restructuring without behavior change
- test: for test additions or modifications
- docs: for documentation updates
- chore: for maintenance tasks
Each commit message should have a short summary line under 72 characters, followed by a blank line and a longer description if needed.
Bad commit message: "fixed stuff"
Good commit message: "fix: resolve null pointer in sentiment pipeline when input text is empty"
The good message tells anyone reading the git log exactly what happened and why, without opening the diff. When a client's CTO is reviewing your delivery six months later, this professionalism compounds into trust.
Protecting Production With Branch Protection Rules
Branch protection rules are your insurance policy against human error. Configure them on every client repository.
For the main branch, require:
- Pull request reviews before merging (at least one, preferably two for critical projects)
- Status checks to pass (CI pipeline must be green)
- Up-to-date branches (the feature branch must be rebased or merged with the latest main before merging)
- No force pushes (this prevents history rewriting that can mask problems)
- No direct commits (everything goes through a PR)
For release branches, if you use them:
- Same protections as main
- Additional requirement for QA sign-off or a specific label indicating client approval
These rules should be configured in your git hosting platform (GitHub, GitLab, Bitbucket) at the organization level so they apply to every new repository by default. Do not rely on individual project leads to remember to set them up.
Handling Client-Specific Configurations Without Branch Sprawl
One of the most common git messes in agencies is long-lived branches for different client environments. You end up with branches like client-a-production, client-b-staging, client-a-on-prem, and they diverge from main until merging becomes a nightmare.
The better approach is environment configuration files, not branches.
Keep environment-specific settings in configuration files or environment variables:
- Use .env files (excluded from the repository) for secrets
- Use configuration files per environment (config/production.yaml, config/staging.yaml) for non-secret settings
- Use feature flags for behavior that varies between clients
This way, main contains all the code, and the deployment pipeline selects the appropriate configuration based on the target environment. No long-lived branches required.
For truly divergent client customizations, consider whether the work belongs in a shared repository at all. If client A needs a fundamentally different model architecture than client B, those might be separate repositories or separate packages in a monorepo, not branches of the same project.
Code Review Culture in an Agency Context
Code reviews in an agency are not just about code quality. They are about knowledge distribution, risk management, and maintaining delivery speed when people are unavailable.
Establish review turnaround expectations. In most agencies, a 4-hour review turnaround during business hours is reasonable. If reviews sit for days, developers start stacking work on top of unmerged branches, creating dependency chains that are painful to untangle.
Rotate reviewers intentionally. Do not let the same person review all PRs for a project. Rotation ensures multiple people understand the codebase, which protects you when someone goes on vacation, gets sick, or leaves the agency.
Use review checklists for AI-specific concerns:
- Are model evaluation metrics included or referenced?
- Are data pipeline changes backward compatible?
- Are new dependencies justified and properly pinned?
- Are configuration changes documented?
- Are there any hardcoded values that should be environment variables?
Make reviews a learning opportunity, not a gatekeeping exercise. Comments should explain the why behind suggestions. Junior engineers should feel comfortable asking questions in review comments. This builds the team's collective skill level, which is one of the few durable competitive advantages an agency has.
CI/CD Pipeline Standards for Agency Repositories
Your git workflow is only as good as the automation supporting it. Every agency repository should have a CI pipeline that runs automatically on every push and every PR.
Minimum CI pipeline stages:
- Lint and format check. Catches style inconsistencies before they become review noise.
- Type checking. For TypeScript or Python with type hints, this catches a class of bugs that unit tests often miss.
- Unit tests. Fast, isolated tests that verify individual components.
- Integration tests. Tests that verify components work together, especially critical for data pipelines and API endpoints.
- Security scanning. Automated dependency vulnerability checks and secret detection.
For AI-specific projects, add:
- Model evaluation. Run a subset of your evaluation suite on every PR that touches model code or training configuration.
- Data validation. Verify that pipeline changes produce output in the expected schema and within expected value ranges.
- Performance benchmarks. Track inference latency and throughput to catch regressions before they reach production.
Keep CI fast. If your pipeline takes more than fifteen minutes, engineers will start finding ways to skip it. Optimize by running stages in parallel, caching dependencies, and using targeted test execution that only runs tests related to changed files.
Handling Secrets and Credentials in Agency Repositories
AI agency work involves API keys, model hosting credentials, client database connections, and cloud provider tokens. Mishandling these in git is a security incident waiting to happen.
Rules that should be non-negotiable:
- Never commit secrets to a repository, not even temporarily. Git history is permanent unless you take extreme measures to rewrite it.
- Use a .gitignore template that excludes .env files, credential files, and common secret patterns.
- Run a pre-commit hook that scans for potential secrets before allowing a commit. Tools like git-secrets or detect-secrets catch most accidental exposures.
- Store secrets in a dedicated secret management system (AWS Secrets Manager, HashiCorp Vault, or even a shared 1Password vault for smaller teams).
- Rotate any secret that is accidentally committed, even if you immediately remove it. Assume it has been compromised.
For client credentials specifically, establish a clear chain of custody. Document who has access to each client's credentials, where they are stored, and when they were last rotated. This is both a security practice and a client trust builder.
Onboarding New Engineers to Your Git Standards
Having standards is useless if new team members do not follow them. Build git workflow onboarding into your agency's engineering onboarding process.
Create a one-page git workflow guide that covers your branch naming convention, PR process, commit message format, and CI requirements. Keep it in a shared documentation system, not buried in a repository that new engineers might not find.
Pair new engineers with a buddy for their first few PRs. The buddy reviews their branches, commit messages, and PR descriptions, providing feedback on workflow adherence alongside code quality.
Automate what you can. Use PR templates that pre-fill the description format. Use branch naming validation in CI. Use commit message linting. The more you automate, the less you need to teach and the less you need to correct.
Review your standards quarterly. As your team grows and your client base evolves, some standards will need updating. A quarterly review ensures your workflow stays practical rather than becoming legacy process that everyone ignores.
Measuring Git Workflow Health
You cannot improve what you do not measure. Track a few key metrics to assess whether your git workflow is helping or hindering delivery.
- PR cycle time: How long from PR creation to merge? Increasing cycle time often signals review bottlenecks or PRs that are too large.
- PR size distribution: Are most PRs under 400 lines? A skew toward large PRs indicates that work is not being broken down effectively.
- CI failure rate: What percentage of CI runs fail? A high rate might mean tests are flaky or the pipeline is too strict for the team's current discipline level.
- Hotfix frequency: How often are you creating hotfix branches? Frequent hotfixes suggest that the review and CI process is not catching issues before they reach production.
- Mean time to recovery: When something does break in production, how quickly can you identify the problematic commit and roll back or fix it? Clean git history and small PRs make this faster.
Review these metrics monthly as a team. Not to assign blame, but to identify systemic improvements that make everyone's work smoother.
Your Next Step
If you do not have a documented git workflow today, start with the three highest-impact changes:
First, enable branch protection on main for every client repository. Require at least one review and passing CI before merge. This single change prevents the most common delivery incidents.
Second, adopt a branch naming convention and enforce it with a CI check. This takes thirty minutes to set up and immediately makes your repository navigation cleaner.
Third, create a PR template that prompts for a description, testing notes, and AI-specific impact assessment. This raises the quality of every review without requiring any cultural change.
You do not need to implement every practice in this post at once. Start with protection, naming, and templates. Then layer in commit standards, review checklists, and metrics tracking as your team matures. The goal is not perfection on day one. The goal is a workflow that makes reliable delivery the default, not the exception.