DEV Community: Amaresh Pelleti

Docker Volumes vs Bind Mounts: Which to Use

Amaresh Pelleti — Mon, 09 Nov 2026 13:41:51 +0000

Use a Docker volume when the container owns the data, such as a database or a model cache. Use a bind mount when you need to edit the files on your host, such as source code or a config file. The docker volumes vs bind mounts choice also changes startup behavior and speed. It decides how easy it is to lose data, too. So it's worth testing before you pick.

I ran everything below on Docker Engine 29.4.3 with Docker Desktop for Mac. I didn't test a Linux host, so I flag the spots where it may differ.

What Is the Difference Between Docker Volumes vs Bind Mounts?

A volume is storage that Docker creates and manages for you. A bind mount maps a folder that already exists on your host into the container. Docker's volumes documentation calls volumes the preferred way to persist container data. Its bind mounts page points bind mounts at sharing source code and host config files.

	Volume	Bind mount
Who manages it	Docker	You
Where data lives	Docker's storage area	A path you choose on the host
Host path must exist	No	Yes, unless Docker creates it
Fills from the image on first use	Yes (copy-up)	No, it hides the image's files
Easy to edit from the host	No	Yes
Best for	Databases, caches, app state	Source code, config files

When Should You Use a Docker Volume?

Use a volume for any data the container creates and you want to keep, but never edit by hand. Volumes survive the container, and Docker handles their location. I wrote a file into a volume, let the container exit, and read it back from a new one:

docker run --rm -v dvbtest-data:/data alpine sh -c 'echo saved > /data/note.txt'
docker run --rm -v dvbtest-data:/data alpine cat /data/note.txt

saved

The --rm flag deleted both containers, but the volume stayed, and docker volume ls still listed it. docker volume inspect shows where Docker stores it:

local /var/lib/docker/volumes/dvbtest-data/_data

⚠️ Note: that path does not exist on a Mac. On Docker Desktop the volume lives inside the Linux VM, so ls on my host returned No such file or directory. If you need to browse the files from your host, a volume is the wrong tool.

The same pattern powers the model cache in the Ollama Docker setup guide. Without a named volume, those downloads vanish with the container.

When Should You Use a Bind Mount?

Use a bind mount when your host and the container need the same files. Source code you edit in an IDE is the classic case. So is a config file you maintain. Per the docs, a bind mount gives the container write access to your host files by default. Add :ro when the container only needs to read:

docker run --rm -v /tmp/dvb/auto-created:/data:ro alpine sh -c 'echo z > /data/y'

sh: can't create /data/y: Read-only file system

The container can't change the host folder now. That matters because a bug or a bad command inside the container can otherwise delete files on your machine.

On ownership: my container wrote as root, and the file still showed up on my Mac owned by my own user. That mapping is a Docker Desktop behavior. I didn't test Linux, where a root process in the container may leave root-owned files on the host.

Does a Mount Hide the Files Already in the Image?

A bind mount always hides what the image has in that folder. A new named volume does the opposite: Docker copies the image's files into it first. I mounted both over the NGINX web root, /usr/share/nginx/html, which ships with index.html and 50x.html.

An empty host folder as a bind mount:

total 4
drwxr-xr-x    2 root     root            64 Nov  5 13:57 .

That folder looked empty, and index.html was gone from view. A new named volume at the same path:

50x.html
index.html

Docker copied both files into the volume on first use. To switch that copy off, use volume-nocopy:

docker run --rm --mount type=volume,src=dvbtest-nocopy,dst=/usr/share/nginx/html,volume-nocopy nginx:alpine ls -A /usr/share/nginx/html

That listed zero files. Note the copy-up only happens when the volume is empty. A volume that already holds data hides the image's files, just like a bind mount.

Docker Volumes vs Bind Mounts With -v and --mount

The two flags differ in one way that bites people: what happens when the host path is missing. With -v, Docker silently creates the folder. With --mount, it stops with an error. Here is -v pointing at a path that didn't exist:

docker run --rm -v /tmp/dvb/auto-created:/data alpine sh -c 'echo hi > /data/x'

It ran fine and created /tmp/dvb/auto-created on my host. The same mismatch with --mount:

docker run --rm --mount type=bind,src=/tmp/dvb/nope,dst=/data alpine true

docker: Error response from daemon: invalid mount config for type "bind": bind source path does not exist: /host_mnt/private/tmp/dvb/nope

It exited with code 125. The /host_mnt/... prefix looks like Docker Desktop's file-sharing path translation. Add bind-create-src to the --mount options if you want the folder created, as the docs describe.

A typo in a -v path therefore creates an empty folder and starts the container happily. That is a classic source of "my config isn't loading" bugs. Prefer --mount in scripts.

There is a second trap in the -v syntax. A bare name is a volume, and a path starting with ./ is a bind mount:

docker run --rm -v data:/app alpine sh -c 'echo a > /app/f'    # creates a named volume "data"
docker run --rm -v ./data:/app alpine sh -c 'echo b > /app/f'  # writes to ./data on your host

After the first command, docker volume ls listed a volume called data and my project folder stayed empty. The second wrote f into ./data. Forget the ./ and you create a hidden volume instead of the folder you meant.

How Much Slower Is a Bind Mount on Docker Desktop?

On my Mac, writing 3,000 small files into a bind mount took about five times longer than into a volume. Each run launched a container and created the files with a shell loop, so both numbers include roughly the same startup cost:

Run	Bind mount	Named volume
1	4.49 s	0.70 s
2	3.27 s	0.73 s
3	3.78 s	0.67 s

This is a rough test: three runs, one machine, one workload. The gap likely comes from Docker Desktop crossing the VM boundary on every file operation. Expect it to matter for node_modules, package caches and builds. On a Linux host, a bind mount is a direct path and I'd expect no such penalty, but I haven't measured it.

How Do You Delete Volumes Safely?

Containers don't delete volumes, so unused ones pile up until you remove them. Compose shows the difference well. I started a service with a volume, then ran docker compose down. The volume survived:

dvbtest_appdata

⚠️ Note: docker compose down -v deletes every named volume declared in that Compose file, along with its data. Run docker compose down without -v unless you really want a clean slate.

docker compose down -v

 Volume dvbtest_appdata Removed

The earlier run's log line was still there when I brought the service back up, so the data had persisted until I used -v. For one volume, use docker volume rm <name>. docker volume prune removes all unused volumes, so read what it lists first.

Docker Volumes vs Bind Mounts: Which Should You Use?

Pick a volume for data the container owns and a bind mount for files you edit. If you're unsure, start with a volume, because it's portable and faster on Docker Desktop.

Situation	Use
Databases, caches, uploads, anything you back up with Docker	Volume
Source code, config files, build output you want on your host	Bind mount
Config the container should read but never change	Bind mount with `:ro`
Temporary state you don't need to keep (Docker's docs point to `tmpfs`)	Neither

For the rest of your container setup, the Docker best practices guide covers the surrounding habits, and the Dockerfile best practices cover the image side.

Frequently Asked Questions

Q: Should I use a Docker volume or a bind mount for a database?
A: Use a volume. Docker manages its location, it survives container removal, and on Docker Desktop it avoided the slowdown I saw with bind mounts. A bind mount makes sense for a database only if you must inspect the files directly from the host.

Q: What is the difference between -v and --mount?
A: --mount uses explicit key=value options and errors if a bind source path is missing. -v is shorter and silently creates a missing host folder. Both can create volumes or bind mounts, but --mount is the clearer choice for scripts.

Q: Do Docker volumes persist after the container is deleted?
A: Yes. Named volumes stay until you remove them with docker volume rm, docker volume prune or docker compose down -v. Anonymous volumes created with docker run --rm are removed along with the container.

Q: Why is my bind mount empty inside the container?
A: A bind mount hides whatever the image has at that path. If the host folder is empty, the container sees an empty folder. A new named volume works differently, because Docker copies the image's files into it first.

Q: Are Docker bind mounts slower than volumes?
A: On Docker Desktop for Mac, yes. Creating 3,000 small files took 3.3 to 4.5 seconds on a bind mount and about 0.7 seconds on a volume in my tests. I didn't measure a Linux host.

Quick Summary:

Docker manages a volume, while a bind mount maps a host folder you choose
Volumes survived container removal in my test, and docker compose down -v is what deletes them
New volumes get the image's files copied in first, but a bind mount hides them
-v creates a missing host path silently, and --mount stops with exit code 125
-v data:/app makes a volume, and -v ./data:/app makes a bind mount
Creating 3,000 files took about five times longer on a bind mount than a volume on Docker Desktop for Mac
Any bind mount the container should only read needs :ro

Before your next docker run -v, decide which side owns the data. In the docker volumes vs bind mounts choice, that answer settles it. Container-owned data goes in a volume. Files you edit go in a bind mount.

Git Pull vs Fetch: What Each Command Really Does

Amaresh Pelleti — Fri, 06 Nov 2026 13:26:29 +0000

git fetch downloads new commits and leaves your branch and your files alone. git pull runs a fetch and then merges or rebases the result into your current branch. The git pull vs fetch choice comes down to one question: do you want to look at incoming changes first, or take them right now?

I ran every command below on Git 2.56.0. A bare repository played the remote, and a second clone played a teammate who keeps pushing to main.

What Is the Difference Between Git Pull vs Fetch?

git fetch updates your remote-tracking branches, such as origin/main, and records what it got in .git/FETCH_HEAD. It never touches your local branches or your working tree. git pull runs git fetch first, then integrates the fetched branch into your current branch. So fetch is safe to run at any time, and pull can change your files.

	`git fetch`	`git pull`
Updates `origin/main`	Yes	Yes
Moves your local branch	No	Yes, by merge or rebase
Changes files in your working tree	No	Yes
Can stop on a conflict	No	Yes
Safe with uncommitted changes	Yes	Only if they don't overlap

The git fetch docs describe the first half. The git pull docs describe the second.

What Does Git Fetch Change in Your Repository?

Fetch changes your remote-tracking refs and nothing else. In my test the teammate pushed one commit. Before the fetch, git status saw nothing:

git status -sb

## main...origin/main

Then I fetched:

git fetch

From /tmp/gpf/remote
   144625a..22c2c9f  main       -> origin/main

Now Git knows the remote moved ahead:

## main...origin/main [behind 1]

My app.txt still said v1. The new commit sat on origin/main, where I could read it first:

git log --oneline main..origin/main
git diff main origin/main --stat

22c2c9f teammate edits app
 app.txt | 1 +
 1 file changed, 1 insertion(+)

.git/FETCH_HEAD held one line, the commit hash plus branch 'main' of /tmp/gpf/remote. Scripts use that file, and you rarely need to open it.

What Does Git Pull Do Beyond a Fetch?

Pull does the fetch, then moves your branch. From the same starting point, git pull printed this:

Updating 144625a..22c2c9f
Fast-forward
 app.txt | 1 +
 1 file changed, 1 insertion(+)

That is the same result as running git fetch and then git merge origin/main. I checked: the two-step version printed the identical Fast-forward output. Pull knows which branch to merge because of the upstream settings Git stored when I first pushed with -u:

branch.main.remote origin
branch.main.merge refs/heads/main

A fast-forward is the easy case. The trouble starts when both sides have new commits.

Git Pull vs Fetch When Your Branches Have Diverged

When your branch and origin/main both have commits the other lacks, a bare git pull stops with an error until you say how to combine them. I added mine.txt locally while the teammate pushed another commit. After a fetch, status showed the split:

## main...origin/main [ahead 1, behind 1]

* 8e9826c me adds mine.txt
| * 0ed7d96 teammate adds line 2
|/
* 22c2c9f teammate edits app

With no pull.* config set, git pull refused:

hint: You have divergent branches and need to specify how to reconcile them.
hint:   git config pull.rebase false  # merge
hint:   git config pull.rebase true   # rebase
hint:   git config pull.ff only       # fast-forward only
fatal: Need to specify how to reconcile divergent branches.

The command exited with code 128 and changed nothing. You have three ways forward, and each leaves different history:

Command	What it does	History after
`git pull --ff-only`	Refuses unless a fast-forward is possible	Unchanged. It failed with `Not possible to fast-forward, aborting.`
`git pull --rebase`	Replays your commits on top of `origin/main`	Linear. My commit became `1b5ae05`
`git pull --no-rebase`	Merges `origin/main` into your branch	A merge commit, `Merge branch 'main' of ...`

Rebase gave me a straight line of four commits. The merge version added a fifth commit with two parents. Neither is wrong. Rebase keeps git log readable, and merge never rewrites a commit you already made. If you want the longer comparison, the branching and merging strategies guide covers when each fits, and the rebase, stash and cherry-pick guide covers the rebase details.

Did the pull go the wrong way? Git records where your branch was before an integration in ORIG_HEAD. After my --rebase pull, I ran this to go back:

⚠️ Note: git reset --hard throws away every uncommitted change to tracked files in the whole repository. Commit or stash first.

git reset --hard ORIG_HEAD

My branch returned to 8e9826c, the commit from before the rebase. The reset, revert and restore guide explains the three reset modes.

Why Does Git Pull Fail With Uncommitted Changes?

Pull fails when your uncommitted edits touch a file the incoming commits also change. Git aborts before it changes anything. I edited app.txt without committing while the teammate pushed a new line to the same file:

error: Your local changes to the following files would be overwritten by merge:
    app.txt
Please commit your changes or stash them before you merge.
Aborting

A fetch in the same state worked without complaint. It printed 0ed7d96..b67314f main -> origin/main, and git status still showed my M app.txt edit untouched. That is the practical reason to fetch first: you see the incoming change, then decide whether to commit, stash, or wait.

How Do You Remove Stale Remote Branches With Fetch?

