Before meeting any tool, understand the pain it removes. Once the pain is clear, every feature of GitHub Actions looks sensible instead of random.

What goes wrong with manual delivery

Writing code is only half of a developer’s job. The code must also be built (turned into something a computer can run), tested (checked for mistakes), packaged (bundled for delivery), and deployed (placed on the servers where users can reach it). When people do these jobs by hand, five troubles appear again and again.

Continuous integration and continuous delivery

Two phrases describe the cure. Continuous Integration (CI) means that every time a developer shares a change, the project is automatically built and tested, so that mistakes are caught within minutes. Continuous Delivery (CD) means that every change which passes the tests is automatically prepared and can be released with little effort. When the release itself also happens automatically, people often call it continuous deployment. Together these practices are known as CI/CD.

Why Azure is part of the story

Microsoft Azure is a cloud, a very large collection of computers, storage, networks, and ready-made services that you rent by use. Delivering software “to Azure” means placing your application onto one of these services, such as a web hosting service, a function platform, a container platform, or a Kubernetes cluster. Because Azure can be controlled entirely by software commands, it is a natural partner for an automation tool: a pipeline can create the servers, install the application, and check that everything works, without a human opening a web page.

An illustrative example

Consider a hypothetical team of eight developers who run an online ticket shop on Azure App Service. Before automation, a release took three hours of careful clicking and happened once a month. After adopting GitHub Actions, every change to the main branch is built and tested in about eight minutes, deployed first to a test copy of the site, and then, after one manager clicks an approval button, to the live site. The team now releases several times a week, and when something does break, the history shows exactly which change caused it.

GitHub Actions has a small vocabulary. Learn these words once, and every later chapter reads easily.

The words, one at a time

Where workflows live

A workflow is written in YAML, a simple text format that uses indentation to show structure. These files live in a folder named .github/workflows at the top of the repository. Because they sit beside the code, they are versioned like code: changes are reviewed, history is kept, and you can see exactly how the delivery process looked on any past day. This idea, often called pipeline as code, is one of the biggest strengths of the approach.

Events in more detail

The most common events are a push (new commits arrive on a branch), a pull request (someone proposes a change and asks others to review it), a schedule (a timer like every night at two), a manual trigger (a person clicks a button, with optional inputs), a release (a new version is published), and a workflow call (one workflow invokes another). You can narrow an event so that it fires only for certain branches, tags, or changed file paths. For instance, a workflow may run only when files under the application folder change, so that a typo fix in the documentation does not trigger a deployment.

Jobs run in parallel unless told otherwise

By default, jobs in a workflow start at the same time on separate machines. When one job needs the result of another, for example a deployment that must wait for the tests, you declare that dependency, and GitHub waits. This lets you build a shape: several test jobs run side by side, and a single deploy job begins only after all of them pass. Because each job starts on a fresh machine, files do not carry over between jobs automatically. Anything the next job needs must be passed as an artifact or stored somewhere shared, such as a container registry.

A short history explains why the pieces look the way they do.

From build servers to built-in automation

In the early 2000s, teams ran their own build servers with tools such as Jenkins, which watched for code changes and ran scripts. These servers were powerful but needed constant care: updating, patching, securing, and scaling. Later, hosted CI services such as Travis CI and CircleCI let teams rent this service. GitHub, the most popular place to host code, introduced GitHub Actions in public form in 2018, and it became generally available in November 2019. Its big idea was to place automation directly inside the place where the code and the review conversations already live, with a marketplace of shared actions so that nobody has to write every step from zero.

Microsoft acquired GitHub in 2018, and the two platforms have grown closer since. Microsoft publishes official GitHub Actions for Azure, Azure documentation shows GitHub Actions deployment as a first-class path, and several Azure services can generate a ready-made workflow file for you from their portal pages.

What GitHub Actions gives you

GitHub Actions and Azure Pipelines

Microsoft also offers Azure Pipelines, part of the Azure DevOps service, which provides a similar capability. Both are mature and can deploy to Azure. A team already deeply invested in Azure Boards, Azure Repos, and Azure Pipelines may stay there, while a team whose code is on GitHub usually finds GitHub Actions the natural choice. Chapter 17 compares them in detail. The important point for now is that this is a choice of tooling, not of destination: both can deliver the same application to the same Azure services.

