For many developers, DevOps feels like unfamiliar, overcomplicated territory filled with tangled pipelines, cloud infrastructure nuances, and containerization hysteria.

But after working in this space for many years, I’ve realized that true DevOps isn't about forcing developers to become infrastructure gurus. Instead, it rests on two foundational pillars: maximizing transparency and minimizing cognitive load.

Achieving this requires close collaboration between development, infrastructure, and DevOps roles.

Let’s look at how to organize your code, repositories, and pipelines cleanly based on the architectural reality of what you are deploying.

Core Concepts

Deployable Blocks vs. Logical Applications

You must first understand the distinction between a deployable block and a logical application.

• Deployable Block: A single, isolated technical unit that can be independently hosted or run. Examples include a single web API backend, a standalone website, a single-page application (SPA) frontend, or a native desktop app.
• Logical Application: A logical grouping of multiple deployable blocks that work together to deliver a business solution. Typically, this means a backend API combined with the frontend SPA that consumes it.

Debugging Functional Pipelines is Extremely Time-Consuming

Unlike developers, a DevOps engineer doesn't have a debugger to see exactly which line of code is executing in real time. To verify that a pipeline works, they must trigger the run and wait for it to complete.

One Repository = One Deployable Block

Sticking multiple deployable blocks into a single repository significantly complicates your DevOps configuration. This leads to bloated, conditional pipeline configurations that are frustrating to maintain.

Instead, adhere to a clean rule: one repository per deployable block. Keep your API in its own repository and your frontend in another.

One Pipeline Definition = One Pipeline

One pipeline definition file must equal exactly one single pipeline. Do not write a pipeline definition that is reused across multiple deployable blocks; doing so is highly confusing and adds considerably to the total cognitive load.

One Pipeline = One Responsibility

Do not create pipeline definitions that rely on complex stage or job conditions to handle every single phase: pull requests, builds, deployments, and infrastructure provisioning. These pipelines are incredibly difficult to maintain.

The env Identifier

As a DevOps engineer, you need to identify which environments you use and consistently apply their correct identifiers—often referred to simply as an env.

Individual environments should be lowercase (e.g., dev, test, uat, or prod) because that is how engineers naturally speak in their daily vernacular:

• "Which env has this bug?"
• "Let's deploy to dev."
• "How do we fix the bug on prod?"

Setting Up Pipelines

Pipeline Naming per Responsibility

Use this naming pattern for each pipeline:

• {Deployable block name} PR for pull requests
• {Deployable block name} BUILD for creating deployable artifacts
• {Deployable block name} RELEASE for deploying to a specific environment
• {Application name} INFRA for running IaC

Always use upper-case responsibility identifiers: PR, BUILD, RELEASE, and INFRA.

Reuse Pipeline Templates

Even though you should strictly follow the rule of having a single pipeline definition per pipeline per responsibility, the content of each definition can remain largely identical. You can achieve this by calling a reusable template across all the applications you manage.

Require the env for RELEASE and INFRA Pipelines

Both RELEASE and INFRA pipelines require a specific target environment to execute against, whereas targeting an environment makes no sense for PR and BUILD pipelines.

Identify the Correct Pipeline Set

Each deployable block has a pipeline set, but not all pipeline sets are created equal.

For backend APIs or server-side web applications, the correct pipeline set is:

• PR: Runs automatically on pull requests to execute linters, check code health, and ensure the code compiles.
• BUILD: Compiles the codebase from the chosen commit into a deployable artifact.
• RELEASE: Takes that exact same artifact and deploys it directly into an environment that you choose manually when running the pipeline.

However, for SPA-like apps (and often native desktop apps), the situation is different. Because SPAs execute directly inside the user's browser, environment targets (like backend API connection URLs) generally must be compiled directly into the client-side bundle. Creating an environment-independent build artifact makes no sense here since the configuration is hardwired into the build itself.

Therefore, you should skip a dedicated build stage. The RELEASE pipeline does not consume a pre-compiled artifact; instead, it consumes a specific git commit directly, triggers the compilation for the chosen target environment on the fly, and deploys it immediately.

Understand the INFRA Pipeline

Application IaC (Infrastructure as Code) should not live inside individual application code repositories. Instead, maintain a separate Infrastructure Repository that contains the INFRA pipeline definition. The repository and the INFRA pipeline cover an entire logical application, not a single deployable block.

From an infrastructure perspective, it is much easier to wire up resource configurations in IaC within a single, unified place. This allows you to orchestrate the database, backend hosting, subnets, and the networking elements required to establish secure communication inside a Zero-Trust environment. It makes little sense to split your IaC into separate, disconnected repositories per deployable unit (such as a separate infrastructure repository for the backend and another for the frontend).

Like the RELEASE pipeline, running the INFRA pipeline strictly requires you to choose a target environment (dev, test, prod).

Local Run Versioning

Azure DevOps assigns an organization-wide, non-sequential tracking ID to pipeline executions called a Build ID, which is a number shared across all projects and pipelines.

Instead of relying on the Build ID, use a localized, incremental Pipeline Run Number (which can be implemented using the counter function in Azure DevOps). This is a simple, whole number that strictly tracks the executions of that specific pipeline, starting from 1 and incrementing with each run. It is human-readable, sequential, and cognitively effortless to cross-reference. This pipeline run number becomes critical later.

Setting Up Pipeline Run Names, Tags, and Metadata

