Zum Hauptinhalt springen

Build and Release Pipelines

πŸ€– Generated with Claude Code

⚠️ Not yet reviewed

Co-Authored-By: Claude (noreply@anthropic.com)

How a change gets from your branch onto a server at Together.

Almost everything we run follows the same two-part shape: a build pipeline that lives in your repository as azure-pipelines.yml, and a release pipeline that lives only in the Azure DevOps web interface. The build produces an artifact; the release takes that artifact and puts it on an on-premises IIS server.

The single most surprising thing for a new joiner is the split itself. Reading the YAML in the repository tells you how the code is compiled and packaged, and nothing at all about where it is deployed. That half is clicked together in the UI and is not version-controlled.

What happens when you merge​

Build and release flow

The build pipeline​

Where it lives​

At the root of the repository, as azure-pipelines.yml β€” a few repositories use the .yaml spelling or keep it under pipelines/. It is normal source code: reviewed in pull requests, versioned with the change it builds.

Most build pipelines declare their steps at the top level, without any stages: block. This is the shape to start from:

trigger:
branches:
include:
- main
- "features/*"
- "bugs/*"

variables:
BuildConfiguration: "Release"
versionMajor: 0
versionMinor: 6

pool:
vmImage: ubuntu-latest

name: $(VersionMajor).$(VersionMinor).$(Year:yy)$(DayOfYear)$(rev:.rr)

steps:
- task: UseDotNet@2
inputs:
packageType: "sdk"
version: "10.0.x"

- task: DotNetCoreCLI@2
displayName: Restore nuget packages
inputs:
command: "restore"
projects: "**/*.csproj"
feedsToUse: "select"
vstsFeed: "f4d35a70-3e50-4b2d-bad9-69fba8d091d7"

- task: DotNetCoreCLI@2
displayName: Build solution
inputs:
command: "build"
arguments: "--configuration $(BuildConfiguration) /property:Version=$(Build.BuildNumber)"

- task: DotNetCoreCLI@2
displayName: Create WebDeploy Package
inputs:
command: publish
publishWebProjects: true
arguments: "--configuration $(BuildConfiguration) --no-build --output $(Build.ArtifactStagingDirectory)/webdeploy"
zipAfterPublish: True

- publish: "$(Build.ArtifactStagingDirectory)/webdeploy"
displayName: Publish Webdeploy Artifact
artifact: "webdeploy"

That follows tis.gf.wgp closely, which is a fair representative of the majority β€” the one deliberate difference is the agent pool, discussed below.

Which agent to build on​

New pipelines SHOULD use a Microsoft-hosted agent β€” vmImage: ubuntu-latest. Hosted agents are patched and maintained for us, give every build a clean machine, and do not queue behind our own build server. Moving builds off our own hardware is the direction we want.

Building on Linux and deploying to IIS is not a contradiction: the WebDeploy zip is just an archive, and the Windows-side release tasks unpack it. Tis.Hosting.ApiGateway, tis.pdftransformer.api, tis.bestand.omdsexplorer and tis.hosting.shell already build on ubuntu-latest and deploy to IIS this way.

vmImage: windows-latest MAY be used when a step genuinely needs Windows. A self-hosted pool SHOULD be used only when the build needs something reachable only from our network.

You will nonetheless see pool: name: default in most existing pipelines β€” 43 of them at the time of writing, against 12 on hosted agents. That is the self-hosted Default pool: four agents on our own build server, shared by everyone, so builds queue behind each other at busy times. It is legacy, not the recommendation. Switching an existing pipeline is usually a one-line change worth making.

The parts worth knowing​