What this guide covers, and what it does not

This guide focuses on the integration: how GitHub Actions authenticates to Azure, what it can deploy, and how to run it safely and well. It does not teach a programming language, and it contains no code listings. Product names, features, prices, and limits change over time, so where this book mentions specifics, treat them as guidance and confirm them in the current GitHub and Microsoft documentation before relying on them.

Three worlds meet in this integration: the GitHub platform, the machines that run the jobs, and your Azure subscription. Seeing the boundaries clearly makes security and troubleshooting much easier.

flowchart LR
  DEV["Developer"] -->|"push or pull request"| REPO["GitHub repository"]
  REPO -->|"event"| GHA["GitHub Actions service"]
  GHA -->|"assigns job"| RUN["Runner machine"]
  RUN -->|"requests identity token"| OIDC["GitHub OIDC token issuer"]
  RUN -->|"presents token"| ENTRA["Microsoft Entra ID"]
  ENTRA -->|"short lived access token"| RUN
  RUN -->|"deploys using access token"| ARM["Azure Resource Manager"]
  ARM --> APP["App Service, Functions, Container Apps, AKS"]
  RUN -->|"pushes images"| ACR["Azure Container Registry"]
  RUN -->|"reads secrets"| KV["Azure Key Vault"]
  GHA -->|"logs and status"| REPO

The components

Reading the diagram

A developer pushes code to the repository. That raises an event, and the GitHub Actions service picks the matching workflow and assigns each job to a runner. When the job needs to talk to Azure, the runner asks GitHub for a signed identity token. It presents that token to Microsoft Entra ID, which checks it against the trust rules you set up. If they match, Entra ID returns a short-lived Azure access token. With that token the runner calls Azure Resource Manager to deploy the application, pushes container images to the registry, and reads any needed secrets from Key Vault. Finally, results and logs go back to the repository so that everyone can see them.

Who owns what

The boundary matters. GitHub owns the workflow engine, the hosted runners, and the identity token issuer. You own the repository content, the workflow files, the Azure subscription, the role assignments, and the trust rules in Entra ID. If you use self-hosted runners, you also own those machines and their patching. This split of responsibility explains many security decisions later in the book: you choose what an Azure identity may do, and GitHub vouches only for who is asking.

Follow a single change from a developer’s keyboard to a running application in Azure, and notice what happens at each hand-off.

sequenceDiagram
  participant D as Developer
  participant G as GitHub
  participant R as Runner
  participant E as Entra ID
  participant A as Azure
  D->>G: Push commit to branch
  G->>G: Match event to workflow file
  G->>R: Queue job and assign runner
  R->>G: Download workflow and fetch code
  R->>R: Build and run tests
  R->>G: Upload build artifact
  R->>G: Request OIDC token for this job
  G-->>R: Signed identity token
  R->>E: Exchange token for access token
  E-->>R: Short lived Azure access token
  R->>A: Deploy package to target service
  A-->>R: Deployment result
  R->>G: Send logs and final status
  G-->>D: Show success or failure on commit

The steps in words

Build once, deploy many

One golden rule shapes good pipelines: build the package once and deploy the same package to every environment. If you rebuild for production, you are shipping something different from what you tested, even if the code is identical, because the tools, dependencies, or timing may differ. By storing the output of the first build as an artifact or a container image with a unique tag and promoting that one item through test, staging, and production, you can trust that what you checked is what you released.

A workflow is only instructions. The runner is the machine that carries them out, and the choice of runner affects speed, cost, security, and network reach.

GitHub-hosted runners

A GitHub-hosted runner is a fresh virtual machine that GitHub creates for each job and destroys afterward. Standard images come with many tools pre-installed, such as common languages, build tools, the Azure command line tool, Docker, and Git. You select the machine type by a label in the workflow, for example a recent Ubuntu Linux version, Windows Server, or macOS. Because each job gets a clean machine, there is no leftover state, and GitHub handles patching and scaling. The trade-off is that hosted runners live on the internet, not inside your private network, and a limited free allowance of run time applies, with usage beyond it billed according to your plan.

GitHub also offers larger runners with more processors and memory, for heavy builds, and some options that let hosted runners join an Azure virtual network so that they can reach private resources. Availability, plan requirements, and prices vary, so check the current documentation.

Self-hosted runners

