Introduction

If you are using the Docker@2 task in Azure DevOps, the important detail is that arguments are ignored when the command is buildAndPush. That means adding --build-arg ... under arguments does not behave the way many people expect. The practical fix is to split the operation into separate build and push steps, then pass build arguments on the build step.

Why buildAndPush Is the Problem

buildAndPush is a convenience command that combines two actions. In the Docker task, that convenience comes with a limitation: the task does not honor the arguments input for that combined command.

So if your pipeline looks correct but the build arguments never reach Docker, the task behavior is the issue, not your Dockerfile syntax.

Split the Pipeline into build and push

The reliable pattern is to run a build task first, passing the build arguments there, then run a separate push task.

1steps:
2- task: Docker@2
3  displayName: Build image
4  inputs:
5    command: build
6    repository: $(imageRepository)
7    dockerfile: $(dockerfilePath)
8    containerRegistry: $(dockerRegistryServiceConnection)
9    tags: |
10      $(Build.BuildId)
11    arguments: --build-arg APP_ENV=$(appEnv)
12
13- task: Docker@2
14  displayName: Push image
15  inputs:
16    command: push
17    repository: $(imageRepository)
18    containerRegistry: $(dockerRegistryServiceConnection)
19    tags: |
20      $(Build.BuildId)

This is usually the clearest solution because each step does exactly one thing.

Make Sure the Dockerfile Accepts the Argument

Passing --build-arg only helps if the Dockerfile declares the corresponding ARG.

1FROM node:20
2ARG APP_ENV
3ENV APP_ENV=$APP_ENV
4RUN echo "Building for $APP_ENV"

If the Dockerfile never declares ARG APP_ENV, the pipeline argument has nowhere meaningful to go.

Use Variables Intentionally

Azure DevOps variables are a natural way to keep the build argument value configurable.

variables:
  appEnv: production

That makes the pipeline easier to reuse across environments. It also keeps the YAML cleaner than hardcoding values into the task input directly.

Be Careful with Secrets

Build arguments are not a secret-management boundary. If the value is sensitive, do not assume --build-arg is the right place for it.

That is an important design point because Docker build arguments can end up in build history or image metadata depending on how they are used. Sensitive values usually belong in a proper secret-management path instead.

This matters even more in CI systems, where logs and build metadata may be visible to more people than the final runtime environment.

Prefer Explicit Pipelines Over Convenience Commands When Behavior Matters

The broader lesson is that convenience wrappers are great until you need precise control. As soon as build-time customization matters, separate build and push steps are often easier to understand, troubleshoot, and maintain than a single combined task.

This is not only about Azure DevOps. It is a general CI/CD design principle: use the high-level shortcut only when its behavior is actually sufficient.

Once you need precise control, explicit steps are usually easier to trust.

That tradeoff is usually worth the extra YAML.

Predictability beats convenience in CI pipelines.

Common Pitfalls

• Passing arguments to buildAndPush and expecting them to be honored.
• Forgetting to declare matching ARG instructions in the Dockerfile.
• Mixing secrets into Docker build arguments casually.
• Treating convenience tasks as if they always expose the full underlying Docker feature set.
• Debugging the Dockerfile first when the real issue is task behavior in the pipeline.

Summary

• In Azure DevOps Docker@2, arguments are ignored for buildAndPush.
• Split the work into separate build and push tasks if you need --build-arg.
• Declare matching ARG instructions in the Dockerfile.
• Use pipeline variables for maintainable argument values.
• Keep sensitive data out of build arguments unless you fully understand the exposure tradeoffs.