A plain git fetch adds new branches but never deletes old remote-tracking refs. Run git fetch --prune to remove the ones whose branch is gone from the remote. The teammate pushed feature/login, then deleted it from the remote. My next plain fetch printed nothing, and git branch -r still listed it:

  origin/HEAD -> origin/main
  origin/feature/login
  origin/main

With --prune, the stale ref went away:

git fetch --prune

 - [deleted]         (none)     -> origin/feature/login

This only removes remote-tracking refs, never your local branches. Per the docs, tags are left alone unless you add --prune-tags. To make it the default for every fetch and pull, run git config --global fetch.prune true.

Git Pull vs Fetch: Which Should You Use?

Use git fetch when you want to see what changed before you integrate it, and git pull when your branch is simply behind and you trust the incoming commits. If you pull on a shared, busy branch, expect the divergence prompt sooner or later.

Fetch first when you have uncommitted work, when the branch is shared and busy, or when a script only needs to know whether you're behind.
Pull when you are a plain fast-forward behind. My first pull above was exactly that.
Use a two-step habit when you want control: git fetch, then git status -sb, then git merge --ff-only origin/main or git rebase origin/main.

Settle the divergent-branch prompt once instead of per command. For linear history, set git config --global pull.rebase true. To refuse anything except a fast-forward, set git config --global pull.ff only. Those two keys come from Git's own hint text above. I tested the matching command-line flags, not the config keys themselves.

Nothing in the Git 3.0 breaking changes list touches pull or fetch, so nothing planned for Git 3.0 changes how these two commands behave. For the bigger picture of how these commands fit together, start with the Git fundamentals guide.

Frequently Asked Questions

Q: Is git pull the same as git fetch plus git merge?
A: Yes, by default. git pull runs git fetch, then merges the upstream branch into your current branch. In my test, git fetch followed by git merge origin/main printed the same Fast-forward output as a single pull. With --rebase it rebases instead of merging.

Q: Does git fetch change my working directory?
A: No. It updates remote-tracking branches like origin/main and .git/FETCH_HEAD only. My edited app.txt was untouched after a fetch, and git status still showed it as modified.

Q: Why does git pull say "Need to specify how to reconcile divergent branches"?
A: Your branch and the remote both have new commits, and no pull.rebase or pull.ff setting tells Git what to do. Pass --rebase, --no-rebase or --ff-only, or set pull.rebase or pull.ff once.

Q: Should I use git fetch or git pull?
A: Fetch when you want to inspect incoming commits first or have uncommitted work. Pull when you're just behind and want to catch up. Many people fetch, check git status -sb, then merge or rebase by hand.