A self-hosted runner is a machine you provide and register with GitHub. It could be a virtual machine in Azure, an on-premises server, or a container on a Kubernetes cluster. Self-hosted runners are useful when a job must reach private systems that the internet cannot see, such as a database inside a locked-down virtual network, when you need special hardware or software, or when you want to control cost on very heavy usage. The price is responsibility: you must patch them, secure them, scale them, and clean them between jobs.

Running runners on Azure

Ephemeral beats persistent

The safest self-hosted setup uses ephemeral runners: each runner takes exactly one job and is then destroyed. A persistent runner that handles many jobs may leave files, credentials, or poisoned caches behind that the next job, possibly from a different repository or a different contributor, can read. If you must use persistent runners, restrict them to trusted repositories and clean the workspace thoroughly after every job.

Choosing between them

The most important question in this whole integration is simple: how does a robot prove to Azure that it is allowed to deploy? The answer you choose decides how safe your pipeline is.

First, what is an identity in Azure?

Every request to Azure must come from someone or something that Azure can recognise. For people, this is a user account in Microsoft Entra ID (the new name for Azure Active Directory). For software, Azure uses a service principal, which is an identity for an application, and a managed identity, which is an identity that Azure creates and looks after for a resource. After Azure knows who is asking, it checks role assignments: lists that say which identity may do which actions on which resources. A role such as “Contributor” on one resource group means “may create and change things in this group, but nowhere else.”

The old way: a stored secret

For years, the usual method was to create a service principal, generate a long-lived client secret (a password for the application), and paste it into GitHub as a repository secret. The workflow read that secret at run time and used it to sign in. This works, but it has serious weaknesses. The secret is valid for months or years, so if it leaks through a log, a misconfigured workflow, a compromised developer machine, or a malicious action, an attacker can use it from anywhere until someone notices. Secrets expire, which causes surprise outages on the day they run out. And someone must remember to rotate them, repeatedly, in every repository that uses them.

Another older method was the publish profile, a downloadable file with credentials for a single web app. It is convenient but is also a long-lived secret with broad power over that app, and Microsoft documentation now increasingly recommends identity-based approaches instead. Check the current guidance for your service.

The better way: OpenID Connect (OIDC)

OpenID Connect is a standard way for one system to vouch for the identity of something to another system. With OIDC, GitHub acts as the one who vouches, and Entra ID acts as the one who trusts. Instead of storing a password, you configure a federated credential on the Azure identity. This is a trust rule that says, in effect: “Accept identity tokens issued by GitHub, but only when they say they come from this organisation, this repository, and this branch or environment.”

At run time the workflow requests a short-lived signed token from GitHub. The token contains claims, which are facts such as the repository name, the branch, the environment, and the workflow that is running. The runner sends this token to Entra ID, which checks the signature, checks that the claims match the federated credential, and then issues an Azure access token that lasts only for a short time, usually around an hour. There is nothing to leak, nothing to rotate, and nothing to expire on a quiet Sunday.

flowchart TD
  S["Workflow job starts with permission to request an identity token"] --> T["GitHub issues signed token with claims"]
  T --> C["Runner sends token to Microsoft Entra ID"]
  C --> V{"Do issuer and claims match a federated credential"}
  V -->|"Yes"| OK["Entra ID issues short lived Azure access token"]
  V -->|"No"| NO["Sign in refused and job fails"]
  OK --> USE["Deploy within the roles assigned to the identity"]
  USE --> END["Token expires and nothing remains to steal"]

Setting up OIDC, in plain steps

Choosing the subject: what the trust rule matches

The most subtle part of OIDC is deciding what the federated credential matches. The token’s subject claim has a pattern that depends on how the job was triggered, and a federated credential accepts exactly one subject value. Common choices are shown below.

Because you need one federated credential per subject, a repository that deploys to three environments usually has three credentials, ideally mapping to three separate identities with different permissions: a low-power one for test, and a more carefully guarded one for production.

Managed identities and workload identity

A user-assigned managed identity works nicely as the deployment identity, because Azure manages its lifecycle and it has no secret at all, but it can still hold federated credentials for GitHub. For the application itself, once deployed, use a managed identity so the app can reach databases and vaults without any stored password. For pipelines that run on self-hosted runners inside Azure, the runner’s own managed identity can sign in directly, though this identity is then shared by every job on that machine, which is a point of caution.

Microsoft and the community publish ready-made actions for Azure. Knowing the main ones saves you from reinventing common steps.

What an action is, and where it comes from

An action is a packaged piece of automation that a workflow step can call by name and version, for example “the Azure login action, version 2”. Actions live in public GitHub repositories (or private ones within your organisation). When a workflow runs, the runner downloads the named action and executes it. This sharing is powerful, but it also means that your pipeline runs other people’s code, a point we revisit in the security chapter.

Common Azure-related actions

Actions versus plain commands

You never have to use an action. Every deploy step can also be done by running Azure command line commands directly from a step. Actions are convenient because they hide detail, validate inputs, and give consistent logging. Commands are flexible and transparent, and they work the same on a developer laptop, which helps with troubleshooting. Many teams use a mix: actions for login and deployment, commands for custom checks.

Reusable workflows and composite actions

As the number of repositories grows, copying the same workflow text into each one becomes a maintenance nightmare. GitHub offers two ways to share. A reusable workflow is a whole workflow that other workflows can call, passing inputs and secrets, ideal for standard “build and deploy to Azure” procedures. A composite action bundles several steps into one action that can be used inside any job. A platform team can publish a small set of approved building blocks, so that product teams assemble pipelines from vetted parts and security improvements reach everyone with a single change.

Pin versions

Every use of an action names a version, such as a major version tag, a more precise tag, or a full commit identifier. A major version tag moves, so you silently receive updates, which is convenient but means that a compromised or buggy release reaches you immediately. A full commit identifier never moves, so you decide when to update. Security-minded teams pin to full commit identifiers, and let an automatic tool such as Dependabot propose upgrades for review.

Azure offers many places to run an application. Each has a different delivery path from GitHub Actions. This chapter tours the most common ones.

Azure App Service

App Service is a managed web hosting platform. You hand it a package of your web application, and Azure runs it, patches the operating system, scales it, and gives it an address. A pipeline builds the application, uploads the package as an artifact, and a deployment job signs in with OIDC and uses the web apps deployment action to publish it. App Service supports deployment slots: extra copies of the app, such as “staging,” that run alongside the live one. The pipeline deploys to the staging slot, tests it there, and then swaps the slots, which switches users to the new version almost instantly and keeps the old version one swap away for a quick rollback. Many teams enable this approach by default for production web apps.

Azure Functions

Azure Functions runs small pieces of code in response to events, such as a message arriving or a timer firing, without you managing servers. Deployment from GitHub Actions is similar to App Service: build and package, then publish using the functions action. Functions can also have slots on certain hosting plans. Because functions often connect to storage and queues using identities, make sure the deployment identity only changes the function app, while the function app’s own managed identity holds the data permissions.

Azure Container Apps

Azure Container Apps runs containers without exposing the details of Kubernetes. The pipeline builds a container image, pushes it to a registry, and then updates the container app to use the new image. Container Apps keep revisions, which are immutable snapshots of each version, and can split traffic between revisions by percentage, which supports canary releases. A new revision can receive 10 percent of traffic first, and if the health looks good, the share grows to 100 percent.

Azure Kubernetes Service (AKS)

AKS is a managed Kubernetes cluster. Kubernetes is a system that runs many containers across a group of machines, restarts them if they crash, and scales them. For AKS, the pipeline builds and pushes an image, signs in to Azure, obtains access to the cluster, and applies Kubernetes descriptions of the desired state, using manifests, Helm charts, or Kustomize overlays. Kubernetes then rolls out the change gradually, replacing old containers with new ones and stopping if health checks fail. A newer approach called GitOps flips the direction: the pipeline only updates a Git repository holding the desired state, and a tool inside the cluster, such as Flux (available as an AKS extension) or Argo CD, pulls the change in. Pull-based delivery means the pipeline never needs cluster-admin access from outside.

Azure Static Web Apps

For front-end sites built with frameworks like React, Angular, or Vue, Static Web Apps hosts the files on a global network and can attach serverless back-end functions. When you create one, Azure can add a workflow to your repository automatically. A helpful feature is the preview environment: each pull request gets its own temporary copy of the site with a unique address, so reviewers can click through the change before it merges, and the copy is deleted when the pull request closes.

Virtual machines and other targets

