Zum Hauptinhalt springen

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​

Branch lifecycle

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 branchWhere
trigger: blockazure-pipelines.yml in the repository
Artifact branch filterthe release definition, in the Azure DevOps UI
Branch policiesProject 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​

PrefixForExample
features/new functionality β€” the defaultfeatures/scim-gateway-route-99754
bugs/fixing a defectbugs/frontendstate-incomplete-save
chores/maintenance with no behaviour changechores/appinsights-cleanup
docs/documentation onlydocs/boa-feature-boundaries
hotfix/an urgent production fixhotfix/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/ and feature/ are both widespread β€” roughly 185 against 90 at the time of writing, alongside featuers/, fetures/ and fesatures/. The plural forms above are the convention. Do not rename existing branches over it; just get new ones right.

When you need one​

SituationRule
A repository only you work onMAY commit to main directly
Anyone else works in the same repositorySHOULD use a branch and a pull request
An important, central applicationMUST 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 main regularly, 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.

PolicyWhat it doesIn use today
Build validationThe PR build must succeed before completionThe most common policy by far
Minimum number of reviewersn approvals required; the author does not counttis.identity and api.togethercca.com require 2, the others 1
Required reviewersNamed people or a group must approvetis.identity, tis.identity.certificate.ScepEnrollmentService
Work item linkingThe PR must reference an Azure Boards itemtis.core, tis-cca.ui.angular, tis.gf.smr5
Comment requirementsAll comments resolved before completiontis.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 typeUse it
Rebase and fast-forwardThe default choice
Squash commitSmall changes, or a branch with throwaway history
Semi-linear mergeAcceptable 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.

TargetRule
BuildBranches trigger a build automatically. The trigger: block usually lists main, features/* and bugs/*
FachtestNon-critical applications MAY deploy branches automatically
StageBy hand
ProductionBranches 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​

StepWhy
Name follows an existing prefix and its dominant casingMakes the repository findable and the pipeline traceable
Default branch is mainThe standard; avoids a rename later
.gitignore covers build output, *.user files and local settingsKeeps noise and machine-specific paths out of diffs
No secrets β€” configuration references Key Vault, the DevOps team creates themA committed secret has to be rotated, not deleted
README.md says what the thing is and how to run it locallyThe 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 mainProtects main and keeps it prod-ready
Application documentation lives here under docs/Hub-and-spoke β€” see DOCUMENTATION-GUIDELINES.md
TopicWhere
Namespace prefixes and project typesrepository-conventions.md
Build and release pipelinesci-cd/
API service repository layoutapi-services/
Reading and requesting secretssecrets.md
Vaults, naming and server authenticationInfrastructure β†’ Secrets
Where a document belongsDOCUMENTATION-GUIDELINES.md in the repository root