Creating a Git workflow for collaborative Ansible development
Creating a Git workflow for collaborative Ansible development gives infrastructure teams a dependable path from a local playbook edit to a tested production change. It also creates an audit trail showing who changed what, why it changed, and which tests passed before deployment.
A practical workflow should suit Australian teams operating across Sydney, Melbourne, Brisbane and Perth, where time-zone differences make scheduling awkward. The goal is to remove ambiguity without burying contributors in process, especially when automation budgets are approved in Australian dollars and changes must satisfy internal governance.
| Approach | How changes move | Best suited to | Main consideration |
|---|---|---|---|
| Trunk-based development | Small, short-lived branches merge continuously | Experienced teams seeking rapid feedback | Requires strong automated testing |
| Feature-branch pull requests | Each change receives review before merging | Most Ansible teams | Branches must remain focused and short-lived |
| Release branches | Maintenance branches are created for supported versions | Products with formal release cycles | Adds branch-management overhead |
Build a repository teams can navigate
Start with a clear repository structure. Keep playbooks, roles, inventory templates, group variables, documentation and CI configuration in predictable locations. Smaller teams can maintain one repository, while mature collections or reusable roles often work better as separate projects with an orchestration repository tying them together through pinned dependencies.
Treat the main branch as deployable and stable. Keep production credentials, generated inventories and machine-specific data outside version control, but retain templates that explain the expected structure. Record supporting packages in requirements.yml so another engineer can reproduce the environment rather than guessing which collections and versions were used. For practitioner context behind the project, about Jonathan Frappier outlines the author’s infrastructure background.
Standardise branches and commits
Protect the main branch and require changes to arrive through reviewed pull requests. Use descriptive branch names such as feature/ACME-142-update-monitoring or fix/ansible-core-compatibility; they connect work to a ticket and reveal its purpose without opening the branch itself.
Commits should describe one logical alteration and explain the reason behind it. Messages such as fix(role): retain service state during upgrades provide more value than changes. Rebase local work to keep the history readable, but do not rewrite branches that others have already pulled. Published history becomes valuable evidence during incident reviews and release audits.
Make reviews part of delivery
A pull request should include the objective, affected hosts, testing performed and rollback approach. Reviewers can then assess idempotence, privilege requirements, supported Ansible versions and the potential operational impact before approving a merge. Small changes receive faster, more useful reviews than broad playbook rewrites.
Add ownership rules for sensitive roles and shared variables. Automation engineers should also review changes made by platform specialists, while infrastructure owners can check whether a playbook matches the intended service state. Merging only after CI succeeds creates an objective delivery gate and prevents reviews from becoming the sole defence against faulty automation.
Separate secrets from automation code
Ansible Vault can protect sensitive values, but encrypted files still require careful password handling. Keep vault passwords and cloud credentials outside Git, provide them through the CI environment or an approved secrets manager, and restrict access according to role. Rotate credentials regularly and document which team or vault identity owns each secret.
Do not commit production inventories containing customer names, private addresses or access credentials. Store environment-specific inventory through a secured dynamic-inventory system, and use sample files to show the required variables. Production execution identities should be separate from developer accounts so a compromised workstation does not immediately grant administrative access.
Automate validation before merge
Every pull request should pass syntax checks, ansible-lint, YAML validation and an execution test. Molecule scenarios can verify role behaviour across supported operating systems, while check-mode runs identify unsupported or risky changes before they reach real infrastructure. A version matrix can test the Ansible core releases and collections supported by the organisation.
Home-lab contributors can reproduce these checks on a spare-room or garage cluster connected through Australian NBN services. For shared test media or lab storage, configuring NFS datastores on ESXi provides a practical reference. CI must use temporary credentials, retain logs as build artefacts and avoid granting runners unrestricted access to production systems.
Coordinate releases across distributed teams
Tag stable releases with semantic versions and maintain a changelog that identifies new features, fixes and required migration steps. Pin collection versions in the deployment repository so an emergency rollback does not accidentally pull a newer dependency. Release branches should exist only when the organisation supports multiple maintained versions.
Schedule release approvals around Australian public holidays, school holiday periods and regional leave. A handoff during the local arvo may suit contributors in Brisbane and Melbourne, while Perth participants can join early in the morning. Keep release notes in Australian date format, such as 14/03/2025, and store approvals in the change system to support audit and governance requirements.
Start with a small, enforceable workflow
A team can introduce the workflow with one low-risk role rather than attempting to redesign every playbook at once. Agree on branch naming, commit wording, pull-request requirements, ownership rules and merge criteria. Configure repository protection and a pull-request template so these decisions operate automatically instead of relying on memory.
Run a short team workshop, select a harmless correction, and process it through the complete path: branch, commit, CI, review, merge and release tag. Record the sequence in a concise contribution guide, then expand it to collections and infrastructure playbooks. Create the repository rules, complete the first reviewed pull request, and make that change the foundation for every future automation update.