Some systems still run on plain virtual machines. Pipelines can deploy there with command-line tools, remote command execution, or by building machine images and rolling out scale sets. Other common targets include Azure Spring Apps and Azure SQL databases (for schema changes), API Management (for API definitions), and Azure Data Factory or Synapse (for data pipelines). The same pattern repeats: build, store an artifact, sign in with a scoped identity, deploy, and verify.

Let the portal write the first draft

Several Azure services, such as App Service and Static Web Apps, have a Deployment Center or similar page where you pick a GitHub repository and branch, and Azure creates the workflow file and the identity configuration for you. This is a very good way to learn, as long as you then review what it created, tighten the permissions, and move any old-style secrets to OIDC.

Containers are the most common way to package modern applications. Here is how a container pipeline flows from source code to a running service.

What a container image is

A container image is a sealed package holding an application together with everything it needs to run: the runtime, libraries, and settings. Wherever the image runs, it behaves the same. A registry is a warehouse for images, and Azure Container Registry (ACR) is Azure’s private registry. Each image has a name, plus a tag such as a version label and an immutable digest, a fingerprint computed from its contents.

flowchart LR
  SRC["Source code in GitHub"] --> BLD["Build image on runner"]
  BLD --> TST["Run tests and scan image"]
  TST --> PUSH["Push image to Azure Container Registry"]
  PUSH --> SIGN["Sign or attest image"]
  SIGN --> DEVD["Deploy to development"]
  DEVD --> STGD["Deploy same image to staging"]
  STGD --> APPR{"Approval required"}
  APPR -->|"Approved"| PRODD["Deploy same image to production"]
  APPR -->|"Rejected"| STOP["Stop and notify team"]
  PRODD --> HEALTH["Health checks and monitoring"]

The stages

Registry safety features

• No admin user. ACR has an optional shared admin account with a password. Leave it off and use identities and role assignments such as a push role for the pipeline and a pull role for the runtime.
• Private access. Premium registries support private endpoints, so images travel only over your private network.
• Vulnerability scanning. Microsoft Defender for Containers can scan images in the registry and running in clusters.
• Content trust and signing. Image signing, including newer open standards, lets clusters accept only images produced by your trusted pipeline.
• Retention rules. Policies can delete old untagged images, preventing the registry from growing forever and costing more.
• Geo-replication. Premium registries can replicate images to several regions, so clusters pull from nearby copies and survive a regional outage.

Provenance and software bills of materials

Modern pipelines also record provenance: signed statements that say which workflow, from which commit, on which runner, built this exact image. They may also generate a software bill of materials (SBOM), a list of every component inside. GitHub offers artifact attestations for this purpose. Later, a deployment gate can verify that an image really came from your official pipeline before it is allowed to run, which defends against tampering between build and deploy.

Before an application can be deployed, its servers, networks, and databases must exist. Infrastructure as code lets the pipeline build those too, with the same discipline as application code.

The idea

Infrastructure as code (IaC) means describing cloud resources in text files rather than clicking through a portal. The description says “I want a web app, a database, and a vault, with these settings,” and a tool makes Azure match it. Because the description is a file, it can be reviewed, tested, versioned, and run again to produce an identical copy, such as a test environment that mirrors production.

The common tools

Preview before you change

The safest pattern uses two stages. On a pull request, the pipeline runs a preview that shows what would change, with Bicep’s what-if feature or Terraform’s plan, and posts it where reviewers can read it. Reviewers can then see “this change will delete a database” before it happens. After the pull request is approved and merged, the deployment stage applies exactly the reviewed change, in the protected environment.

State, drift, and ownership

Terraform and similar tools keep a state file, a record of what they believe exists. This file can contain sensitive values and must be stored remotely and securely, for example in an Azure Storage account with locking, encryption, access limited to the pipeline identity, and versioning. Drift happens when someone changes resources by hand in the portal, so reality no longer matches the code. A scheduled workflow that runs a preview nightly and alerts on differences catches drift early. Equally important is deciding who owns each layer: a platform team may own networks and shared services, while application teams own their app resources, each with separate pipelines and separate permissions.

Separate infrastructure from application pipelines

Changing infrastructure is riskier and rarer than changing application code. Keep their pipelines separate so that a quick application fix does not accidentally touch networks and databases, and so that the identity used for applications does not need broad rights. The application pipeline should hold only the permissions necessary to deploy to resources that already exist.

