first version of the knowledge base :)

20 - Knowledge/devops/git-workflows.md

@@ -0,0 +1,111 @@
+---
+title: Git Workflows
+description: Practical Git workflow patterns for teams and personal infrastructure repositories
+tags:
+  - git
+  - devops
+  - workflow
+category: devops
+created: 2026-03-14
+updated: 2026-03-14
+---
+
+# Git Workflows
+
+## Introduction
+
+A Git workflow defines how changes move from local work to reviewed and deployable history. The right workflow keeps collaboration predictable without adding unnecessary ceremony.
+
+## Purpose
+
+This document covers the most common workflow choices for:
+
+- Application repositories
+- Infrastructure-as-code repositories
+- Self-hosted service configuration
+
+## Architecture Overview
+
+A Git workflow usually combines:
+
+- Branching strategy
+- Review policy
+- Merge policy
+- Release or deployment trigger
+
+The two patterns most teams evaluate first are:
+
+- Trunk-based development with short-lived branches
+- Feature branches with pull or merge requests
+
+## Common Workflow Patterns
+
+### Trunk-based with short-lived branches
+
+Changes are kept small and integrated frequently into the default branch. This works well for active teams, automated test pipelines, and repositories that benefit from continuous deployment.
+
+### Longer-lived feature branches
+
+This can be useful for larger changes or teams with less frequent integration, but it increases drift and merge complexity.
+
+### Infrastructure repositories
+
+For IaC and self-hosting repos, prefer small reviewed changes with strong defaults:
+
+- Protected main branch
+- Required checks before merge
+- Clear rollback path
+- Commit messages that explain operational impact
+
+## Configuration Example
+
+Example daily workflow:
+
+```bash
+git switch main
+git pull --ff-only
+git switch -c feature/update-grafana
+git add .
+git commit -m "Update Grafana image and alert rules"
+git push -u origin feature/update-grafana
+```
+
+Before merge:
+
+```bash
+git fetch origin
+git rebase origin/main
+```
+
+## Troubleshooting Tips
+
+### Merge conflicts happen constantly
+
+- Reduce branch lifetime
+- Split large changes into smaller reviewable commits
+- Rebase or merge from the default branch more frequently
+
+### History becomes hard to audit
+
+- Use meaningful commit messages
+- Avoid mixing unrelated infrastructure and application changes in one commit
+- Document the operational reason for risky changes in the pull request
+
+### Reverts are painful
+
+- Keep commits cohesive
+- Avoid squash-merging unrelated fixes together
+- Ensure deployments can be tied back to a specific Git revision
+
+## Best Practices
+
+- Prefer short-lived branches and small pull requests
+- Protect the default branch and require review for shared repos
+- Use fast-forward pulls locally to avoid accidental merge noise
+- Keep configuration and deployment code in Git, not in ad hoc host edits
+- Align the Git workflow with deployment automation instead of treating them as separate processes
+
+## References
+
+- [Git: `gitworkflows`](https://git-scm.com/docs/gitworkflows)
+- [Pro Git: Branching workflows](https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows)