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β
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β
| Element | What 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: True | Produces 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@2 | Publishes 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.
ReleaseStartedmeans 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.
| Stage | Starts | Gated by |
|---|---|---|
FACHTEST | Automatically, if the team wants it that way | Usually nothing |
PROD | Always by hand | Named approvers on central applications; often nothing on smaller ones |
STAGE | By hand | Usually 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:
Manage IISWebApplicationβ creates or updates the application pool and the IIS application.Deploy IIS Website/Appβ unpacks thewebdeployzip 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 group | Used by |
|---|---|
fachtest.servicebytogether.at | FACHTEST stages |
stage.servicebytogether.at | STAGE stages |
www.servicebytogether.at | PROD 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 aresourceName:instead of a deployment group job. - Versioning moves to git tags. MinVer derives the
version from tags such as
service-v9.3.1andcontracts-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 aManualValidation@1approval, 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.ymland 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.