Real systems have more than one copy. A safe pipeline moves a change through them in order, with the right people and rules guarding each door.

Why several environments

An environment is a separate copy of your system for a specific purpose. Development is where engineers try things freely. Test or QA is where automated and manual checks run. Staging mirrors production as closely as possible, so surprises appear there instead of in front of customers. Production is the live system. Each step up the ladder is stricter and more carefully guarded. In Azure, environments are typically kept in separate resource groups or, for stronger isolation, separate subscriptions, each with their own identities and network rules.

GitHub environments

GitHub has a feature also called environments. Each GitHub environment is a named target, such as “production”, that you attach to a deployment job. It brings several protections.

flowchart LR
  PR["Pull request"] --> CI["Build and test"]
  CI --> MERGE["Merge to main"]
  MERGE --> ART["Build once and store artifact"]
  ART --> DEV["Deploy to development environment"]
  DEV --> SMOKE["Smoke tests"]
  SMOKE --> STG["Deploy to staging environment"]
  STG --> E2E["End to end and performance tests"]
  E2E --> GATE{"Reviewer approval"}
  GATE -->|"Approved"| PROD["Deploy to production environment"]
  GATE -->|"Rejected"| HALT["Halt and investigate"]
  PROD --> VERIFY["Post deployment verification"]
  VERIFY -->|"Healthy"| DONE["Release complete"]
  VERIFY -->|"Unhealthy"| ROLL["Automatic rollback"]

Branching and release strategies

How you organise branches shapes how pipelines trigger. Two popular approaches are worth knowing.

Preview environments for pull requests

A powerful pattern creates a short-lived copy of the application for each pull request. Reviewers click a link and see the change running, and a clean-up workflow deletes the copy when the pull request closes. Static Web Apps supports this natively, and Container Apps, App Service slots, or temporary resource groups can do it for other kinds of applications. Because these copies cost money while they exist, always pair creation with automatic deletion, and give them tags and a time limit.

Approvals that mean something

An approval is only useful if the approver has the information to decide. Good pipelines show reviewers what is changing, such as the commit list, test results, the infrastructure preview, and the staging verification. They also ensure that the person who wrote the change is not the only one who can approve it, a rule often called separation of duties, and many organisations need this for audit reasons. GitHub can prevent the person who triggered a deployment from approving their own run.

Concurrency control

If two runs deploy to the same environment at the same time, they can fight, and the older code might land after the newer code. GitHub’s concurrency setting names a group, such as the environment name, and ensures only one run in the group is active at a time. For deployments, it is usually best to queue rather than cancel the one in progress, because cancelling halfway through a deployment can leave a system half-updated. For pull request builds, cancelling older runs when a new commit arrives is wise and saves minutes.

A deployment pipeline holds the keys to production. Attackers know it, so a pipeline must be designed as a high-value target, not as a convenience script.

Why pipelines attract attackers

A pipeline runs code, often from many contributors and many third-party sources, on a machine that can reach secrets and cloud accounts. If an attacker can alter what the pipeline runs, they can steal credentials, insert malicious code into the product, or damage the cloud. Real incidents across the industry have included compromised popular actions that leaked secrets from the logs of thousands of workflows, and build systems used as stepping stones to customers. Security here is about shrinking what any single piece can do when it is compromised.

Layer 1: least privilege on the GitHub side

• Restrict the workflow token. Every run receives an automatic token for talking to GitHub itself. Set the default to read-only and let each workflow or job request only the extra permissions it needs.
• Protect branches. Require pull requests, reviews, and passing checks before merge on the main branch, so that nobody can push a change straight into production.
• Protect workflow files. Use code ownership rules so that changes to the workflow folder need review by a platform or security team. A changed workflow is a changed deployment.
• Limit who can approve. Keep the list of production reviewers small and meaningful.

Layer 2: least privilege on the Azure side

• One identity per environment and purpose. A test pipeline should never hold production rights.
• Narrow scopes. Assign roles at the resource or resource group level, not the whole subscription.
• Custom roles where built-in roles are too broad, granting only the specific actions needed.
• Bind trust to environments. Federated credentials for production should match only the production environment, which is protected by approvals and branch rules.
• Separate “plan” from “apply”. Previews can use a read-only identity, while only the protected deploy job gets write rights.

