How can I force an overwrite when pushing a Docker image using the docker_image Ansible module?

Below is an explanation and some suggestions.

Explanation

The Ansible module (community.docker.docker_image) is designed to be idempotent. This means it checks if the image with the given tag already exists in the registry and, if so, it won’t perform the push again. There isn’t currently a built‑in parameter to “force” a push (i.e. overwrite the existing image regardless of its presence).

Workarounds and Alternatives

1. Use a Unique Tag
   One common approach is to tag your image uniquely (for example, using a commit SHA, timestamp, or build number). This lets you push a new version every time without worrying about overwriting an already‑present tag. For example:

   YAMLCopied
   - name: Push images with unique tag to registry
     community.docker.docker_image:
       name: "my-image"
       repository: "ghcr.io/my-org/my-repo/my-image:{{ unique_tag }}"
       push: true
       source: local

2. Remove the Remote Image Before Pushing
   If you really want to overwrite an existing tag, another approach is to remove the image from the registry before pushing. This could be done using a registry API (for example, using Ansible’s URI module) to delete the image, or using a shell/command task that calls a CLI command if available for your registry. After deletion, running the push again will place the new image.

3. Invoke Docker Commands Directly
   You could bypass the docker_image module entirely and use Ansible’s shell or command module to run the docker image push command directly. This might be useful if you want to work around the module’s behavior. For example:

   YAMLCopied
   - name: Push image directly using docker CLI
     shell: |
       docker tag my-image ghcr.io/my-org/my-repo/my-image:latest
       docker push ghcr.io/my-org/my-repo/my-image:latest

   This approach gives you full control of the process, but you lose some of the benefits of the module’s idempotence.

Conclusion

Currently, there is no force‑push option built into the docker_image module. You can work around this limitation by either using unique tags or removing the remote image before pushing, or by using direct Docker CLI calls through Ansible. Choose the approach that best fits your workflow and environment.