Q: How do I delete remote-tracking branches that no longer exist?
A: Run git fetch --prune. It removes stale origin/* refs and leaves local branches alone. Set git config --global fetch.prune true to do it on every fetch.

Quick Summary:

git fetch updates origin/main and .git/FETCH_HEAD, and never touches your branch or files
git pull is a fetch plus a merge or rebase, so it can change files and stop on conflicts
A bare pull on diverged branches fails with exit 128 until you pass --rebase, --no-rebase or --ff-only
Pull aborts if uncommitted edits overlap incoming changes, while fetch works fine
Plain fetch keeps stale origin/* refs, and --prune removes them
git reset --hard ORIG_HEAD brought my branch back to its pre-rebase commit

Next time the git pull vs fetch question comes up, run git fetch and git status -sb first. If the status says behind, pull is a safe fast-forward. If it says ahead and behind, pick a strategy before you pull.

Azure Managed Identity vs Service Principal: Which to Use

Amaresh Pelleti — Thu, 05 Nov 2026 12:57:10 +0000

Most Azure managed identity vs service principal debates start from a false split. A managed identity is a service principal. Microsoft's docs say Azure creates a service principal of a special type in Entra ID for every managed identity. The real question is who looks after the credential: Azure or you. Below you get the rule for choosing, the commands for both, and the gotchas that appear after the first deploy.

I built this from Microsoft Learn and the Azure CLI reference as of November 3, 2026. I haven't run every command against a live tenant, so test them in a sandbox subscription first.

Azure Managed Identity vs Service Principal: What Is the Difference?

A service principal is the identity an application uses to sign in to Entra ID and receive Azure permissions. A managed identity is a service principal whose credential Azure creates, stores and rotates for you. You can never read it. With a regular service principal, you create a secret or certificate yourself. You store it and replace it before it expires. That credential handling is the whole difference.

There are two flavors of managed identity:

System-assigned identities live on a single Azure resource, such as a VM or an App Service. Delete the resource and Azure deletes the identity.
User-assigned identities are standalone resources. You create them, attach them to one or more resources, and delete them yourself.

Managed identities cost nothing extra, according to the same overview page.

Azure Managed Identity vs Service Principal: Side by Side

	Managed identity	Service principal (app registration)
Credential	None you can see or leak	Client secret, certificate or federated credential
Where code can run	Azure compute that supports managed identities	Anywhere
Expiry risk	None	Secrets last 24 months at most
Lifecycle	System-assigned: tied to the resource. User-assigned: independent	Until you delete the app
Sharing	User-assigned can attach to many resources	Anything that holds the credential
Best fit	Workloads running on Azure	CI/CD, on-premises, other clouds

When Should You Use a Managed Identity?

Use a managed identity whenever your code runs on Azure compute that supports one. It removes the secret. Nothing sits in an environment variable waiting to leak, and nothing expires on a Friday night. Microsoft's passwordless guidance recommends managed identities plus Azure RBAC as the default path for Azure-to-Azure connections.

In code, DefaultAzureCredential from the Azure Identity libraries handles both environments. Locally it can use the account you signed in with through the Azure CLI. On Azure it picks up the managed identity of the host. Your code doesn't change between the two.

Should You Pick System-Assigned or User-Assigned?

Microsoft's own best-practice page says user-assigned identities fit a broader range of scenarios. Pick user-assigned when:

Resources come and go quickly. Many VMs with system-assigned identities can hit the Entra object-creation rate limit and return HTTP 429.
Several resources need the same access. In Microsoft's example, four VMs sharing one user-assigned identity need two role assignments. Four system-assigned identities need eight.
Access must exist before the resource does. A system-assigned identity appears with its resource, so you can't grant it a role in advance.

Pick system-assigned when permissions should disappear with the resource. It also fits audit logs that must name the specific resource, not just the identity.

When Do You Still Need a Service Principal?

You need a service principal when your workload runs somewhere a managed identity can't attach: GitHub Actions runners, on-premises servers, or another cloud. Even then, avoid a stored secret. Microsoft says client secrets are less secure than certificate or federated credentials and should not be used in production.

Workload identity federation is the secretless route. Your app registration or user-assigned identity trusts tokens from an external provider such as GitHub. The workload then swaps that token for an Entra access token. Two details worth knowing: system-assigned identities can't hold federated credentials, and an app or user-assigned identity can have at most 20 of them.

How Do You Set Up Each One?

A managed identity for an App Service

⚠️ Note: leave --scope off az webapp identity assign. The CLI reference lists Contributor as the default for --role. Grant the narrow role yourself in the next step.

This creates one user-assigned identity and attaches it to one web app:

az identity create --name app-uami --resource-group rg-app --location centralus
az webapp identity assign -g rg-app -n my-web-app --identities app-uami

Next, grant it read access to one storage account. Passing --assignee-object-id skips the Microsoft Graph lookup. The reference says pairing it with --assignee-principal-type avoids propagation-latency errors.

PRINCIPAL_ID=$(az identity show --name app-uami --resource-group rg-app --query principalId --output tsv)

az role assignment create \
  --assignee-object-id "$PRINCIPAL_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "Storage Blob Data Reader" \
  --scope /subscriptions/<sub-id>/resourceGroups/rg-app/providers/Microsoft.Storage/storageAccounts/<account>

A service principal for GitHub Actions, no secret

az ad sp create-for-rbac creates a password credential by default. Turn that off and scope the role to one resource group:

az ad sp create-for-rbac --name gh-deploy --create-password false \
  --role Reader --scopes /subscriptions/<sub-id>/resourceGroups/rg-app

Then add a federated credential on the app registration under Certificates & secrets. The issuer is https://token.actions.githubusercontent.com and the audience is api://AzureADTokenExchange. In the workflow, grant id-token: write and log in with the official action:

permissions:
  id-token: write
  contents: read

steps:
  - uses: azure/login@v2
    with:
      client-id: ${{ secrets.AZURE_CLIENT_ID }}
      tenant-id: ${{ secrets.AZURE_TENANT_ID }}
      subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

Our Terraform and GitHub Actions deployment guide shows this login in a full pipeline. The service principal setup guide covers the portal steps.

What Breaks in an Azure Managed Identity vs Service Principal Setup?

Role changes take hours to reach a managed identity. Azure caches managed identity tokens per resource URI for around 24 hours. You can't force a refresh. If the app still gets a 403 after a role or group change, the old token is the likely cause. Microsoft's fix is to put permissions directly on a user-assigned identity instead of going through an Entra group.

Deleting an identity doesn't delete its role assignments. They linger as "Identity not found". They also count against the 5,000 role assignments per subscription. Microsoft's cleanup command removes assignments whose ObjectType is Unknown:

Get-AzRoleAssignment | Where-Object {$_.ObjectType -eq "Unknown"} | Remove-AzRoleAssignment

⚠️ Note: that command runs against your current subscription and deletes every matching assignment. Run the Get-AzRoleAssignment half on its own first and read the list.

A wrong federated-credential subject fails silently. Entra accepts a bad subject when you create the credential. The failure shows up at token exchange. Matching is case-sensitive, wildcards aren't supported, and the issuer, subject and audience must match the token exactly.

GitHub changed the default subject format. For repositories created after July 15, 2026, GitHub's OIDC reference says the default sub claim includes owner and repository IDs. One example is repo:octo-org@123456/octo-repo@456789:ref:refs/heads/main. Older repositories keep the name-based format unless you opt in. A credential written in the old format won't match a new repository's token. Copy the subject from the docs, not from an older workflow.

Anyone who can run code on the resource can use its identity. Microsoft's example: a user can run code in a Logic App but has no storage access. That user can still read the storage account through the app's managed identity. Grant code-execution roles sparingly.

Parallel creation can collide. In ARM templates, create federated credentials under the same parent identity one at a time. Parallel creation can fail with a 409 conflict.

Azure Managed Identity vs Service Principal: Which Should You Choose?

Work down this list and stop at the first match:

Code runs on Azure compute that supports managed identities. Use a managed identity. Pick user-assigned if resources share access or churn often.
Code runs in GitHub Actions, Kubernetes elsewhere, or another cloud. Use a federated credential on an app registration or a user-assigned identity.
Code runs on your laptop. Sign in with az login and let DefaultAzureCredential use that. Don't create a service principal just for local work.
None of the above works. Use a service principal with a certificate. Keep expiry under 12 months and set a reminder to rotate it.

For secrets that still need a vault, see our comparison of AWS, Azure and GCP secret managers. For the wider picture, start with the Azure security best practices guide.

Frequently Asked Questions

Q: Is a managed identity the same as a service principal?
A: Almost. Every managed identity has a service principal of a special type behind it in Entra ID. The difference is the credential: Azure manages it for a managed identity, while you manage it for a regular service principal.

Q: Can a managed identity be used outside Azure?
A: Not directly. A managed identity serves workloads running on Azure resources. For GitHub Actions or other clouds, federate an app registration or a user-assigned identity with the external provider.

Q: How long does a client secret last?
A: At most 24 months, and Microsoft recommends under 12. az ad sp create-for-rbac defaults to one year through its --years option.

Q: Why does my managed identity still get a 403 after I added a role?
A: The role may not have propagated yet, or the cached token predates it. Azure caches tokens for roughly 24 hours and can't refresh them early. Restarting the app doesn't clear that cache, so the practical fix is to wait. To avoid the delay next time, grant roles directly to a user-assigned identity instead of through a group.

Q: Should I use system-assigned or user-assigned identities?
A: Use user-assigned when resources are short-lived or share access. Use system-assigned when permissions should end with the resource, or per-resource audit logs matter.

Quick Summary:

A managed identity is a service principal whose credential Azure manages and rotates for you
Use a managed identity on Azure compute, and federation for GitHub Actions and other clouds
Client secrets cap at 24 months and Microsoft says not to use them in production
Managed identity tokens are cached about 24 hours, so role changes can take hours to apply
Deleted identities leave role assignments behind, and the limit is 5,000 per subscription
New GitHub repositories use a different OIDC sub format, so check your federated credential's subject

Whichever way the Azure managed identity vs service principal choice goes for you, start small. Pick one workload that still uses a client secret and move it to a managed identity or a federated credential. Then delete the secret.

GitHub Actions Lockfile Guide: How actions.lock Works

Amaresh Pelleti — Wed, 04 Nov 2026 18:04:40 +0000

GitHub Actions workflow lockfiles went into public preview on October 14, 2026 and became generally available on October 28. The timing is almost funny: GitHub automated the exact workaround this blog told you to do by hand. A GitHub Actions lockfile pins every action in a workflow, plus its transitive dependencies, to a commit you've actually reviewed, so a tag moving after merge can't quietly swap in different code. Here's what .github/workflows/actions.lock locks, how to roll it out without breaking CI, and the limits GitHub documents but the announcements skip.

I haven't run the extension against a real repository for this guide. Everything below comes from GitHub's changelog, GitHub Docs and the gh-actions-lock README as of November 3, 2026, when the extension was at v0.4.1. The extension is young and its flags have already changed between releases, so treat gh actions-lock --help as the final word.

The Problem: Tags and Branches Move After You Review Them

When you review a pull request that adds uses: actions/checkout@v4, you're reviewing whatever commit v4 points to at that moment. Tags are mutable refs. A maintainer, or someone who compromises a maintainer's account, can repoint v4 tomorrow, and your workflow picks up the new code on its next run. No new pull request, no re-review.

That's not hypothetical. Several real GitHub Actions supply-chain incidents followed exactly this pattern: compromise the account behind a popular action, repoint the tag, then wait for CI everywhere to pull the new commit. Manual SHA pinning closes this gap one action at a time, but doing it by hand across dozens of workflows and their transitive dependencies doesn't scale, and nobody relocks a hand-pinned ref once it goes stale.

What a GitHub Actions Lockfile Actually Pins

A workflow lockfile lives at .github/workflows/actions.lock. It's one file per repository, with entries for every workflow you've onboarded, and it's machine-generated: GitHub says never to edit it by hand. It pins a commit SHA to every action your workflows depend on, including transitive dependencies, meaning the actions your actions call internally.

Each locked dependency records four things: the ref it was resolved from (a tag or branch), the exact commit that ref pointed to, and the numeric owner_id and repo_id of the source repository. At run time, GitHub Actions uses those two IDs to confirm that the repository behind the name is still the one you locked.

Once a workflow is onboarded, every action it uses must be in the lockfile, and the locked commit is what runs. That commit also has to be reachable from the recorded branch or tag in the action's own repository. A commit that exists only in a fork, or that's no longer reachable, is rejected when the workflow runs.

One boundary catches people out: a lockfile doesn't pin reusable workflow calls. GitHub's docs are explicit that jobs.<id>.uses calls aren't covered, and that to pin a reusable workflow you reference it by its full commit SHA. The dependencies of a reusable workflow are covered by the lockfile in the repository where that workflow is defined, not by yours. So if you call shared workflows from another repository, that repository needs its own lockfile.

Two more details. A lockfile only controls which action code runs. It doesn't control input parameters, secrets or the runner image. And there are two ways to refer to an action in your own repository: uses: ./path runs whatever is checked out in the runner's workspace, so the extension can't pin it, while uses: $/path runs your repository's action at the workflow's own commit, so it's pinned and the actions it uses can be locked.

Installing and Generating Your First actions.lock

Install the gh-actions-lock extension through the GitHub CLI. GitHub recommends turning on Dependabot for GitHub Actions first, so the lockfile stays in sync from day one.

gh extension install github/gh-actions-lock

From the root of your repository, run it with no arguments. It scans every workflow under .github/workflows/, pins each resolvable action to a commit SHA, and writes the lockfile.

gh actions-lock

To onboard a single workflow instead of the whole directory, pass its path.

gh actions-lock .github/workflows/ci.yml

Check your uses: lines before you run it. The lockfile pins whatever each ref resolves to right now, so make sure those are the versions you actually want locked.

Review the whole diff, not just the lockfile. The extension also rewrites your uses: references to the specific version it resolved, so octo-org/deploy-action@v3 can become octo-org/deploy-action@v3.1.0. That makes the reference more specific without changing the commit it points to. If you'd rather keep partial versions like v4 as written, pass --no-narrow.

Local actions need a decision. The extension never follows or locks a ./ local action. If a local action in your checkout uses other actions, the run reports a local-action error and writes nothing. You have two options:

gh actions-lock --migrate-local-actions
gh actions-lock --ignore-local-actions

--migrate-local-actions rewrites same-repository ./… references to $/… so the action runs as a pinned reference. It only happens when you pass the flag, because the two forms behave differently. --ignore-local-actions keeps the ./ path and downgrades the error to a warning, but a local action that uses an unlocked action will then fail at run time, partway through the job. GitHub recommends the migrate option.

GitHub Enterprise Server isn't supported. The extension works with github.com and GitHub Enterprise Cloud, including data-residency tenants (*.ghe.com). For a tenant, run gh auth login --hostname TENANT.ghe.com and run the tool from the tenant repository checkout. Public actions like actions/checkout are still read from github.com, so in CI on a tenant you'll want a github.com token with no permissions in GH_ACTIONS_LOCK_GITHUB_COM_TOKEN. Without one, those lookups are anonymous and share GitHub's limit of 60 requests an hour per IP address.

Rolling Out a GitHub Actions Lockfile One Workflow at a Time

You don't have to lock every workflow in one pull request. A scoped run touches only the workflow you name, so you can onboard your highest-risk pipeline first: the one that runs on every pull request, or the one holding deploy credentials. Only a full-directory run prunes entries for deleted workflows, so run it without a path now and then to keep the file clean. Anyone with write access to the repository can do the onboarding.

Expect a real diff the first time, and check one thing before you merge: your allowed-actions policy. After a workflow is onboarded, the allowlist is checked against locked commit SHAs instead of tags. An entry pinned to a tag, such as actions/checkout@v6, no longer matches. Use a wildcard or the full commit SHA instead, or onboarded workflows will start failing.

After onboarding, rerun the tool whenever you add a workflow that has uses: dependencies, or add or remove a uses: dependency in an existing one.

Keeping Your GitHub Actions Lockfile Current

Locked pins are sticky by design, and what happens when a ref moves depends on the ref:

A branch or partial version such as main or v3 keeps its locked commit, and the extension reports a ref-moved warning. Check the upstream history, then run gh actions-lock --relock to advance it.
A full version tag such as v3.1.0 must point at its locked commit. If the tag moved, you get an error until you run --relock or change the uses: line.
Rewritten history, where the locked commit is no longer in the reference's history (a force-push, for example), is an error that --relock doesn't fix. After you've reviewed the upstream history, run gh actions-lock --accept-moved. GitHub says not to use --accept-moved in automation.

Dependabot handles the routine bumps. When it opens a version update for an action in an onboarded workflow, it regenerates the matching lockfile entry in the same pull request, with no extra configuration, so the workflow file and the lockfile can't drift apart. It only maintains coverage, though. It won't onboard a workflow that has no lockfile entries yet.

Treat lockfile changes like any other dependency change. A changed commit is new code your workflows will run. A changed owner_id or repo_id should be rare and means the repository behind that name isn't the one you originally locked, so investigate before you merge. Adding .github/workflows/actions.lock to your CODEOWNERS file makes sure the right team reviews those diffs.

Enforcing the Lockfile: CI Checks, Pre-Commit Hooks, and Org Policy

A lockfile only protects you if something checks it. These are the modes:

Command	Writes	Network	Use for
`gh actions-lock`	yes	yes	Onboarding and fixing the lockfile
`gh actions-lock --relock`	yes	yes	Advancing moved refs to current upstream commits
`gh actions-lock --verify`	no	yes	CI: the same checks as a fix run
`gh actions-lock --verify-local`	no	no	Pre-commit: every `uses:` has a lockfile entry
`gh actions-lock --no-fix`	no	yes	Read-only report

In CI, run gh actions-lock --verify on pull requests and make it a required check. It checks provenance before merge, and the runner checks it again at job start. The repository ships a ready-made verify-lockfile.yml you can copy and adapt.

--verify-local is the fast offline gate for a pre-commit hook. It makes no network calls and needs no authentication, but it only confirms every action reference has a lockfile entry, not that the entry is trustworthy. That's the right trade-off locally, and the wrong one as your only check.

For several repositories, the Require lockfile policy lets enterprise, organization and repository admins mandate lockfiles instead of relying on every team to wire up that CI step. GitHub's rollout advice is worth following: pilot it first. Evaluate mode, which is only available on GitHub Enterprise Cloud, shows you what would be blocked before anything breaks. The policy blocks runs of targeted workflows that aren't onboarded, including workflows with no uses: dependencies. It also blocks a calling workflow when a reusable workflow it calls isn't onboarded in its own repository. It's a separate policy from "Require actions to be pinned to a full-length commit SHA", though an onboarded workflow satisfies both.

What a GitHub Actions Lockfile Does Not Do

Locking a dependency and vetting it are different jobs, and GitHub says so directly: "Locking does not determine whether the dependency itself is safe, so review dependencies before locking them." A lockfile guarantees the code that ran during your review is the code that runs on every later job. It says nothing about whether that code was safe to run in the first place.

The README also lists limits the announcement doesn't mention:

Reusable workflows called from another repository aren't locked.
Container images aren't locked, and any image without an @sha256: digest produces a warning.
A lockfile change that moves a floating ref (v4, main) back to an older commit in its history isn't detected, so review lockfile diffs or pin exact tags.

And it doesn't replace restricting GITHUB_TOKEN permissions or requiring review on workflow changes. It closes one gap, tag drift after review, not the whole supply chain.

Lockfiles vs Manual SHA Pinning: What Changes, What Doesn't

If you've been pinning actions to a SHA by hand, the practice our GitHub Actions security guide recommends, that wasn't wrong. GitHub has historically recommended it too. But for repositories that adopt a lockfile, GitHub now says SHA pinning inside workflow files is no longer necessary. The lockfile is the better option because it covers transitive dependencies, keeps your workflow YAML easier to read, and records the identity of the source repository. An onboarded workflow also satisfies the "Require actions to be pinned to a full-length commit SHA" policy.

Two exceptions keep manual pinning alive. Calls to reusable workflows still need a full commit SHA by hand, because the lockfile doesn't cover them. And workflows you haven't onboarded yet still rely on whatever pinning you've already got.

For teams starting from zero, skip straight to the lockfile. For teams with hand-pinned SHAs everywhere, you can keep them while you migrate, and drop them once each workflow is onboarded.

Frequently Asked Questions

Q: Is the GitHub Actions lockfile still in preview?
A: No. It was in public preview from October 14, 2026 and became generally available on October 28, 2026, on GitHub Enterprise Cloud (including data-residency tenants), Team and Free plans. GitHub Enterprise Server isn't supported.

Q: Does a GitHub Actions lockfile replace manually pinning actions to a SHA?
A: For onboarded workflows, mostly yes. GitHub says SHA pinning inside workflow files is no longer necessary once a repository adopts a lockfile. The exception is reusable workflow calls (jobs.<id>.uses), which the lockfile doesn't pin, so those still need a full commit SHA.

Q: Does the lockfile cover reusable workflows?
A: No. A reusable workflow's dependencies are covered by the lockfile of the repository where it's defined, not the caller's. If you call shared workflows from another repository, that repository needs its own lockfile.

Q: Does Dependabot work with actions.lock?
A: Yes, for workflows you've already onboarded. When Dependabot bumps an action there, it regenerates the matching lockfile entry in the same pull request. It won't onboard a workflow that has no entries yet.

Q: What happens if an upstream action legitimately releases a new version?
A: Branch and partial-version refs keep their locked commit and give a warning; run gh actions-lock --relock after checking the upstream history. If a locked commit is no longer in the ref's history, only --accept-moved clears it, and GitHub says never to use that flag in automation.

Quick Summary:

GitHub Actions workflow lockfiles went generally available October 28, 2026 (public preview from October 14) on Enterprise Cloud, Team and Free plans
.github/workflows/actions.lock pins every action and its transitive dependencies to a reviewed commit, but not reusable workflow calls (jobs.<id>.uses)
Install with gh extension install github/gh-actions-lock, then run gh actions-lock, and review the full diff: it also rewrites uses: refs to specific versions
Local ./ actions are a blocking error until you pass --migrate-local-actions or --ignore-local-actions
After onboarding, allowed-actions policies check locked SHAs, so tag-based allowlist entries stop matching
Use --verify in CI and --verify-local as an offline pre-commit gate; --relock advances moved refs, and --accept-moved is never for automation
Container images and floating-ref rollbacks aren't covered, and locking isn't vetting: review dependencies before you lock them

If you already pin actions by hand, a GitHub Actions lockfile is the next step. Onboard your riskiest workflow first, fix the allowlist, add --verify to CI, and keep calling reusable workflows by full SHA.

Ollama Docker Setup: GPU, Volumes and Compose

Amaresh Pelleti — Tue, 03 Nov 2026 13:37:41 +0000

---
title: "Ollama Docker Setup: GPU, Volumes and Compose"
published: true
description: "Ollama Docker setup tested on Docker 29.4.3 and Ollama 0.40.13: persistent volumes, GPU flags for NVIDIA and AMD, a Compose file and the gotchas."
tags: ollama, docker, devops, ai
canonical_url: https://devtoolhub.com/ollama-docker-setup-gpu-volumes/
---
> Originally published on [DevToolHub](https://devtoolhub.com/ollama-docker-setup-gpu-volumes/).

Running Ollama in a container takes one `docker run` command. That command also decides two things the docs bury: whether your models survive a rebuild, and whether your GPU gets used. This Ollama Docker setup guide covers both. I ran it on Docker 29.4.3 with Ollama 0.40.13 and hit three problems the one-liner doesn't warn you about.

## What Is the Minimum Ollama Docker Setup?

The minimum Ollama Docker setup is one container with a named volume and port 11434 published. The official [Ollama Docker docs](https://docs.ollama.com/docker) give this CPU-only command, and it worked as written:

bash
docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama


First, check that the API answers, then pull and run a model inside the container:

bash
curl http://localhost:11434/
docker exec -it ollama ollama run llama3.2


The first curl returns `Ollama is running`. The server logs show what hardware it found, and on my Mac the line read `inference compute id=cpu`. That log line is your first GPU check. The second check is `docker exec ollama ollama ps`, whose `PROCESSOR` column read `100% CPU` for a loaded model.

Inside the container, Ollama binds to `0.0.0.0:11434` by default. That is why the published port works without setting `OLLAMA_HOST` yourself.

## How Do Volumes Keep Ollama Models Between Containers?

A named volume mounted at `/root/.ollama` keeps your models when you delete and recreate the container. Without it, every `docker rm` throws away every model you pulled, and the next container starts empty.

I tested both cases with a 270 MB model, `smollm2:135m`:

bash

Same volume, new container: the model is still there

docker rm -f ollama
docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama
docker exec ollama ollama list # smollm2:135m listed

No volume, new container: nothing

docker rm -f ollama
docker run -d -p 11434:11434 --name ollama ollama/ollama
docker exec ollama ollama list # empty


However, the volume holds more than models. Mounting a bind directory showed four entries in it: `models`, `cache`, `id_ed25519` and `id_ed25519.pub`. Ollama generates that key pair on first start ("Couldn't find '/root/.ollama/id_ed25519'. Generating new private key" in the log). So if you lose the volume, you lose the key too, not just the downloads.

⚠️ **Note:** the volume name changes between `docker run` and Compose. Compose prefixes volume names with the project name, so a volume called `ollama` in `compose.yaml` became `comp_ollama` on my machine. Models you pulled with the plain `docker run` command above won't show up. Set `name: ollama` under the volume to pin it, as in the file further down.

## How Do You Enable GPU in an Ollama Docker Setup?

For NVIDIA, install the NVIDIA Container Toolkit on the host and register it with Docker. Then add `--gpus=all` to the run command. AMD uses the `rocm` image tag with the `/dev/kfd` and `/dev/dri` devices. Docker Desktop on macOS has no GPU passthrough at all.

### NVIDIA Ollama Docker Setup

Ollama's docs walk through the toolkit install for apt and yum, and the [NVIDIA install guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) has the current repository steps. After installing the package, point Docker at it and restart the daemon:

bash
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker


Then start the container with every GPU visible:

bash
docker run -d --gpus=all -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama


On top of that, your card needs compute capability 5.0 or higher and a driver version 550 or newer, according to the [Ollama GPU docs](https://docs.ollama.com/gpu). Cards on compute capability 5.0 through 6.2 need driver 570 or newer.

### AMD Ollama Docker Setup

bash
docker run -d --device /dev/kfd --device /dev/dri -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama:rocm


Plus, the `rocm` tag is the smaller download. Docker Hub lists the `0.40.13` amd64 image at 3.39 GB and `0.40.13-rocm` at 1.45 GB.

### Ollama Docker Setup on macOS

Ollama's FAQ is blunt: GPU acceleration is not available for Docker Desktop on macOS. On my Mac, `--gpus=all` failed with `failed to discover GPU vendor from CDI: no known GPU vendor found`. So if you want Apple GPU speed, run Ollama natively and keep Docker for everything else. [Ollama vs LM Studio](https://devtoolhub.com/ollama-vs-lm-studio/) covers the native install.

### How do you confirm the container is really using the GPU?

Run a prompt, then check `docker exec ollama ollama ps`. A `PROCESSOR` value of `100% GPU` means the model sits entirely in VRAM. `100% CPU` means no GPU was found. A split like `48%/52% CPU/GPU` means the model sits partly in each. Because of that, a healthy status proves nothing about the GPU.

## How Do You Write an Ollama Docker Compose File?

An Ollama Docker Compose file needs four things beyond the image. Those are a named volume, a localhost port binding, a healthcheck, and an optional one-shot service that pulls your model. This is the file I tested, with the GPU block split out into its own file so the base file runs anywhere:

yaml

compose.yaml

services:
ollama:
image: ollama/ollama:0.40.13
container_name: ollama
restart: unless-stopped
ports:
- "127.0.0.1:11434:11434"
environment:
OLLAMA_KEEP_ALIVE: 30m
OLLAMA_NUM_PARALLEL: 2
volumes:
- ollama:/root/.ollama
healthcheck:
test: ["CMD", "ollama", "list"]
interval: 10s
timeout: 5s
retries: 5
start_period: 10s

pull-model:
image: ollama/ollama:0.40.13
depends_on:
ollama:
condition: service_healthy
environment:
OLLAMA_HOST: ollama:11434
entrypoint: ["ollama", "pull", "smollm2:135m"]
restart: "no"

volumes:
ollama:
name: ollama

yaml

compose.gpu.yaml (NVIDIA hosts only)

services:
ollama:
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]


Start it on a CPU host with `docker compose up -d`. On a GPU host, layer the second file on top:

bash
docker compose -f compose.yaml -f compose.gpu.yaml up -d


### Why use `ollama list` as the healthcheck in an Ollama Docker setup?

The image ships without `curl` or `wget`, so the usual `curl -f http://localhost:11434` healthcheck fails with a missing binary. `ollama list` talks to the local server, so it works as a probe. With it, `pull-model` waited for the `Healthy` state, pulled the model, and exited with code 0.

### Why does the GPU block get its own file?

Because Compose refuses to start the service on a host without the NVIDIA runtime. With the `deploy` block in the single file, `docker compose up` on my Mac stopped with `could not select device driver "nvidia" with capabilities: [[gpu]]`. The Docker docs say the `capabilities` field is required. They also say `count` and `device_ids` are mutually exclusive. Check those two first if your GPU block fails on a real GPU host. See the [Compose GPU support page](https://docs.docker.com/compose/how-tos/gpu-support/) for the full field list.

### Why bind the port to 127.0.0.1?

Because `-p 11434:11434` publishes on every interface. After a plain run, `docker port` showed `0.0.0.0:11434` and `[::]:11434`. The `127.0.0.1:11434:11434` form in the file above showed `127.0.0.1:11434` only. Docker also publishes ports ahead of `ufw` rules, which its own docs cover under [Docker and ufw](https://docs.docker.com/engine/network/packet-filtering-firewalls/). If this host faces the internet, read [the Ollama VPS hardening guide](https://devtoolhub.com/ollama-production-vps-hardening/) before you publish anything.

## Which Environment Variables Matter in Docker?

Five variables cover most tuning, and you set them with `-e` on `docker run` or under `environment:` in Compose. Defaults below come from the server config line Ollama prints at startup and from the [Ollama FAQ](https://docs.ollama.com/faq).

| Variable | Default | What it does |
|---|---|---|
| `OLLAMA_KEEP_ALIVE` | `5m` | How long an idle model stays in memory |
| `OLLAMA_NUM_PARALLEL` | `1` | Parallel requests per model; RAM scales with this times the context length |
| `OLLAMA_MAX_LOADED_MODELS` | 3 per GPU, or 3 on CPU | Models loaded at once, if they fit |
| `OLLAMA_MODELS` | `/root/.ollama/models` | Where models live inside the container |
| `OLLAMA_VULKAN` | `true` | Vulkan GPU support, bundled in the image |

One more detail from the startup log: with no GPU, Ollama picked a default context of 4096 tokens (`default_num_ctx=4096`). Set `OLLAMA_CONTEXT_LENGTH` if your prompts need more, and size memory for it. [Ollama hardware requirements](https://devtoolhub.com/ollama-hardware-requirements/) has the RAM and VRAM math.

## What Breaks in an Ollama Docker Setup?

Three things broke or surprised me, and the first one costs the most.

⚠️ **`docker compose down -v` deletes the models volume, and the `-v` flag is the only difference.** Plain `docker compose down` stopped the containers and left the `ollama` volume in place. Adding `-v` removed it. Models and key pair went with it. Use it only when you want a clean slate:

bash
docker compose down # keeps the ollama volume
docker compose down -v # deletes the volume and every model in it


The other two:

- **`latest` moves fast.** Docker Hub showed `0.40.12` on 27 October, release candidates on the 28th, and `0.40.13` on the 29th. Pin the tag in Compose so a restart doesn't pull a new version while you're debugging.
- **But the image is big.** The amd64 image is 3.39 GB compressed on Docker Hub. The arm64 image used 4.29 GB on my disk once pulled. Budget for that before the first model.

## What I Did Not Test

I tested everything on a Mac with no NVIDIA, AMD or Vulkan GPU. So none of the GPU paths ran against real hardware. I did not run the NVIDIA toolkit install, the `rocm` image, Vulkan, Windows with WSL2 or Jetson. Multi-GPU selection with `device_ids` is untested too. Those steps come from the official docs I linked, and the only GPU behavior I observed was the failure messages above. Everything else in this guide ran as written.

## Frequently Asked Questions

**Q: How do I run Ollama in Docker with GPU support?**
A: On NVIDIA, install the NVIDIA Container Toolkit, run `sudo nvidia-ctk runtime configure --runtime=docker`, restart Docker, then start the container with `--gpus=all`. On AMD, use the `ollama/ollama:rocm` image with `--device /dev/kfd --device /dev/dri`. Confirm with `ollama ps`.

**Q: Where does Ollama store models in Docker?**
A: Inside the container at `/root/.ollama/models`. Mount a named volume at `/root/.ollama` so models survive container removal. The same directory holds the `id_ed25519` key pair Ollama generates on first start.

**Q: Why is Ollama using the CPU inside Docker?**
A: Ollama found no GPU the container can access. Check that you passed `--gpus=all` or the AMD devices. Check that the host driver meets the version requirement. Then run `docker exec ollama ollama ps` and look for `100% CPU`. Docker Desktop on macOS can never pass a GPU through.

**Q: Can I use Ollama in Docker on a Mac?**
A: Yes, on the CPU only. Ollama's FAQ states GPU acceleration is unavailable for Docker Desktop on macOS. Run Ollama natively for Apple GPU performance.

**Quick Summary:**
- Mount a named volume at `/root/.ollama`, or every container removal deletes your models and the key pair.
- Compose prefixes volume names, so set `name: ollama` to share one volume between `docker run` and Compose.
- Check the GPU with `docker exec ollama ollama ps`, not the container's health status.
- Put the NVIDIA `deploy` block in a separate override file, because the single-file version fails on hosts without the runtime.
- The image has no `curl`, so use `ollama list` as the healthcheck, and bind the port to `127.0.0.1` unless you mean to expose it.

Your Ollama Docker setup is now running, so point your apps at it with the [Ollama API guide](https://devtoolhub.com/ollama-api-guide/).

Podman Checkpoint CVE: How a Sandbox Bypass Works

Amaresh Pelleti — Mon, 02 Nov 2026 13:03:31 +0000

If you run Podman in production, a container image can now disable the sandbox restrictions you explicitly asked for, just by carrying one annotation. CVE-2026-94603 is a podman checkpoint handling bug that tricks podman run into treating an ordinary image as a restored checkpoint, which silently overrides flags like --cap-drop=ALL. Here's exactly how the bypass works, who it actually reaches, and what you need to patch.

What Happened: A Crafted Image Can Turn Off Your Sandbox

Podman's run command is supposed to enforce whatever sandboxing flags you pass it. Run it with --cap-drop=ALL and you expect zero Linux capabilities inside that container, no exceptions.

CVE-2026-94603 breaks that guarantee. A container image carrying a specific annotation makes Podman treat your run command as if it were restoring a checkpoint instead of starting a fresh container. Checkpoint restores are allowed to bring their own capability set with them, so your flags get silently dropped. No error, no warning — the container just starts with weaker isolation than you asked for.

The Annotation Trick Behind the Podman Checkpoint Bug

The mechanism is narrow and specific, not a sprawling exploit chain. Podman has supported checkpoint and restore since version 4.4.0. It lets you snapshot a running container's process state, including open file descriptors, memory, and capabilities. You can restore that snapshot later, even on a different host. Podman identifies a checkpoint image by the io.podman.annotations.checkpoint.runtime.name annotation baked into the image's OCI metadata.

The bug is that podman run never verified the image actually came from a real podman container checkpoint export. It only checked for the annotation's presence. So an attacker can take any ordinary image and add that one annotation. Running podman run against that image then skips your sandboxing flags. It applies whatever capability set the fake checkpoint metadata specifies instead. One annotation, no memory corruption, no privilege escalation chain — just a trust check that assumed only genuine checkpoints would ever carry that label.

Why Podman Checkpoint Restores Get Special Treatment

This isn't an arbitrary design flaw. Checkpoint and restore has a real reason to behave differently from a normal run. When you restore a checkpoint, you're not starting a fresh container — you're resuming a process that was already running with a specific set of capabilities, namespaces, and open resources. If Podman forced your current command-line flags onto a restored process, the restore would frequently fail or behave in ways the original workload never expected.

So checkpoint restores have always been allowed to carry their own privilege configuration, overriding whatever you pass on the command line. That's reasonable when the checkpoint data is genuinely trustworthy. The gap was that podman run had no way to distinguish a real checkpoint from an image someone simply labeled to look like one.

Who's Exposed: Rootful Podman Only

This is scoped tighter than the headlines suggest. Checkpoint and restore depends on CRIU (Checkpoint/Restore In Userspace), a Linux feature that needs privileges rootless containers don't have access to. Both Red Hat's CVE record and the GitHub security advisory behind it confirm the same thing directly. Rootless containers are not affected, because checkpoint and restore is unavailable in that mode.

So if you're already running Podman rootless, this bug doesn't reach you at all. That's been the project's recommended default for years, because a compromised container only affects that user's own privileges. It's specifically a rootful-Podman problem — anyone running podman as root, including CI runners, build servers, and any workflow that pulls untrusted images with elevated privileges.

The CVSS Score Depends on Who You Ask

This part is worth being precise about, because the sources genuinely disagree, and you should know why rather than just picking a number. NVD's record is sourced from the GitHub Security Advisory the Podman maintainers filed. It scores this CVSS 3.1 10.0 (Critical), vector AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H. That's a network attack vector, no privileges needed, no user interaction required.

Red Hat's own CVE record scores it lower, 8.6 (Important), vector AV:L/AC:L/PR:N/UI:R/S:C/C:H/I:H/A:H. Red Hat models the attack vector as local rather than network, and it requires user interaction. That matches the exploitation path both advisories describe. An attacker has to entice someone into running a specially crafted image. That's a local action, not a remote, zero-interaction network attack.

Both scores describe the same flaw; they disagree on how to model the attack vector. Red Hat's local, interaction-required framing better matches how you'd actually get hit in practice. But don't let the lower number talk you out of patching — a full capability-set bypass on a container you expected to be locked down is serious under either score.

Affected Versions and What the Fix Actually Changed

CVE-2026-94603 affects Podman >=4.4.0, <5.8.8 and >=6.0.0, <6.1.3. It's fixed in 5.8.8 and 6.1.3.

The fix isn't a patched validation check. Maintainers removed checkpoint-image support from podman run entirely instead. The fix commit explains the reasoning directly: checkpoints are an extremely privileged operation that podman run was never built to constrain. So Podman now rejects any checkpoint-annotated image passed to run outright. The error is generated server-side during spec processing, instead of the old client-side check this bug exploited. That closes the whole bypass category, not just the one annotation.

Checkpoint and restore itself still works after the fix, just through podman container restore, which is a deliberate, audited operation instead of something a run command can be tricked into.

How to Check Your Podman Checkpoint Exposure and Patch

Run podman version and compare it against the ranges above. If you're anywhere from 4.4.0 through 5.8.7, or 6.0.0 through 6.1.2, and you run Podman rootful, you're exposed. Upgrade to 5.8.8 or 6.1.3, whichever major line you track, and the checkpoint-annotation bypass goes away because the feature it relied on no longer exists in podman run.

If you can't patch immediately, the practical mitigation is the same advice Podman has given for years: don't run untrusted images as root. Pair that with runtime detection. A tool like Falco can flag containers that start with an unexpected capability set. That catches this kind of silent sandbox downgrade even before you patch. Pinning digests and avoiding arbitrary registry images with elevated privileges are good general habits too. Our Docker best practices guide covers these, and most of it applies just as directly to Podman.

Frequently Asked Questions

Q: Does CVE-2026-94603 affect rootless Podman?
A: No. Both Red Hat's advisory and the GitHub security advisory confirm rootless containers aren't affected, because checkpoint and restore requires CRIU privileges that rootless mode doesn't have.

Q: What's the real CVSS score for this podman checkpoint bug?
A: Sources disagree. NVD lists 10.0 (Critical) based on the GitHub advisory's network/no-interaction scoring. Red Hat lists 8.6 (Important), scoring the attack vector as local with required user interaction, which matches how the bug is actually triggered.

Q: What annotation triggers the bypass?
A: io.podman.annotations.checkpoint.runtime.name. Any image carrying it gets treated as a checkpoint restore by vulnerable versions of podman run.

Q: Can I still use checkpoint and restore after patching?
A: Yes, through podman container restore. The fix removed checkpoint handling from podman run specifically, not from Podman's checkpoint feature overall.

Q: Do I need to change anything besides upgrading Podman?
A: Not strictly, but it's worth confirming any automation that runs images as root isn't pulling from untrusted registries, since that's the actual exposure path this bug needs.

Quick Summary:

CVE-2026-94603 lets a crafted image disable your sandbox flags by faking a io.podman.annotations.checkpoint.runtime.name checkpoint annotation.
Affects Podman >=4.4.0, <5.8.8 and >=6.0.0, <6.1.3; fixed in 5.8.8 and 6.1.3.
Rootless Podman is not affected. Checkpoint and restore needs CRIU privileges rootless mode doesn't have.
NVD scores it 10.0 (Critical). Red Hat scores it 8.6 (Important) based on a local, user-interaction-required attack path. Both describe the same flaw.
The fix removed checkpoint-image support from podman run entirely rather than patching the annotation check.

The underlying lesson from this podman checkpoint bypass isn't just "upgrade." Any feature allowed to override your explicit security flags needs its trust boundary checked, not just its presence flag. Run podman version. Patch to 5.8.8 or 6.1.3 if you're rootful. And if you haven't already moved your default workflows to rootless, this is a good reason to.

AWS Secrets Manager vs Azure Key Vault vs GCP Secret Manager

Amaresh Pelleti — Thu, 29 Oct 2026 11:30:25 +0000

Pick the secrets manager that lives in the cloud your workloads already run in. The AWS Secrets Manager vs Azure Key Vault vs GCP Secret Manager choice then comes down to three things the product pages bury: how each one bills, which one rotates secrets for you, and how hard each one makes an accidental delete.

I pulled every number below from the vendors' own pricing, quota and rotation pages on 2026-10-28, and I ran the cost scenarios myself. But I did not create secrets in any of the three clouds for this post. The AWS and Azure flags match the installed CLIs (aws-cli 2.38.6, azure-cli 2.90.0). The gcloud commands come from Google's docs only, because gcloud would not start on the machine I wrote this on.

[IMAGE: articles/images/2026-10-28-aws-secrets-manager-vs-azure-key-vault-vs-gcp-secret-manager-diagram.png | alt: "Billing unit, rotation and read limits for three cloud secret stores side by side"]

What Is the Difference Between AWS Secrets Manager vs Azure Key Vault vs GCP?

All three store secret strings encrypted, keep versions, and gate reads with IAM. The differences that change your design are size and rate limits, who ships rotation, and the billing unit. AWS bills per secret, Azure bills per operation, and Google bills per active secret version.

	AWS Secrets Manager	Azure Key Vault	GCP Secret Manager
Max secret size	65,536 bytes	25 KB	64 KiB
Read limit	10,000 `GetSecretValue` per second, per Region	4,000 transactions per 10 seconds, per vault	90,000 access requests per minute, per project
Versions	100 per secret, unlabeled ones pruned	No cap, but backup fails past 500	Not stated on the quotas page
Billing unit	Per secret, plus per call	Per operation	Per active version, plus per access
Built-in rotation	Yes, via Lambda or managed rotation	No for secrets	No, notification only

Converted to seconds, AWS allows 10,000 reads per Region, but Azure allows only 400 per vault, and every operation except create shares that budget. Google sits between them at 1,500 per project.

So a fleet that cold-starts and fetches secrets at once can hit throttling on Azure first. Spreading hot secrets across vaults helps, up to the subscription-wide cap of five times the per-vault limit. That advice is my inference from Microsoft's service limits table, not Microsoft guidance.

How Much Do AWS Secrets Manager vs Azure Key Vault vs GCP Secret Manager Cost?

For 100 secrets and 1 million reads a month, list prices work out to $45.00 on AWS, $3.00 on Azure and $8.61 on GCP. AWS costs the most because it charges $0.40 per secret every month. Azure's pricing lists no storage charge for secrets, so you pay only for operations.

	Storage	Reads
AWS	$0.40 per secret per month	$0.05 per 10,000 calls
Azure (Standard)	None listed	$0.03 per 10,000 operations
GCP	$0.000082192 per active version per hour after 6 free versions	$0.03 per 10,000 accesses after 10,000 free

I took the Azure rate from Microsoft's retail prices API for East US. For Google I multiplied the hourly rate by 730 hours, which is about $0.06 per version per month.

Secrets	Reads per month	Active versions each	AWS	Azure	GCP
100	1,000,000	1	$45.00	$3.00	$8.61
1,000	10,000,000	1	$450.00	$30.00	$89.61
100	1,000,000	5	$45.00	$3.00	$32.61

The last row is the GCP trap. Google bills enabled and disabled versions, but not destroyed ones. So old versions you never destroy keep costing money. AWS avoids this because it bills per secret and prunes unlabeled versions itself once a secret passes 100.

These list prices in USD exclude free-tier credits, KMS, Pub/Sub, and the Lambda or function you run for rotation. Also check the live pricing pages before you commit.

Which Secrets Manager Rotates Secrets for You?

Only AWS rotates a secret end to end. Azure and Google deliver the trigger and leave the rotation code to you. Because of that, the gap matters more than the price difference if you manage database passwords.

AWS calls a Lambda function on your schedule. The function runs four steps: create_secret, set_secret, test_secret and finish_secret. You set the schedule with a cron() or rate() expression plus a window Duration. Secrets owned by other AWS services use managed rotation instead, which needs no Lambda. Per the rotation docs, if any step fails, Secrets Manager retries the whole rotation during the open windows.

aws secretsmanager rotate-secret \
    --secret-id MySecret \
    --rotation-lambda-arn arn:aws:lambda:<aws-region>:<account-id>:function:my-rotation-function \
    --rotation-rules "{\"ScheduleExpression\": \"cron(0 16 1,15 * ? *)\", \"Duration\": \"2h\"}"

Azure autorotates keys, not secrets. For a secret, Key Vault publishes a SecretNearExpiry event to Event Grid 30 days before expiry. Event Grid calls a function you wrote, which creates the new version and then updates the target service. Microsoft's own tutorial warns there can be a lag between those two steps. During that window, the secret in Key Vault can't authenticate. Event Grid also retries for two hours if a step fails.

GCP sends a SECRET_ROTATE message to a Pub/Sub topic and stops there. The rotation docs set rotation_period to a minimum of one hour, and next_rotation_time must sit at least five minutes ahead. Also, scheduled rotations are skipped while another is in flight. Failed sends retry for up to seven days, then the rotation is canceled.

gcloud secrets create SECRET_ID \
  --replication-policy "automatic" \
  --next-rotation-time="NEXT_ROTATION_TIME" \
  --rotation-period="ROTATION_PERIOD" \
  --topics="projects/your-project-id/topics/your-topic-name"

How Do You Create and Read a Secret in Each Cloud?

Each CLI takes a file instead of a literal value, and you should use that path. AWS warns that command history and shell utilities can expose parameters, and Google discourages piping through echo for the same reason. So pass the value from a file, then delete the file afterward.

# AWS
aws secretsmanager create-secret --name MyTestSecret --secret-string file://mycreds.json
aws secretsmanager get-secret-value --secret-id MyTestSecret --query SecretString --output text

# Azure
az keyvault secret set --name MySecretName --vault-name MyKeyVault --file /path/to/file --encoding utf-8
az keyvault secret show --name MySecretName --vault-name MyKeyVault --query value -o tsv

# GCP
gcloud secrets create SECRET_ID --replication-policy="automatic"
gcloud secrets versions add SECRET_ID --data-file="FILE_PATH"
gcloud secrets versions access latest --secret=SECRET_ID

Without a version argument, each reads the newest value, but each names it differently. AWS returns the AWSCURRENT stage by default, az keyvault secret show uses the latest version, and Google accepts latest as the version ID. For Azure access, Microsoft recommends Azure RBAC and calls access policies legacy. If you authenticate from a pipeline, our Azure service principal guide covers the identity side.

What Are the Deletion and Recovery Gotchas?

All three make deletion harder than you expect, but the rules differ. Know them before an incident, because a deleted secret can block you from recreating it under the same name.

Azure Key Vault turns soft delete on for new vaults, and you can't switch it off. Deleted secrets stay recoverable for 7 to 90 days, with 90 as the default. You set that interval only at vault creation, so you can't change it later. While a secret sits in the deleted state, you can't create another secret with the same name in that vault. Purge protection is optional and also off by default. The az keyvault create command exposes --retention-days, --enable-purge-protection and --enable-rbac-authorization.

AWS makes the secret inaccessible immediately and schedules deletion after a recovery window of at least seven days. Plus, nothing is billed for a secret marked for deletion. ⚠️ Note: --force-delete-without-recovery skips the window, and you can't undo it. Also, a replicated primary secret can't be deleted until you remove its replicas.

On Google, the replication policy is permanent: the locations can't be updated after you create the secret. With user-managed replication, an outage in one chosen region makes creates and updates fail rather than leaving data inconsistent.

Which Should You Choose: AWS Secrets Manager vs Azure Key Vault vs GCP?

Choose the store in the cloud where the workload runs, then let one of these exceptions override that.

If you need	Pick
Turnkey database-password rotation	AWS, the only one that ships it, so budget $0.40 per secret per month
Thousands of small secrets at low cost	Azure, the cheapest in every scenario above, with GCP second
Bursty reads	AWS, which gives the most headroom per Region, so plan vault layout on Azure
All three clouds or on-prem	A neutral store, because reading across clouds means managing a credential for the other cloud's IAM

For the neutral-store route, our HashiCorp Vault authentication guide covers how workloads sign in. If you already picked Azure, our Key Vault best practices post goes deeper on access control. For Terraform users, ephemeral values keep secrets out of state.

What I Did Not Test

I did not measure latency, real throttling behavior, or a full rotation run on any cloud. I also did not test organization policies or cross-account access. Everything above comes from the vendors' documentation and my own arithmetic on their list prices. Treat the cost table as a model of your bill, not a quote.

Frequently Asked Questions

Q: Which is cheaper, AWS Secrets Manager or Azure Key Vault?
A: Azure Key Vault, at list price. At 100 secrets and 1 million reads a month it costs $3.00, against $45.00 on AWS. AWS charges $0.40 per secret per month, while Azure lists no storage charge for secrets.

Q: Does Azure Key Vault rotate secrets automatically?
A: Not natively. Key Vault autorotates keys, with a minimum interval of seven days. For secrets, you wire an Event Grid event to a function that writes the new version and updates the target service.

Q: Does GCP Secret Manager rotate secrets on its own?
A: No. It publishes a SECRET_ROTATE message to a Pub/Sub topic on your schedule. You build the subscriber that creates the new version and deploys it.

Q: Can I recover a deleted secret in AWS Secrets Manager?
A: Yes, during the recovery window, which is at least seven days. Use restore-secret before the DeletionDate. A secret deleted with --force-delete-without-recovery is gone for good.

Quick Summary:

AWS bills $0.40 per secret, Azure bills per operation only, and GCP bills per active version, so old undestroyed GCP versions cost money
At 100 secrets and 1 million reads a month, list prices came to $45.00 on AWS, $3.00 on Azure and $8.61 on GCP
Only AWS rotates secrets end to end. Azure and GCP send a trigger and you write the rotation code
Azure reads are capped at 400 a second per vault, against 10,000 a second per Region on AWS
Azure soft delete can't be disabled, and Google's replication locations can't be changed after creation
I verified the AWS and Azure flags against the installed CLIs and ran no secrets in any cloud

Before you commit, plug your own secret and read counts into the three price formulas above, then decide between AWS Secrets Manager vs Azure Key Vault vs GCP Secret Manager on your numbers.

Git Reset vs Revert vs Restore: Which to Use

Amaresh Pelleti — Wed, 28 Oct 2026 12:55:03 +0000

Use git reset to move your branch back, git revert to undo a commit with a new commit, and git restore to fix files without touching history. The git reset vs revert choice comes down to one question: has anyone else pulled the commit? If yes, revert it. If no, reset it.

I ran all three on Git 2.56.0 in a scratch repo, including a push to a bare remote, so every output below is real. This guide covers the three reset modes, how to undo your last commit and keep the changes, what happens when you reset a pushed commit, and how to recover after a hard reset. It is part of our complete Git and GitHub Actions guide.

[IMAGE: articles/images/2026-10-27-git-reset-vs-revert-vs-restore-diagram.png | alt: "Decision flow for undoing a commit, picking reset, revert or restore"]

What Is the Difference Between Git Reset vs Revert vs Restore?

git reset moves the current branch to another commit. git revert adds a new commit that cancels an older one, so history stays intact. git restore copies file contents from a commit or the index into your working tree or index, and never moves the branch.

Command	What it changes	History	Safe on pushed commits
`git reset`	Branch pointer, plus index and files depending on the mode	Rewritten	No
`git revert`	Adds a new commit	Kept	Yes
`git restore`	Files in the working tree or index	Untouched	Not applicable, it touches no commits

The test repo has three commits, already pushed to a bare remote:

d026baa change app to v3, add notes
1350c0e change app to v2
7974ef4 add app v1

The last commit changes app.txt to v3 and adds notes.txt. Every example below undoes that commit in a different way.

How Git Reset Works: Soft, Mixed and Hard

A reset has three modes, and they differ in what they do with your changes. --soft moves the branch and leaves the changes staged. --mixed, the default, leaves them in your files but unstaged. --hard throws them away. According to the git reset docs, Git also sets ORIG_HEAD to the old branch tip before every reset, which matters for recovery later.

Mode	Branch	Index (staged)	Working tree
`--soft`	Moves	Unchanged	Unchanged
`--mixed` (default)	Moves	Reset to match	Unchanged
`--hard`	Moves	Reset to match	Reset to match

Here is --soft HEAD~1. Both changes stay staged, ready to recommit:

git reset --soft HEAD~1
git status -sb

## main
M  app.txt
A  notes.txt

Now --mixed, which is what a bare git reset HEAD~1 runs. The edit to app.txt stays in the file, but nothing is staged:

Unstaged changes after reset:
M   app.txt
## main
 M app.txt
?? notes.txt

Look at the last line. notes.txt was a new file in the undone commit, so after a mixed reset it shows up as untracked (??). Git has not deleted it, and git add notes.txt puts it back under version control.

⚠️ Note: git reset --hard discards every uncommitted change to tracked files across the whole repository, not just one file. Run git status first.

git reset --hard HEAD~1

HEAD is now at 1350c0e change app to v2

app.txt went back to v2 and notes.txt was gone. An untracked file I had left in the folder survived, because a hard reset only touches files Git tracks.

Git Reset vs Revert for Your Last Commit: Keeping Your Changes

To undo your last commit and keep the work, run git reset --soft HEAD~1 if you want the changes staged, or git reset HEAD~1 if you want them unstaged. Both leave your files exactly as they were. Only the commit disappears.

git reset --soft HEAD~1   # changes stay staged
git reset HEAD~1          # changes stay in files, unstaged

This only works for commits nobody else has pulled. The branch moves back, so a commit you already pushed no longer matches the remote.

Git Reset vs Revert After You Push

After you push, use git revert. A reset on a pushed commit makes your branch diverge from the remote, and the push fails. I reset the pushed branch with --hard HEAD~1 and tried to push:

 ! [rejected]        main -> main (non-fast-forward)
error: failed to push some refs to '../remote.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart.

Only a force push gets that through, and a force push rewrites history for everyone who already pulled it. Whether that is even allowed depends on your workflow, so check how Git Flow, GitHub Flow and trunk-based development treat shared branches.

Revert avoids the problem. It adds a commit instead of removing one:

git revert --no-edit HEAD
git push origin main

bccdd1d Revert "change app to v3, add notes"
d026baa change app to v3, add notes
1350c0e change app to v2
7974ef4 add app v1
To ../remote.git
   d026baa..bccdd1d  main -> main

The push worked as a plain fast-forward. app.txt was back to v2 and notes.txt was gone, but the original commit and the revert both stay in the log. That record is the point, because anyone who pulled d026baa can see exactly what undid it.

Revert also works on a commit that is not the latest. git revert 1350c0e reverted change app to v2 from further back in the log and added a new commit on top.

How Git Restore Fixes Files Without Moving HEAD

git restore changes files, not commits. By default it overwrites your working tree copy. With --staged it only touches the index. With --source it pulls the file from any commit. The git restore docs describe the working tree as the default location when you pass neither --staged nor --worktree.

⚠️ Note: git restore <file> throws away your unstaged edits to that file, and Git does not ask first. It exited with code 0 and printed nothing.

echo "oops" >> app.txt
git restore app.txt        # edit gone, file is back to v2

To unstage a file but keep your edit:

git add app.txt
git restore --staged app.txt
git status -sb

## main
 M app.txt

The older git reset app.txt gave the same status in my test. Use whichever you remember, but restore --staged says what it does.

To pull one file from an old commit without moving the branch:

git restore --source=7974ef4 app.txt
cat app.txt                # v1

The file now shows as modified (M app.txt). To undo that, run git restore --source=HEAD --staged --worktree app.txt.

Can You Recover After a Git Hard Reset?

You can recover committed work, but not uncommitted edits. A hard reset only moves the branch, so the old commit still exists. git reset --hard ORIG_HEAD jumps straight back:

git reset --hard ORIG_HEAD

HEAD is now at d026baa change app to v3, add notes

git reflog lists every earlier position of HEAD, so you can also reset to HEAD@{1}. In my test the reflog showed d026baa HEAD@{1}: commit: change app to v3, add notes right after the reset. For more recovery steps, see our Git troubleshooting and recovery guide.

Uncommitted work is different. I appended a line to app.txt, ran git reset --hard, and the line vanished. The newest reflog entry was just reset: moving to HEAD, because Git never recorded that edit. So commit or stash before you reset.

If you want a reset that refuses to lose local edits, use --keep. With a local change in app.txt, git reset --keep HEAD~1 stopped with error: Entry 'app.txt' not uptodate. Cannot merge. instead of overwriting the edit.

Reverting Merge Commits and Resolving Conflicts

A merge commit has two parents, so git revert needs to know which side to keep. Without -m, Git stops:

error: commit 33e0fc4264dac85dea5f1897db2b5e31e9478c20 is a merge but no -m option was given.
fatal: revert failed

Pass -m 1 to keep the first parent, which is the branch you merged into. The git revert docs say parent numbers start at 1.

git revert --no-edit -m 1 HEAD

In my test that removed the merged feature's file (feat.txt) and kept the work from main.

Reverts can also conflict. I reverted an older commit that created c.txt after a later commit had changed the file:

CONFLICT (modify/delete): c.txt deleted in parent of a26f5ed (add c.txt line A) and modified in HEAD.
error: could not revert a26f5ed... add c.txt line A

git status showed UD c.txt. Fix the file and run git revert --continue, or back out with git revert --abort, which restored the clean branch. For the usual conflict markers, see our merge conflict guide.

Git Reset vs Revert vs Restore: Which to Use?

Pick by situation, not by habit. Keep this table next to your Git cheat sheet:

You want to	Use
Undo your last local commit, keep the work staged	`git reset --soft HEAD~1`
Undo your last local commit, keep the work unstaged	`git reset HEAD~1`
Undo your last local commit and discard the work	`git reset --hard HEAD~1`
Undo a commit you already pushed	`git revert <sha>`
Undo a merge you already pushed	`git revert -m 1 <merge-sha>`
Unstage a file	`git restore --staged <file>`
Discard edits to a file	`git restore <file>`
Get an old version of one file	`git restore --source=<sha> <file>`

Frequently Asked Questions

Q: What is the difference between git reset and git revert?
A: git reset moves your branch to an earlier commit and rewrites history. git revert adds a new commit that cancels an earlier one and keeps history intact. Reset suits local commits nobody has pulled, and revert suits anything pushed.

Q: Does git reset delete commits?
A: Not right away. The commits drop off your branch, but they stay reachable through git reflog and ORIG_HEAD. In my test, git reset --hard ORIG_HEAD brought the commit straight back.

Q: What does git reset HEAD~1 do?
A: It moves your branch back one commit and unstages that commit's changes. Your files stay as they were, and new files from the commit become untracked.

Q: Can I revert a commit that is not the latest?
A: Yes. git revert <sha> works on any commit and adds a new commit on top. It can conflict if later commits touched the same lines.

Q: How do I undo a git reset?
A: Run git reset --hard ORIG_HEAD right after the reset, or find the old commit in git reflog and reset to it. This only recovers committed work.

Quick Summary:

git reset moves your branch, git revert adds a commit that cancels one, and git restore fixes files without moving anything
Reset a commit only if nobody has pulled it. Resetting a pushed commit made my push fail with non-fast-forward
--soft keeps changes staged, --mixed keeps them unstaged, and --hard discards them
git reset --hard ORIG_HEAD recovers committed work, but uncommitted edits are gone for good
Reverting a merge needs -m 1, and git revert --abort backs out of a conflict
git restore <file> discards unstaged edits without asking

Before your next undo, settle the git reset vs revert question first: run git log --oneline -3 and check whether the commit is on the remote. If it is, use git revert.

Ansible Lint GitHub Actions: Fail PRs on Bad Playbooks

Amaresh Pelleti — Tue, 27 Oct 2026 12:55:41 +0000

I ran ansible-lint against a four-task playbook that looked fine at a glance. It reported 14 violations and exited with code 2. Setting up that same check as an Ansible Lint GitHub Actions workflow takes about ten lines of YAML, so the broken playbook never reaches main. This guide covers the workflow, the profile you should enforce, and a trap with ignore files that I hit while testing.

Everything below was run with ansible-lint 26.10.1 and ansible-core 2.21.5 on Python 3.14.

Why Add an Ansible Lint GitHub Actions Check?

An Ansible Lint GitHub Actions check turns style and safety rules into a required check on every pull request. A reviewer no longer has to spot a missing mode: on a copy task or a shell call that runs on every play. The check fails, the PR stays red, and the author fixes it before anyone reads the diff.

It also catches the quiet problems. For example, tasks that report "changed" on every run and state: latest installs that upgrade packages unpredictably. Both break idempotency, which is the property that makes a playbook safe to re-run.

What Ansible Lint Catches in a Real Playbook

First, here is the playbook I tested. It installs nginx, copies a config, restarts the service, and unpacks a tarball:

- name: Configure web servers
  hosts: web
  become: true
  tasks:
    - name: install nginx
      apt:
        name: nginx
        state: latest

    - name: Copy site config
      copy:
        src: nginx.conf
        dest: /etc/nginx/nginx.conf

    - shell: systemctl restart nginx

    - name: Fetch release tarball
      shell: curl -s https://example.com/app.tgz | tar xz -C /opt

Running ansible-lint site.yml printed this summary line and exited with code 2:

Failed: 14 failure(s), 0 warning(s) in 1 files processed of 1 encountered. Last profile that met the validation criteria was 'min'.

The 14 violations came from nine rule IDs. Four are fqcn hits, one per short module name. The rest are the ones that matter in production:

Unpinned installs trip package-latest: "Package installs should not use latest."
The copy task has no mode, which trips risky-file-permissions.
Calling systemctl and curl through shell trips command-instead-of-module, because the systemd and get_url modules exist for that.
Both shell tasks report changed on every run (no-changed-when).
A pipe without pipefail means a failed curl can still produce a green task (risky-shell-pipe).
One task has no name at all (name[missing]).

A reviewer skimming this in a PR would probably approve it. The linter, however, doesn't skim.

The Minimal Ansible Lint GitHub Actions Workflow

The official action takes a handful of inputs. Per the ansible-lint installation docs, they are args, setup_python, python_version (default 3.14), working_directory, and requirements_file. Create .github/workflows/ansible-lint.yml:

name: ansible-lint
on:
  pull_request:
    paths:
      - "**.yml"
      - "**.yaml"
      - ".ansible-lint"

permissions:
  contents: read

jobs:
  lint:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: ansible/ansible-lint@9bce2bfb8f4a984e6b13767bc0d6bf0a49492164 # v26.10.1
        with:
          args: "--profile production"
          requirements_file: requirements.yml

Three details here are deliberate.

First, the action is pinned to a commit SHA. The docs example uses @main, which means your lint rules change whenever upstream merges something. The SHA above is the v26.10.1 tag, which I resolved through the GitHub API. If you're tightening the rest of your pipeline too, the GitHub Actions security guide explains why tags are a weak pin.

Second, permissions: contents: read keeps the token minimal, because a linter needs nothing more.

Third, requirements_file installs the roles and collections your playbooks import. Skip it and you get load failures on any playbook that uses a collection module. Keep the setting in the file, not in extra action inputs. The docs state that extra options won't be added to the action, so behavior changes go in a .ansible-lint config file instead.

For a refresher on how workflow files fit together, see the workflow YAML explainer.

Which Profile Should You Enforce?

ansible-lint groups rules into six cumulative profiles: min, basic, moderate, safety, shared, and production. Each one extends the one before it, according to the profiles documentation. Pick one with --profile on the command line or profile: in .ansible-lint.

I ran the same broken playbook against each profile:

Profile	Failures	Exit code
`min`	0	0
`basic`	4	2
`moderate`	5	2
`safety`	8	2
`production`	14	2

The min profile only checks that Ansible can load the file. Because our playbook passes it, the default run said the last profile met was min. That is a low bar, so don't stop there.

For a new repo, start at production. In practice that is the setting most teams end up on anyway. For an existing one, start at basic and move up one profile at a time as you clean up. Specifically, the safety profile is where the rules about latest, risky permissions, and shell pipes show up, so it's the first level that protects you from real incidents.

The fixed version of the playbook passes --profile production with exit code 0:

- name: Configure web servers
  hosts: web
  become: true
  tasks:
    - name: Install nginx
      ansible.builtin.apt:
        name: nginx
        state: present

    - name: Copy site config
      ansible.builtin.copy:
        src: nginx.conf
        dest: /etc/nginx/nginx.conf
        mode: "0644"
      notify: Restart nginx

    - name: Download release tarball
      ansible.builtin.get_url:
        url: https://example.com/app.tgz
        dest: /tmp/app.tgz
        mode: "0644"

    - name: Unpack release tarball
      ansible.builtin.unarchive:
        src: /tmp/app.tgz
        dest: /opt
        remote_src: true

  handlers:
    - name: Restart nginx
      ansible.builtin.service:
        name: nginx
        state: restarted

The restart moved into a handler. As a result, nginx only restarts when the config actually changes. That one change removes a no-changed-when hit and makes the play idempotent.

What `--fix` Actually Fixes

ansible-lint --fix rewrites the file in place. On my test playbook it cut the failures from 14 to 8. It capitalized the task name, added ansible.builtin. to every module, and turned shell: systemctl restart nginx into ansible.builtin.command.

However, it could not fix the rest. The log said it plainly: "Rule specific fix not applied for: name[missing]". It also left latest, the missing mode, and both no-changed-when hits alone, because those need a human to decide what the right behavior is.

⚠️ Note: --fix modifies your files. Run it on a clean branch and read the diff before you commit. Don't run it in CI and push the result back unattended.

Adopting Ansible Lint GitHub Actions Checks on an Existing Repo

Turning on a strict check for a repo with hundreds of old violations makes every PR red on day one. The usual answer is ansible-lint --generate-ignore, which writes a .ansible-lint-ignore file. Each line holds a filename and a rule ID, and ansible-lint stops failing on those pairs.

Here is what that file looked like for my test playbook:

site.yml command-instead-of-module
site.yml command-instead-of-shell
site.yml fqcn[action-core]
site.yml name[casing]
site.yml name[missing]
site.yml no-changed-when
site.yml package-latest
site.yml risky-file-permissions
site.yml risky-shell-pipe

After generating it, the same run reported Passed: 0 failure(s), 14 warning(s) and exited with code 0. Because the check is green, you can merge the workflow and start enforcing rules on new code.

Why an Ignore File Can Hide New Violations

The ignore file works per file and per rule. It does not work per line. I found this out by appending a new task to site.yml that ran rm -rf /tmp/x through ansible.builtin.command with no changed_when. That is a fresh no-changed-when violation.

As a result, the run printed Passed: 0 failure(s), 15 warning(s) and exited with code 0. The new violation showed up as a warning marked # ignored, and the PR stayed green.

This means an ignore entry for no-changed-when in a file silences that rule for every future task in that file. A few ways to deal with it:

Treat .ansible-lint-ignore as debt, not a setting. Review it in PRs and shrink it over time.
Prefer fixing a rule across the repo, then deleting its ignore lines, over leaving ignores in place.
Don't expect --strict to help. It makes warnings fail the run, and ignored violations count as warnings. With the ignore file in place, --strict exited with code 2 on my test, so it can't gate new code while old ignores exist.
Put new playbooks in new files. Rules ignored for legacy.yml don't apply to new.yml.

Running Ansible Lint Locally Before Your GitHub Actions Run

Plus, a failing PR check is slower than a failing terminal. Install the same version the workflow uses and run it before you push:

python3 -m venv .venv
.venv/bin/pip install ansible-core ansible-lint
.venv/bin/ansible-lint --profile production

⚠️ Note: use Python 3.14 or older. On Python 3.15, ansible-core 2.21.5 printed a warning that it supports Python up to 3.14, and ansible itself crashed with module 'dataclasses' has no attribute '_is_type'. The GitHub Action defaults to 3.14, so CI won't hit this, but a fresh laptop with the newest Python might.

ansible-lint also supports several output formats through -f: brief, full, md, json, codeclimate, quiet, pep8, and sarif. Use pep8 for editor integration and codeclimate if your CI tool consumes it.

If you manage infrastructure with both tools, linting is where Ansible and Terraform converge. The Terraform docs action follows the same pattern of a single CI job that fails the PR. For picking between the tools themselves, see OpenTofu vs Terraform. And if you want the wider picture of what breaks pipelines, the GitHub Actions incidents guide is the place to start.

Frequently Asked Questions

Q: Does ansible-lint fail the build by default?
A: Yes. ansible-lint exits with code 2 when it finds violations, and a non-zero exit fails the GitHub Actions step. Warnings from your warn_list or ignore file don't fail the run unless you pass --strict.

Q: Which ansible-lint profile should I use in CI?
A: Use production for new repos and basic for existing ones, then raise it one level at a time. The profiles are cumulative, so safety includes everything in basic and moderate.

Q: Should I pin the ansible-lint action to a tag or a SHA?
A: Pin to a commit SHA and leave the tag in a comment. Tags can move, and the official docs example uses @main, which changes under you. Dependabot can bump a SHA-pinned action for you.

Q: Can ansible-lint fix problems automatically?
A: Partly. ansible-lint --fix handled 6 of 14 violations on my test playbook, mostly module names and casing. It also can't decide changed_when conditions, file modes, or package versions for you.

Q: Why does my CI check pass when I know a task is wrong?
A: Check .ansible-lint-ignore first. An entry there silences a rule for the whole file, so new violations of that rule pass as warnings.

Quick Summary:

ansible-lint exits with code 2 on violations, so it works as a required PR check with no extra scripting
A four-task test playbook produced 14 violations across nine rule IDs; --profile min passed, production failed all 14
Use ansible/ansible-lint pinned to a commit SHA (v26.10.1 is 9bce2bfb8f4a984e6b13767bc0d6bf0a49492164), not the docs example's @main
Pass requirements_file so roles and collections install before linting
--fix resolved 6 of 14 and left the judgment calls; read the diff before committing
--generate-ignore is per file and per rule, so new violations of an ignored rule pass silently, and --strict fails while ignores exist
Local installs need Python 3.14 or older for ansible-core 2.21.5

Start with --profile basic on your current repo, generate the ignore file once, and commit the Ansible Lint GitHub Actions workflow. Then delete one ignore line per week until the file is empty.

Istio AuthorizationPolicy Bypass: HTTP/2 Method-Case Bug

Amaresh Pelleti — Mon, 26 Oct 2026 12:55:30 +0000

Istio AuthorizationPolicy rules that block or allow traffic by HTTP method just got a real asterisk. ISTIO-SECURITY-2026-007 fixes a case bug in that matcher. Published October 15, 2026, it covers one specific issue: an HTTP/2 request with a lowercased method name could slip past a method-based rule entirely. If you run DENY rules with methods, or ALLOW rules with notMethods, check this today. Don't wait for your next patch window.

What ISTIO-SECURITY-2026-007 Fixes in Istio AuthorizationPolicy

The advisory bundles five fixes. The loudest is a critical Envoy Brotli decompressor buffer overflow, CVE-2026-111497 (CVSS 9.2). Two Envoy crash bugs on CONNECT requests without a :path header (GHSA-8vc2-jrm4-835w, CVSS 7.5, and GHSA-47vj-9r25-wv5j, CVSS 6.5) and an ambient-mode istiod denial-of-service bug (GHSA-7p2q-4xvg-vxc6, CVSS 7.7, IP-addressed waypoints only) round it out.

The other is the one this piece covers: GHSA-w44g-8m76-8gc5, CVSS 7.4 (High). Istio titled it "AuthorizationPolicy method rules are bypassed over HTTP/2 by changing the method case."

There's no CVE number attached to this one yet. Only the GHSA ID exists, so don't expect it in a CVE search anytime soon. The affected range is 1.31.0–1.31.1, 1.30.0–1.30.5, and 1.29.0–1.29.8.

How the HTTP/2 Method-Case Bypass Works

An Istio AuthorizationPolicy can use a DENY rule with methods, or an ALLOW rule with notMethods. Both compile down to an Envoy :method matcher. That matcher is case-sensitive. So a rule meant to block POST only checks for the literal uppercase string POST.

Here's where the codecs diverge. Envoy's HTTP/1.1 codec normalizes and rejects non-uppercase methods before the request reaches the authorization filter. A lowercase post never even gets to test the policy. HTTP/2 doesn't enforce that same restriction at the codec layer. A request arriving as post instead of POST passes straight through the case-sensitive matcher. The policy that was supposed to block it does nothing.

That's the whole bug. One protocol enforces method casing before policy evaluation; the other doesn't. The policy logic assumed both would behave the same way. Policies that only use ALLOW rules with an explicit methods list aren't affected. The request still has to match an allowed value to get through. The negative-match cases — DENY + methods, ALLOW + notMethods — are different: there, a non-match means "let it through."

Why Istio AuthorizationPolicy Bypasses Keep Happening

This is at least the fifth time a matching-logic gap has let traffic slip past an Istio AuthorizationPolicy rule. Every time, the rule was supposed to catch it. Each one has been a different field. But the shape of the bug is the same: the policy compiler assumes a normalized value. Somewhere downstream, that assumption breaks.

CVE-2020-16844 (ISTIO-SECURITY-2020-009, CVSS 6.8) — DENY rules with wildcard suffixes on source principals or namespaces never denied TCP callers.
CVE-2021-39155 (ISTIO-SECURITY-2021-008) — the Host header comparison was case-sensitive, even though RFC 4343 says hostnames should compare case-insensitively. That gap let Httpbin.Foo bypass a rule written for httpbin.foo.
CVE-2021-39156 (same ISTIO-SECURITY-2021-008 advisory) — a #fragment appended to a request path could bypass path-based authorization checks.
CVE-2022-21679 (ISTIO-SECURITY-2022-001, CVSS 6.8) — mixing a 1.12 control plane with 1.11 data plane proxies broke hosts and notHosts matching.

None of these are the same code path. But they're all the same category: a string comparison in an AuthorizationPolicy field that quietly assumed normalized input. If you've treated method, host, or path matchers as airtight, this history says otherwise.

Who Is Affected: Versions and Deployment Modes

You're exposed if two things are both true. Your Istio AuthorizationPolicy rules use DENY with methods, or ALLOW with notMethods. And clients can reach the workload over HTTP/2.

That covers both sidecar mesh deployments and ambient mode. Both enforce L7 authorization through Envoy proxies that speak HTTP/2 to upstream services and to each other.

It doesn't matter whether the attacker is external or an already-compromised pod elsewhere in the cluster. The bypass works the same way either direction. That's exactly why relying on a single enforcement layer is risky. Our guide on Kubernetes node pools and networking is useful here too. It maps where traffic actually flows before you decide where policy should live.

Patched Versions and the Upgrade Path

Istio shipped fixes in 1.31.2, 1.30.6, and 1.29.9. The 1.29 branch's fix is also its final release. That line is done taking patches. Treat 1.29.9 as a stopgap, and plan your move to 1.30 or 1.31 regardless.

Roll the whole mesh, not just the control plane. The same release carries Envoy fixes, so restart your sidecars — or ztunnels and waypoints, on ambient — to pick up the patched proxy build, and don't stop at istiod.

How to Audit Your Istio AuthorizationPolicy Rules Right Now

You don't need to wait for a scanner to tell you if you're exposed. Pull every policy in the cluster and grep for the two fields that matter:

kubectl get authorizationpolicies.security.istio.io -A -o yaml | grep -B5 -E "methods:|notMethods:"

For each hit, check the action field on that policy. If it's DENY and lists methods, or it's ALLOW and lists notMethods, that rule relied on a case-sensitive match. HTTP/2 traffic could dodge it until you upgraded. If every method-based rule you find is an ALLOW with an explicit methods list, you were never affected. Patch anyway — the next matcher bug in this list might also hit a different field.

Mitigations If You Can't Upgrade Yet

The cleanest workaround doesn't need a code change to Istio at all. Rewrite DENY + methods rules as ALLOW rules with an explicit, uppercase methods list instead. Per the advisory itself, policies that only use ALLOW with an explicit methods list were never affected. A request still has to match a listed value to get through. There's no negative-match gap to exploit.

If you can't restructure the policy quickly, you can also restrict which workloads accept HTTP/2 from untrusted sources. That's a narrower fix than it sounds. gRPC and most modern service-to-service traffic run on HTTP/2 by default. Upgrading is still the actual fix; the policy rewrite is a bridge, not a replacement.

The Takeaway: Don't Rely on Istio AuthorizationPolicy Alone

Five bypasses across six years in the same subsystem is a pattern, not bad luck. That's a reasonable argument for not putting all your access control eggs in one AuthorizationPolicy basket. Layer a Kubernetes NetworkPolicy underneath your mesh's L7 rules. That way, a matcher bug at the application layer doesn't also mean the connection itself was never restricted.

Runtime visibility helps too. A tool like Falco can flag unexpected traffic at the kernel level, no matter what Envoy's policy layer missed. If you're studying for a Kubernetes security certification, our CKA vs CKAD vs CKS breakdown covers the access-control picture. It shows where authorization and network segmentation fit into the certification track.

For now: patch to 1.31.2, 1.30.6, or 1.29.9. Audit your existing Istio AuthorizationPolicy rules for DENY+methods or ALLOW+notMethods. And don't treat method-based policy as your only line of defense.

Frequently Asked Questions

Q: Does this bug have a CVE number?
A: Not as of this advisory's publication. It's tracked only under the GitHub Security Advisory ID GHSA-w44g-8m76-8gc5, CVSS 7.4 (High). A CVE may get assigned later, but don't rely on a CVE-only vulnerability feed catching it yet.

Q: Is my cluster affected if I only use ALLOW rules with an explicit methods list?
A: No. The advisory is specific: ALLOW rules with an explicit methods list were never affected. It still has to match a value in that list. The bug only hits the negative-match cases: DENY with methods, or ALLOW with notMethods.

Q: Does HTTP/1.1 traffic need the same audit?
A: No, not for this specific bug. Envoy's HTTP/1.1 codec rejects non-uppercase methods before the request reaches the authorization filter. So the case-mismatch bypass doesn't apply here. HTTP/2 is the exposed path.

Q: Are the other fixes in the same advisory related to this bypass?
A: No. ISTIO-SECURITY-2026-007 bundles five separate fixes: this method-case bypass (GHSA-w44g-8m76-8gc5), a critical Envoy Brotli overflow (CVE-2026-111497), two Envoy CONNECT crash bugs, and an ambient-mode istiod denial-of-service bug (GHSA-7p2q-4xvg-vxc6) that needs an IP-addressed waypoint. They're unrelated to each other, and patching to the fixed versions covers all of them.

Quick Summary:

ISTIO-SECURITY-2026-007 (Oct 15, 2026) fixes GHSA-w44g-8m76-8gc5, CVSS 7.4 — no CVE assigned yet
The bug: Istio AuthorizationPolicy's :method matcher is case-sensitive, so HTTP/2's lowercase methods slip past DENY/notMethods rules
Affected: DENY rules with methods, or ALLOW rules with notMethods, on 1.31.0–1.31.1, 1.30.0–1.30.5, 1.29.0–1.29.8
Not affected: ALLOW rules with an explicit methods list
Patched in 1.31.2, 1.30.6, and 1.29.9 (1.29's final release — plan your move off that branch)
Same advisory also fixes a critical Envoy Brotli overflow (CVE-2026-111497, CVSS 9.2) — the upgrade covers it
This is the fifth AuthorizationPolicy matching bypass in Istio's history (CVE-2020-16844, CVE-2021-39155, CVE-2021-39156, CVE-2022-21679) — treat method/host/path matchers as a layer, not the whole wall, and back them with NetworkPolicy and runtime detection

The real fix is upgrading. But if this is the fifth time a string comparison inside Istio AuthorizationPolicy has let traffic through it shouldn't have, the bigger lesson is to stop treating that one policy object as your only gate.

MCP vs A2A vs AG-UI: The Protocol Stack, Fact-Checked

Amaresh Pelleti — Fri, 23 Oct 2026 12:30:14 +0000

MCP vs A2A vs AG-UI is the comparison chart making the rounds right now, and the framing is right — these are three different, complementary layers, not competing standards. But a couple of its headline numbers are either stale or don't hold up against the protocols' own sources, and it skips the actual news: MCP's July 2026 spec update is a real breaking-change event, not a one-word "stateless" bullet point. Here's what each protocol actually does, fact-checked against their own docs and GitHub repos, plus what the chart got right and what's worth correcting. For the agent concepts underneath all three, see our AI agents explained guide.

The Three Protocols, What Each One Actually Connects

The "vs" in every comparison title is misleading — you don't pick one. Each protocol solves a different connection problem, and a real agentic system typically uses all three at once:

MCP (Model Context Protocol) — built by Anthropic — connects an agent to tools and data. Anthropic's own docs describe it as a standardized way to connect AI applications to external systems, "like a USB-C port for AI applications." If your agent needs to read a file, query a database, or call an API, this is the layer — see our MCP registry breakdown for how big that ecosystem already is.
A2A (Agent2Agent Protocol) — built by Google, now governed by the Linux Foundation — connects one agent to another. It's how two independent agents, possibly built by different teams on different frameworks, discover each other and hand off work.
AG-UI (Agent-User Interaction Protocol) — built by CopilotKit and its open-source community, not Google (a detail the viral chart gets right, worth double-checking since AG-UI's name invites confusion with Google's A2A) — connects an agent to the human watching it work. It's an event-based protocol for streaming an agent's state and output into a real UI, not a chat log.

None of these three compete for the same job. A production agent that reads your CRM (MCP), delegates a sub-task to a specialist agent (A2A), and shows a human the live progress bar while it works (AG-UI) is using all three simultaneously.

MCP's July 2026 Spec Update Was Bigger Than "Stateless"

The chart's MCP row says "Stateless spec, July 2026" and leaves it there. That's the right headline, but it's doing a lot of work in one line — per MCP's own 2026-07-28 changelog, this is the largest rewrite since launch: protocol-level sessions and the Mcp-Session-Id header are gone, the initialize handshake is gone, and Roots, Sampling, and Logging are now formally deprecated with a twelve-month removal window. We already covered the full breaking-change list and a real server-migration checklist in MCP Server Authentication: What the 2026-07-28 Spec Broke — if you're migrating an MCP server, that's the piece to work from.

What's actually new to check, and what the chart doesn't carry at all: per Anthropic's own announcement, MCP is at 400M monthly SDK downloads as of that July 28 update — a real, sourced number that's meaningfully below the chart's "close to 500M" claim, and the real reason for the stateless move is architectural: "MCP moves from a bidirectional stateful protocol to a request/response model. Servers can now deploy on serverless and edge infrastructure" — something the old session-pinned design couldn't do cleanly.

A2A's Real Status — v1.0, Signed Agent Cards, and a Number Worth Correcting

The chart says A2A hit "v1.0 with signed Agent Cards, March 2026." The version and date both check out — A2A's GitHub releases show v1.0.0 published March 12, 2026, and the live spec's section 8.4 ("Agent Card Signing") does define canonicalization, signature format, and signature verification requirements so agents can cryptographically sign their Agent Cards for authenticity. Worth knowing if you're building against it today: v1.0 isn't the current patch anymore — v1.0.1 shipped May 28, 2026 with HTTP binding and TaskStatus fixes.

Governance checks out too: Google originally built A2A and donated it to the Linux Foundation, and as of August 20, 2026 it formally joined the Agentic AI Foundation (AAIF) — the same body that already hosts MCP — putting both protocols under one neutral governance structure instead of two separate vendor-led ones. A2A's Technical Steering Committee includes representatives from AWS, Cisco, Google, IBM Research, Microsoft, Salesforce, SAP, and ServiceNow.

The one number worth double-checking: the chart lists A2A at "150+ organizations behind it." I couldn't find a primary source attributing that specific figure to A2A alone. What I could verify, directly from the Linux Foundation's own press release, is AAIF's total membership — the body that now governs both A2A and MCP — which states it "grows to 247 member organizations with the addition of 57 new members over the past three months." That's a materially different, larger number than "150+," just measuring the whole foundation rather than one protocol's backers specifically. If the chart's figure is from an earlier AAIF member count, it's stale now.

AG-UI's Real Adoption — 16.7k Stars and a Fourth Integration the Chart Skips

AG-UI's chart row says "15K+ GitHub stars." Checking the ag-ui-protocol/ag-ui repo directly, it's actually at 16.7k stars — the chart's number is accurate but already a bit behind. More interesting: the chart lists three 1st-party framework integrations (Google ADK, Microsoft Agent Framework, AWS AgentCore). The repo documents a fourth — AWS Strands Agents is also officially supported, alongside AWS Bedrock AgentCore, not instead of it. If you're picking an agent framework specifically because it has AG-UI support baked in, Strands is a real option the chart doesn't mention.

Where ACP Went

The chart's footer note — "Where's ACP? IBM merged it into A2A in August 2025" — checks out exactly. IBM Research's Agent Communication Protocol, built to power its BeeAI platform, overlapped heavily with A2A (both covered agent-to-agent discovery and messaging). The original ACP repository itself confirms it: archived August 27, 2025, with a banner reading "ACP is now part of A2A under the Linux Foundation!" and a link to the migration guide. If you see ACP referenced in older material, it's a dead end now — the real destination is A2A.

Do You Need All Three? A Practical Decision Guide

Your agent needs to read or write something external — a CRM, your docs, a GitHub repo, a database: that's MCP. One server, any MCP-compatible client can use it — our best MCP servers by category guide is a starting point.
Your agent needs to hand off a task to a different, independently-built agent — possibly on a different framework, possibly a different vendor: that's A2A. The Agent Card is how the other side learns what your agent can do before the handoff.
A person needs to watch your agent work and approve or steer its steps in real time, not just read a final answer: that's AG-UI. It's the layer between the agent's internal state and whatever UI framework renders it.
You're building a single-tool integration with no multi-agent handoff and no live UI — you may genuinely only need MCP. Don't add A2A or AG-UI to a system that doesn't have another agent or a human-in-the-loop UI to connect to.

Frequently Asked Questions

Q: Are MCP, A2A, and AG-UI competing standards?
A: No. They connect different things — MCP connects an agent to tools and data, A2A connects one agent to another, AG-UI connects an agent to the person watching it. A single system can use all three at once.

Q: What actually changed when MCP went stateless in July 2026?
A: Sessions, the initialize handshake, and three features (Roots, Sampling, Logging) all changed at once — see our full MCP server authentication breaking-change checklist for the complete list. The number worth knowing that isn't in that piece: Anthropic's own blog puts MCP at 400M monthly SDK downloads as of this update.

Q: Who governs MCP and A2A now?
A: Both are hosted projects under the Agentic AI Foundation (AAIF), part of the Linux Foundation. A2A joined AAIF on August 20, 2026, after Google donated it; MCP was already a founding AAIF project. AAIF's own press release puts total membership at 247 organizations.

Q: Does AG-UI only work with Google, Microsoft, and AWS AgentCore?
A: Those three are 1st-party supported, but so is AWS Strands Agents — a fourth framework with official AG-UI support that's easy to miss if you're only going by popular comparison charts.

Q: What happened to ACP (IBM's Agent Communication Protocol)?
A: It merged into A2A. The original repository was archived August 27, 2025, with a notice directing developers to A2A's migration guide.

Quick Summary:

MCP, A2A, and AG-UI are complementary layers (tools, agent-to-agent, agent-to-human), not competing alternatives
MCP's July 28, 2026 spec update (sessions, the initialize handshake, Roots/Sampling/Logging all changed) is covered in full in our MCP server authentication piece
Per Anthropic's own blog, MCP is at 400M monthly SDK downloads as of that update — not "close to 500M"
A2A hit v1.0.0 in March 2026 (now on patch v1.0.1) with real signed Agent Cards; AAIF's own total membership is 247 organizations, a different number than "150+"
AG-UI is at 16.7k GitHub stars with four 1st-party framework integrations (Google ADK, Microsoft Agent Framework, AWS Bedrock AgentCore, and AWS Strands Agents)
ACP (IBM) merged into A2A in August 2025 and is a dead end if you see it referenced

The real answer to MCP vs A2A vs AG-UI is: pick protocols by the connection you actually need, not by which chart you saw first — and if you're touching an MCP integration built before July 2026, check it against the real breaking-change list above before assuming "stateless" just means a minor version bump.

macOS 27 fm CLI: What Apple's Built-In Model Can Do

Amaresh Pelleti — Thu, 22 Oct 2026 12:48:08 +0000

The macOS 27 fm CLI gives every Mac a free language model in the terminal. It needs no account, no API key and no download, and you can point any OpenAI-style client at it. It also has a hard 4,096-token limit and a few rough edges, and several articles describing it get the details wrong.

I ran it on macOS 27.0.1 and measured what it does.

What is the macOS 27 fm CLI?

The fm command is a binary at /usr/bin/fm that talks to Apple's on-device foundation model, the same model behind Apple Intelligence. Apple announced it at WWDC26, so it isn't hidden. Run fm available first. On my Mac it printed System model available, and that was the whole setup.

Command	What it does
`fm respond`	One prompt in, one answer out. Reads stdin too
`fm chat`	Interactive session, saved under `~/.fm/sessions/`
`fm count-tokens`	Counts tokens in a prompt
`fm schema`	Generates a JSON schema for structured output
`fm serve`	Starts a local Chat Completions API server

Is the Private Cloud Compute model available?

Not on this build. Apple's session shows fm respond --model pcc, but on macOS 27.0.1 it fails:

fm respond --model pcc 'hi'
# Error: The value 'pcc' is invalid for '--model <model>'. Please provide one of 'system'.

What is the context window of the fm CLI?

About 4,096 tokens, shared by prompt and reply. Inputs up to 4,001 counted tokens worked; 4,031 failed with The session's transcript exceeded the model's context size. The 8,192 figure in some articles doesn't match this test.

How do you run fm serve as a local API?

fm serve --port 1976
curl -s localhost:1976/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"system","stream":false,"messages":[{"role":"user","content":"Say hi in 3 words."}]}'

The model id is always system. The server streams by default, so set "stream": false explicitly. I found no auth option, so keep it on localhost.

Can the fm CLI return structured JSON?

fm schema object --name Person --string name --int age > person.json
fm respond --schema person.json 'Extract: Maria is 34 years old and lives in Lisbon.' --no-stream
# {"name": "Maria", "age": 34}

How does it compare to Ollama?

About 21 tokens per second through fm serve, versus 20.9 for llama3.2 (3B) on Ollama, one run each. Use fm for zero-install scripting and Ollama when you need a bigger model or long context.

It also answered "today's date" with October 27, 2024, and wrote a find -exec wc -l command that prints per-file counts instead of a total. Check anything it produces.

Read the full version with the comparison table and FAQ on DevToolHub.