Layer 3: trust in the code that runs

Secrets handling rules

Prefer having no secrets at all: OIDC for Azure and managed identities for applications remove most of them. Where a secret is unavoidable, store it in Azure Key Vault or GitHub’s encrypted secrets, scope it to the environment that needs it, and give it an owner and a rotation date. GitHub automatically masks the exact values of stored secrets in logs, but masking cannot protect transformed values such as an encoded copy, so never print secrets for debugging. Turn on secret scanning and push protection in GitHub so that accidental commits of keys are caught, ideally before they are even pushed.

Code scanning and supply chain tools

Network considerations

If the target resources have no public access, such as databases behind private endpoints, a hosted runner on the internet cannot reach them. You then either use runners inside your Azure network, use hosted runners that GitHub can attach to your virtual network, or restructure so that the pipeline never touches the private resource directly, for example by pushing an image to a registry and letting the private cluster pull it. Avoid the shortcut of opening firewalls to all of GitHub’s published address ranges, since those ranges are shared by every GitHub user.

Slow pipelines waste developer time and money. Fast pipelines encourage frequent, small, safe releases.

What you pay for

GitHub-hosted runner time is metered in minutes, with a multiplier that depends on the operating system, since Linux minutes are the cheapest and Windows and macOS usually cost more. Each plan includes an allowance, and public repositories on standard runners have historically been free, but allowances and rates change, so check the current pricing. Storage for artifacts and caches is also limited and billed beyond the included amount. On the Azure side, you pay for any self-hosted runner machines, for the registry, for preview environments while they exist, and for the test environments that the pipeline deploys.

Speeding things up

Saving money

• Prefer Linux runners where possible, since they are cheaper per minute than Windows or macOS.
• Set job time limits. A hung job can burn minutes for hours. Setting a timeout of, say, 20 minutes on a job that normally takes five prevents runaway charges.
• Shorten artifact and log retention to what you need for audits.
• Clean up preview environments automatically on pull request close and with a nightly sweep for orphans.
• Scale self-hosted pools to zero when idle, using autoscaling.
• Use scheduled workflows sparingly. A job that runs every five minutes uses over 8,000 runs a month.
• Review usage reports in your GitHub organisation to find which workflows consume the most minutes.

A worked example

These numbers are invented to show the arithmetic only. Suppose a team of 20 developers triggers 40 pull request runs per day, and each run takes 12 minutes on a Linux runner. That is 480 minutes a day, or about 10,000 minutes in a 21-working-day month. If caching and parallel jobs cut each run to six minutes, the monthly total halves to roughly 5,000 minutes. More importantly, developers wait six minutes less per check, which is 40 times six, or 240 minutes of waiting removed every day, often worth far more than the minutes saved on the bill.

Every release carries risk. The goal is not zero risk, which is impossible, but a release process where mistakes are small, visible, and quickly reversible.

Deployment strategies

Health checks as gates

A deployment is not finished when files are copied. It is finished when the new version proves it is healthy. Good pipelines run smoke tests (quick checks that the main paths work), query monitoring for error rates and response times for several minutes after release, and only then declare success. If checks fail, the pipeline triggers rollback automatically or alerts the on-call engineer. Azure features help: App Service slot swaps with warm-up, Container Apps traffic weights, Kubernetes readiness probes, and Azure Monitor alerts that a workflow can query.

Rollback

Plan rollback before you need it. For slot-based hosting, swap back. For containers, redeploy the previous image digest, which is why you keep old images and never reuse tags. For Kubernetes, roll back to the previous revision. For infrastructure, re-apply the previous version of the code. The hardest case is database changes, because data cannot be un-written. Use the expand and contract approach: first add new columns or tables in a way that old and new code both work (expand), deploy the new code, and only much later remove the old structures (contract). That way, rolling the application back never hits an incompatible database.

Resilience of the pipeline itself

• Retries for flaky steps. Network blips happen. Retrying a download once is sensible; retrying a test failure repeatedly can hide real bugs.
• Idempotent deployments. Running the same deployment twice should produce the same result, so a re-run after a partial failure is safe.
• A manual path. If GitHub has an outage on the day of a critical fix, can you deploy another way? Document an emergency procedure and test it, with extra approvals and an audit trail.
• Multi-region awareness. For globally important apps, deploy to regions one at a time, starting with the least busy, so that a bad release never hits everywhere simultaneously.
• Dependencies on the internet. Pipelines download actions, packages, and images. Mirror critical ones in your own registry to survive outages of public services.