ElementWhat it means
pool:See above β€” vmImage: ubuntu-latest for anything new.
trigger:Usually main plus the working-branch prefixes features/* and bugs/*, so feature branches get built too.
name:The build number, not the assembly version. $(rev:.rr) is a counter that resets each day, giving numbers like 0.6.25234.03.
vstsFeed:Our internal Azure Artifacts feed tis-cca. The GUID is the same in nearly every pipeline; it is the feed, not the project.
zipAfterPublish: TrueProduces a WebDeploy package β€” a zip the IIS deployment tasks understand. This is why the release side can stay generic.
artifact: "webdeploy"The artifact name. The release pipeline refers to it by this name, so changing it breaks the release.
PublishSymbols@2Publishes PDBs to the Azure DevOps symbol server so production stack traces can be resolved. Only a handful of pipelines do this today; it is worth adding when you touch one.

The release pipelines depend on the webdeploy artifact name, so it SHOULD be kept unless you are also editing the release definition.

The release pipeline​

Find it under Pipelines β†’ Releases in Azure DevOps, not under Pipelines β†’ Pipelines. Classic release pipelines are a separate, older feature with its own editor.

A release definition has three parts.

An artifact link. It points at the build pipeline and takes the Latest version by default. A Continuous deployment trigger on that link means every successful build automatically creates a release. Creating a release is not the same as deploying it β€” see the stages below.

Stages, almost always named FACHTEST, PROD and STAGE. Despite the ordering in the editor, they are independent of one another; each has its own trigger condition and its own approvals.

Two separate switches govern a stage, and it is worth keeping them apart:

  • What starts it β€” the trigger condition. ReleaseStarted means the stage runs as soon as a release is created; an empty condition means somebody has to start it in the UI.
  • What gates it β€” the pre-deploy approval. Either automated, or a list of named people who must approve before the deployment runs.
StageStartsGated by
FACHTESTAutomatically, if the team wants it that wayUsually nothing
PRODAlways by handNamed approvers on central applications; often nothing on smaller ones
STAGEBy handUsually nothing; being retired, and not every pipeline still has it

PROD MUST NOT start automatically. Every production deployment is begun deliberately by a person. That is a rule, not a default.

Whether FACHTEST deploys automatically is the development team's own decision. Automatic is what we usually want, and most pipelines are set up that way, but choosing a manual start for your application is perfectly legitimate.

Named approvers on PROD are our standard for important, central applications β€” the ones whose releases affect many users at once. More specialised applications with a smaller user base frequently have no approver configured, and that is fine. Look at what your own definition does rather than assuming either way.

None of this is a step towards fully automated delivery. The intended workflow is that a developer oversees the deployment and then tests the application manually afterwards. The automation exists to remove the tedious and error-prone parts of shipping, not to remove the person watching it happen.

Deployment jobs. The work itself is a deployment group job, which runs on the servers registered in a deployment group rather than on a build agent.

A new release definition SHOULD use the shared task group. A task group is a named, reusable block of steps maintained once and referenced from many release pipelines β€” Ensure Web Application And Deploy $(AppPoolName) is the one to reach for. It ensures the application pool and IIS application exist and then deploys the webdeploy package, parameterised so the same block serves every application. Because it is shared, a fix or an improvement reaches every pipeline that uses it, and new releases get the settings right without anyone re-deriving them.

Underneath, it performs two tasks:

  1. Manage IISWebApplication β€” creates or updates the application pool and the IIS application.
  2. Deploy IIS Website/App β€” unpacks the webdeploy zip into the application's folder.

Many existing definitions β€” generally the older ones β€” add those two tasks directly instead of using the task group. That still works, and there is no need to rush a migration, but it means each pipeline carries its own copy of settings that then drift apart. An old definition MAY be switched over when you are editing it anyway.

Not everything is a web application. tis.gf.abgleich, for example, uses Create or Update scheduled Task to install a nightly job instead of deploying to IIS.

Where the code lands​

A stage picks its target machines by tag within a deployment group:

Deployment groupUsed by
fachtest.servicebytogether.atFACHTEST stages
stage.servicebytogether.atSTAGE stages
www.servicebytogether.atPROD stages

The deployed application ends up under D:\deployed-webapps\ on the target server, served by IIS under a virtual path matching the application name.

You MUST NOT infer a stage's environment from the host name. Numbering such as tisapp03 versus tisapp003 reflects hardware-renewal history β€” names are swapped between the two forms as servers migrate β€” not Prod versus Fachtest. The tags in use are inconsistent besides: some FACHTEST stages are tagged tisapp03, some TISAPP003, and casing varies. What actually selects the machine is the combination of deployment group and tag on the job, so read those two together.

Details about the servers and agents themselves β€” what runs where, how machines are registered β€” belong to Infrastructure rather than here.

Finding your own pipeline​

Everything lives in the togethercca/tis-cca project.

  • Builds: https://dev.azure.com/togethercca/tis-cca/_build
  • Releases: https://dev.azure.com/togethercca/tis-cca/_release

To trace a repository through to production: open the build pipeline with the same name as your repository, then open Releases and look for a release definition of that name. Its artifact tab confirms which build it consumes. A handful of components have their own Azure DevOps project β€” kundenportal is the notable one β€” so if a name is missing from tis-cca, check there.

Beware of definitions prefixed OLD_ or archive_. There are many, and they are not in use.

Common variations​

Frontends built in the same pipeline. Angular applications are built with NodeTool@0 and Npm@1 tasks before the .NET build, and the compiled output is published as part of the same WebDeploy package. tis.gf.wgp, tis.bestand.bestandsuebersicht and tis.mandanten.vermittlerweb3 do this, for example.

Frontends built in their own pipeline. Other repositories keep the client separate, with a second YAML file and a second build definition β€” tis.gf.smr5 has webclient-azure-pipeline.yml alongside its azure-pipelines.yml, and tis.volltextsuche splits into api-pipeline.yml and webclient-pipeline.yml. If a repository seems to have no frontend build, look for a second pipeline file before concluding it is missing.

Contract packages. Repositories that publish shared contracts add a pack step and a NuGetCommand@2 push to the internal tis-cca feed, so consumers can reference them.

Multiple artifacts. A pipeline may publish several artifacts from one build β€” a web application, a console tool, configuration files β€” and let different release stages consume different ones.

For how a service repository is laid out around all this, see api-services/project-structure.md.

Future: releases in YAML​

The split described above is our current default, not our target. Four repositories β€” tis.identity.api, tis.identity, boa-api and api.togethercca.com β€” already do everything in one multi-stage YAML file, with no classic release pipeline at all.

What that changes:

  • Deployment becomes reviewable. Stages, approvals and IIS settings sit in the repository and go through pull requests like any other change.
  • Environments replace deployment groups. Stages use environment: with a resourceName: instead of a deployment group job.
  • Versioning moves to git tags. MinVer derives the version from tags such as service-v9.3.1 and contracts-v…, rather than from a build-number counter.
  • A pre path allows testing before the switch. The stage deploys to a parallel application (tis.identity.api-pre), runs integration tests against it on the machine itself, waits for a ManualValidation@1 approval, and only then deploys to the live application. The classic pipelines have no equivalent.
  • Steps become templates. Repeated deployment logic moves into .azure-pipelines/templates/deploy-iis.yml and is referenced per stage.

Shared pipeline templates are being built. Today those templates are copied between repositories rather than shared, so a fix in one does not reach the others. The tis-cca.pipeline-templates repository exists to solve that, gathering the steps every pipeline repeats β€” building and packaging, deploying to IIS, running integration tests. The intent is that creating a pipeline becomes referencing a template and supplying a handful of parameters, instead of copying a neighbouring repository's YAML and adjusting it.

It is work in progress and not ready to be used. It MUST NOT be referenced from your pipeline yet. This page will say so when that changes.

Treat this as the direction of travel. If you are adding a pipeline to an existing repository today, the two-part build-and-release setup is still what fits the surrounding infrastructure.