At the start of a pipeline run, format the run name using a consistent pattern. For brevity, let's assume our deployable block is named MyApp:

• PR pipeline: MyApp PR {PR run number}
• BUILD pipeline: MyApp BUILD {BUILD run number}
• RELEASE pipeline: MyApp RELEASE (BUILD {BUILD run number}) -> {ENV} ({RELEASE run number})
• RELEASE pipeline for SPA apps: MyApp RELEASE {RELEASE run number}
• INFRA pipeline: MyAppSuite INFRA {INFRA run number}

If your CI/CD tool allows it, expose this information within any configurable run metadata. The RELEASE pipeline naming conventions are particularly helpful for resolving a common developer complaint: "The pipeline broke something because it deployed the wrong version." (More on how to disprove this below).

DevOps-Compliant Applications

You cannot build a smooth delivery ecosystem if your applications operate as unreadable "black boxes". A piece of software must actively contribute to the clarity of the ecosystem as a whole.

The stdout Rule

From an operational perspective, your application operates in two entirely different states:

1. The Startup Phase: Everything executing before the application claims a socket from the OS and begins listening on a port.
2. The Running Phase: Everything executing after the socket is successfully opened and request processing begins.

The startup phase is critical. If your application encounters an exception here, hosting platforms will continuously spin and restart the instance in a loop. When a crash happens on startup, the runtime state of absolutely everything is unknown—including your logging libraries.

You cannot rely on logging sinks (like Application Insights or Serilog) to tell you what went wrong. If the logging provider initialization itself causes the crash, it will fail silently and leave you completely blind.

During the startup phase, write everything exclusively to standard output (stdout). A pure console log is completely bulletproof. It ensures that if a boot-up crash occurs, a DevOps engineer can immediately open the container logs or cloud log stream, read the plain-text exception, and isolate the bug instantly. Save your sophisticated external telemetry sinks for the running phase after the socket is safely open.

Configuration and secrets

Configuring your applications should never involve logging into a production server to manually edit files. That is a recipe for configuration drift and unmitigated chaos.

The Environment Variables Rule

Every application must be built to read its configuration values directly from environment variables. Only local development machines are allowed to use files for tracking configuration changes in got depository.

Cloud platforms natively expose environment variables in a highly transparent, easily adjustable UI. If you need to test a configuration change, you update the variable in the platform portal, restart the instance, and immediately see if it works.

What About Secrets?

Secrets (connection strings, API keys, etc.) are fundamentally just configuration values, but they require a Zero Trust delivery model. They absolutely do not belong in git.

To handle secrets cleanly without introducing cognitive overhead:

• Masking in Variable Groups: Use your CI/CD tool’s secure variable groups (like Azure DevOps Variable Groups marked with the lock icon). Once entered, they can never be viewed again by users, and the pipeline output will automatically mask them.

• Key Vault Reference Architecture: Have your DevOps engineer set up a central Key Vault. Use a Managed Identity for your application instance, granting it strict read-only access to the vault.

The Version Info Endpoint

Every hosted deployable block should expose a public, unauthenticated JSON endpoint at /version-info that returns a payload structured like this:

{
  "env-file": "dev",
  "env-server": "dev",
  "started": "2026-05-30 13:44:51",
  "uptime": "2d 1h 35m",
  "buildPipelineRun": 811,
  "releasePipelineRun": 875,
  "infraPipelineRun": 44,
  "buildPipelineUrl": "https://dev.azure.com/your-org/your-project/_build/results?buildId=13466",
  "releasePipelineUrl": "https://dev.azure.com/your-org/your-project/_build/results?buildId=13799",
  "infraPipelineUrl": "https://dev.azure.com/your-org/your-project/_build/results?buildId=7987",
  "sourceCommitHash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "sourceCommitBranch": "main"
}

The version-info.json File

Before diving into individual properties, let's look at how the version-info.json file behaves.

This file should live in the repository of all deployable blocks and always deploy alongside your production artifacts. The values inside the source code repository are left as empty strings or zeroes, except for env-file, which defaults to the string value local.

env-file

This property is explicitly overwritten by the RELEASE pipeline to match the target environment selected during execution.

Sometimes, developers are permitted to deploy a build directly from their local machines to lower testing environments. The presence of "env-file": "local" in an environment provides an immediate visual signal that this was a local deployment, not an automated pipeline run.

env-server

Each deployable block running in a specific environment must have a scoped environment variable named env that identifies the environment (such as test, uat, or prod). The /version-info endpoint should surface this variable's value here.

When managing a vast catalog of applications and fluid infrastructure, you aren't always in control of the underlying hostnames or DNS masks. Having the application explicitly report its active env-server value gives you immediate, definitive confirmation of the environment in which the application is actually executing.

started and uptime

These values apply primarily to server-hosted applications and are incredibly useful when diagnosing infrastructure instability or unexpected restarts.

The pipelineRun and pipelineUrl Properties

These properties expose the localized pipeline run number mentioned earlier.

Surfacing these values will save DevOps engineers thousands of headaches. When a developer claims, "The pipeline deployed the wrong version because my feature isn't working," you can easily verify the deployment status. Simply navigate to the embedded pipeline URL, check the sequence number, identify who ran it, and correlate it directly with the running application's state.

OpsBuild.net

Would you like the idea of having a complete, opinionated dev/DevOps/InfraOps environment ready?

Visit https://opsbuild.net/ and subscribe to the mailing list.