Measuring delivery health

The research-based DORA metrics describe how well a team delivers software: how often it deploys, how long a change takes from commit to production (lead time), what percentage of releases cause problems (change failure rate), and how fast it recovers (time to restore). GitHub Actions run data, deployment records, and incident tickets can feed these numbers. Watch the trend, not just a single day, and use it to find the biggest bottleneck rather than to rank people.

Pipelines fail, and when they do, speed of diagnosis matters. Knowing where evidence lives and recognising the usual suspects turns hours of confusion into minutes.

Where to look

Common failures and their usual causes

A calm method for investigating

Monitoring the pipeline as a product

Treat the pipeline like a service with its own health. Track success rate, median and long-tail duration, queue time waiting for runners, flaky test frequency, and spend. Alert on a sudden rise in failures or a stuck deployment. Export workflow and audit data to a central system, such as Azure Monitor or a security information platform, to keep history beyond GitHub’s retention period and to correlate pipeline events with production incidents.

There is more than one good way to automate delivery to Azure. This chapter helps you choose, and explains how to move without chaos.

flowchart TD
  Q1{"Is your code hosted on GitHub"} -->|"Yes"| Q2{"Do you depend heavily on Azure Boards, Repos, or Test Plans"}
  Q1 -->|"No, on Azure Repos"| AP["Azure Pipelines is a natural fit"]
  Q2 -->|"No"| GA["GitHub Actions is a natural fit"]
  Q2 -->|"Yes"| MIX{"Can you accept two tools"}
  MIX -->|"Yes"| BOTH["GitHub Actions for CI and Azure Boards for planning"]
  MIX -->|"No"| AP2["Evaluate Azure Pipelines with GitHub repositories"]
  GA --> Q3{"Need private network access"}
  Q3 -->|"Yes"| SELF["Add self hosted or network attached runners"]
  Q3 -->|"No"| HOST["Use GitHub hosted runners"]

The main options compared

How to decide

• Where does the code live? Keep pipelines close to the code unless there is a strong reason not to.
• What does the organisation already run? A mature Azure DevOps estate with hundreds of release pipelines is expensive to move, so migrate gradually, if at all.
• What are the compliance needs? Check approval, audit, and separation-of-duties features of each against your auditors’ expectations.
• Do developers prefer one? Daily experience matters; a tool people like is used properly.
• How strong are your self-hosting needs? If private network access is critical, compare each product’s runner and agent models.

Migrating without drama

GitHub provides an importer tool that can read pipelines from Azure DevOps, Jenkins, CircleCI, and others and produce a first draft of workflow files. Treat its output as a starting point to review, since some features convert imperfectly or not at all.

Teams that succeed with GitHub Actions on Azure tend to repeat a few good designs. Teams that struggle tend to repeat a few familiar mistakes. Knowing both saves months.

Patterns that work

Habits compared

Four decisions worth recording

Teams that write down their key decisions avoid arguing about them again a year later. These short records use the common format of context, decision, and consequences. They are illustrative examples, not mandates.

This chapter gathers the advice of the whole book into one checklist to use before launch, during reviews, and after incidents.

Best practices

Common mistakes

The following scenarios are invented illustrations built from common situations. They are not case studies of real companies, and the numbers are examples chosen to make the ideas concrete.

Short answers to the questions beginners ask most often.

You began with a bakery whose recipes were carried by hand. You now have the blueprint for an automatic delivery line from GitHub to Azure.

GitHub Actions turns every code change into an automatic, repeatable journey: an event starts a workflow, jobs run on clean runners, the build is tested and stored once, and a protected deployment job signs in to Azure with a short-lived OIDC token and delivers the same tested artifact to App Service, Functions, Container Apps, AKS, or other targets. Environments, approvals, and slots or canaries make releases safe, and monitoring, tagging, and run books make problems quick to solve. Around all of this sit the disciplines that keep a pipeline trustworthy: least privilege, pinned actions, careful treatment of untrusted code, ephemeral runners, infrastructure as code with previews, and constant attention to speed and cost.