Working with Git
π€ Generated with Claude Code
β οΈ Not yet reviewed
Co-Authored-By: Claude (noreply@anthropic.com)
How we cut repositories, name and use branches, and get a change into main.
Two neighbouring pages cover what this one deliberately leaves out: which namespace prefix a repository gets and what project types exist is in repository-conventions.md, and what happens after a merge β builds, releases, environments β is in ci-cd/.
Almost everything here is a SHOULD. The handful of MUSTs exist because breaking them costs somebody else a production incident, and they are marked as such.
The shape of itβ
Repositoriesβ
One project, one repositoryβ
A repository holds one deployable thing: one service, one application, one library, one tool. If two parts are built, versioned and released independently, they are two repositories β even when they are usually changed together.
The exception is a component and its contract package. Publishing Tis.Something.Contracts from
the same repository as the service that implements it is normal and keeps the two in step.
Namingβ
All repositories live in Azure DevOps under togethercca/tis-cca. When you create one:
- Reuse an existing prefix rather than inventing a namespace. The prefix says what kind of thing this is β see repository-conventions.md.
- Follow the casing that already dominates that prefix. Capitalisation across the organisation is historically inconsistent, and matching the neighbours beats being globally correct.
- The repository name is the pipeline name is the release name. Keeping all three identical is what makes a repository traceable to production, so pick a name you can live with.
The default branch is mainβ
New repositories MUST use main. Around 100 of the roughly 185 repositories in tis-cca
already do; about 80 still use master, among them tis.core, tis.gf.smr5 and several partner
integrations.
Those SHOULD be renamed β but not as a campaign. Rename when you are working in the repository anyway, and remember that the branch name is referenced from outside git:
| Also names the branch | Where |
|---|---|
trigger: block | azure-pipelines.yml in the repository |
| Artifact branch filter | the release definition, in the Azure DevOps UI |
| Branch policies | Project settings β Repositories β Policies |
Azure DevOps keeps a redirect for the old name, so clones and open pull requests survive the rename. The three items above do not update themselves.
Never commit secretsβ
Connection strings, API keys, certificates and passwords MUST NOT be committed β not even to a branch that is deleted afterwards, because git keeps them. Configuration references a secret in Azure Key Vault; the value itself never enters the repository.
Developers have no write access to the key vaults, so creating a secret goes through the DevOps team. Ask them β it happens rarely enough not to be a bottleneck, and it is much cheaper than the alternative. See secrets.md.
If a secret does land in a commit, rotating it is the fix. Rewriting history is not.
Branchesβ
Namingβ
| Prefix | For | Example |
|---|---|---|
features/ | new functionality β the default | features/scim-gateway-route-99754 |
bugs/ | fixing a defect | bugs/frontendstate-incomplete-save |
chores/ | maintenance with no behaviour change | chores/appinsights-cleanup |
docs/ | documentation only | docs/boa-feature-boundaries |
hotfix/ | an urgent production fix | hotfix/token-refresh-expiry |
After the prefix: kebab-case, and the work item number when there is one. German is fine where the
domain is German β features/bl_88955_erweiterung_ovb is a perfectly good branch name.
A team MAY add a prefix that fits its own repository. tis.identity uses config/* for
per-customer IdentityServer configuration (config/arisecur, config/check24), which is a better
name than forcing that work into chores/.
On the plural.
features/andfeature/are both widespread β roughly 185 against 90 at the time of writing, alongsidefeatuers/,fetures/andfesatures/. The plural forms above are the convention. Do not rename existing branches over it; just get new ones right.
When you need oneβ
| Situation | Rule |
|---|---|
| A repository only you work on | MAY commit to main directly |
| Anyone else works in the same repository | SHOULD use a branch and a pull request |
| An important, central application | MUST use a branch β main is protected |
"Important, central" means the same thing here as it does for release approvals: the applications whose breakage affects many users at once β the gateway, identity, the platform libraries that everything else depends on.
Keep them short-livedβ
A branch is a temporary workspace, not a place to live.
- SHOULD be merged within days. A branch open for weeks is a merge conflict that has not happened yet.
- SHOULD be rebased onto
mainregularly, not only at the end. - SHOULD carry one piece of work. Two unrelated changes are two branches.
- SHOULD be deleted on completion. Azure DevOps offers the checkbox in the pull request β leave it ticked.
cca-config-server is the cautionary example: customer branches last touched in 2022 and 2023 are
still sitting next to master, and nobody now knows whether they matter.
main is always prod-readyβ
Whatever is on main SHOULD be in a state that could go to production without further work.
That is what makes everything else on this page cheap: hotfixes are ordinary branches, main is
always a safe base to rebase onto, and a release becomes a decision rather than a scramble.
The corollary is that unfinished work does not go to main because the sprint is ending. It stays
on its branch, or it ships behind a switch.
Protecting mainβ
For important, central applications, main MUST be protected so that nobody can push to it
directly. Setting any branch policy in Azure DevOps does that automatically β under
Project settings β Repositories β <repository> β Policies β Branch policies.
The baseline is build validation: a pull request MUST build green before it can complete. Everything else is the team's call.
| Policy | What it does | In use today |
|---|---|---|
| Build validation | The PR build must succeed before completion | The most common policy by far |
| Minimum number of reviewers | n approvals required; the author does not count | tis.identity and api.togethercca.com require 2, the others 1 |
| Required reviewers | Named people or a group must approve | tis.identity, tis.identity.certificate.ScepEnrollmentService |
| Work item linking | The PR must reference an Azure Boards item | tis.core, tis-cca.ui.angular, tis.gf.smr5 |
| Comment requirements | All comments resolved before completion | tis.gf.smr5, cca.omdsmerge |
Only around ten repositories have any policy at all. That is not an argument for adding them everywhere β a repository one person maintains is fine without β but if your application is on the central list and has none, that is worth fixing.
Code ownershipβ
Repositories have no owner. The team owns the code, and anyone may change any repository.
That does not mean nobody knows it best. Every application has one or two main developers who carry the context, and they are who you ask for a review and who you tell before a structural change. Asking them is courtesy and good sense; waiting for them is not a requirement, and no repository should be blocked because one person is on leave.
Getting the change into mainβ
Rebase over mergeβ
Rebase. A linear history means git log on main reads as a sequence of changes rather than a
braid, and git bisect works. Before completing a pull request, rebase your branch onto main
rather than merging main into it.
Squash for small changes. Where a branch is one logical change spread over a dozen "wip", "fix typo", "actually fix it" commits, squashing MAY be the better outcome. Squash when the intermediate commits tell nobody anything; keep them when each one means something.
In the Azure DevOps completion dialog:
| Merge type | Use it |
|---|---|
| Rebase and fast-forward | The default choice |
| Squash commit | Small changes, or a branch with throwaway history |
| Semi-linear merge | Acceptable when you want a merge commit but a linear parent chain |
| Merge (no fast-forward) | Avoid β this is what produces the braided history |
Commit messagesβ
New work SHOULD use Conventional Commits:
feat(tis-secrets): add find/get commands with vault aliases
fix(benutzer): scope-abhΓ€ngiger FreshWindow-Default im ScopedCache
docs: add coordination guidance for service and contract releases
refactor(session): SessionErstellung -> SessionCreateOptions
feat(tis-secrets)!: piped output defaults to AKV references
- type β
feat,fix,docs,refactor,test,chore,build,perf - scope β optional, the area touched
!after the type marks a breaking change- subject β imperative, no trailing full stop
Tis.Hosting.Extensions, tis.identity.api and parts of boa-api already work this way. Older
repositories are full of free-form German subjects, and that history stays as it is β this applies
to what you write next, not to what is already there.
Azure DevOps prefills the merge commit with Merged PR 12345: <pull request title>, so give the
pull request a title in the same form and the convention survives the merge.
Pull requestsβ
- Describe the change, not the diff. The reviewer can read the diff; they cannot read why you chose this shape.
- Link the work item. Several repositories enforce it β do it everywhere.
- Keep them reviewable. A forty-file pull request gets an approval, not a review.
- Resolve comments rather than deleting them. The conversation is the record.
Branches, builds and deploymentsβ
The mechanics belong to ci-cd/. What matters here is how far a branch is allowed to travel.
| Target | Rule |
|---|---|
| Build | Branches trigger a build automatically. The trigger: block usually lists main, features/* and bugs/* |
| Fachtest | Non-critical applications MAY deploy branches automatically |
| Stage | By hand |
| Production | Branches SHOULD NOT be deployed, and production MUST NOT deploy automatically |
Two of those deserve spelling out.
A branch on Fachtest is temporary. Fachtest is shared. While your branch is on it, nobody else
is testing anything there and the environment no longer reflects main. Test, then merge and let a
main build take the slot back.
A branch in production is an incident, not a workflow. In genuinely exceptional cases it
happens. When it does, the branch MUST be replaced by a build from main as soon as the test
that justified it is finished β or rolled back. Production running code that exists on no permanent
branch is a state nobody can reason about afterwards.
Hotfixesβ
Because main is prod-ready, a hotfix needs no special procedure: branch from main as
hotfix/β¦, fix, review, rebase, deploy from main. The only thing that differs is the urgency,
and urgency is a reason to get a second pair of eyes on it rather than to skip them.
Branching from the deployed commit instead of main is justified only when main has moved on in
ways that cannot ship yet β which, if main is kept prod-ready, should be rare enough to be
memorable.
Where this does not applyβ
Products with several supported versionsβ
cca.omdsmerge runs a gitflow model: a protected develop, a master, and long-lived
release/9.15.0, release/9.15.3 and release/phase1 branches, each with its own policies.
tis.identity keeps releases/is/7.0.x through releases/is/7.4.x and releases/bff/3.1.x
through releases/bff/4.1.x alongside main.
That is correct, not legacy. CCA9 is installed at the customer and several versions are supported at once; an IdentityServer major version is maintained after the next one ships. When you must fix a version you are no longer developing, that version needs a branch to live on.
The test is simple: if you support more than one released version at a time, you need release
branches β and if you do not, you do not. A hosted service that only ever runs one version has no
reason to keep develop and release/* around, and trunk-based development on main is what the
rest of this page describes.
Everything that already existsβ
Nothing here is retroactive. Existing branch names, master defaults, merge commits and German
commit subjects are not defects to be cleaned up. Apply this to the next branch you create.
Checklist for a new repositoryβ
| Step | Why |
|---|---|
| Name follows an existing prefix and its dominant casing | Makes the repository findable and the pipeline traceable |
Default branch is main | The standard; avoids a rename later |
.gitignore covers build output, *.user files and local settings | Keeps noise and machine-specific paths out of diffs |
| No secrets β configuration references Key Vault, the DevOps team creates them | A committed secret has to be rotated, not deleted |
README.md says what the thing is and how to run it locally | The first question every new joiner has |
azure-pipelines.yml triggers on main, features/* and bugs/* | Branches get built, not only main |
Central application: branch policy with build validation on main | Protects main and keeps it prod-ready |
Application documentation lives here under docs/ | Hub-and-spoke β see DOCUMENTATION-GUIDELINES.md |
Relatedβ
| Topic | Where |
|---|---|
| Namespace prefixes and project types | repository-conventions.md |
| Build and release pipelines | ci-cd/ |
| API service repository layout | api-services/ |
| Reading and requesting secrets | secrets.md |
| Vaults, naming and server authentication | Infrastructure β Secrets |
| Where a document belongs | DOCUMENTATION-GUIDELINES.md in the repository root |