A few days ago, working with Claude Code, I came across a tool that’s been around in the Docker ecosystem for a while but that I didn’t know about: docker pushrm. And the truth is it surprised me how useful it is for something as simple as keeping your container repository documentation synchronized.
The problem it solves
Anyone who has worked with Docker Hub, Quay, or Harbor knows the typical flow: you update your project’s README on GitHub, build and push your image, but… the container registry’s README is still outdated. You have to manually go to the browser, copy and paste the content, and do the update manually.
For someone who handles several projects and repositories, this quickly becomes a tedious task and easy to forget.
What is docker pushrm
docker pushrm is a plugin for the Docker CLI that adds a very simple command: docker pushrm. What it does is read the README.md file from the current directory and automatically upload it to the container registry as the repository description.
The tool is the work of Christian Korneck and is available as an official Docker plugin. It supports the main registries:
- Docker Hub (cloud)
- Red Hat Quay (cloud and self-hosted/OpenShift)
- Harbor v2 (self-hosted)
Installation on macOS
Installation is quite straightforward. In my case, on macOS, I simply downloaded the binary and placed it in the Docker plugins directory:
# Download the binary for macOS
curl -LO https://github.com/christian-korneck/docker-pushrm/releases/latest/download/docker-pushrm-darwin-amd64
# Move to Docker plugins directory
mv docker-pushrm-darwin-amd64 $HOME/.docker/cli-plugins/docker-pushrm
# Make it executable
chmod +x $HOME/.docker/cli-plugins/docker-pushrm
For other operating systems:
On Linux:
curl -LO https://github.com/christian-korneck/docker-pushrm/releases/latest/download/docker-pushrm-linux-amd64
mv docker-pushrm-linux-amd64 $HOME/.docker/cli-plugins/docker-pushrm
chmod +x $HOME/.docker/cli-plugins/docker-pushrm
On Windows:
Place the executable in: c:\Users\<your-username>\.docker\cli-plugins\docker-pushrm.exe
Once installed, you can verify it works with:
docker pushrm --help
Basic usage
The simplest use is extremely straightforward:
# In your project directory with README.md
$ ls
Dockerfile README.md
# Build and push image as usual
$ docker build -t my-user/my-project .
$ docker push my-user/my-project
# And now synchronize the README
$ docker pushrm my-user/my-project
That’s it. The command will read the current directory’s README.md and upload it to Docker Hub as the repository description.
Useful options
For Docker Hub you can also set a short description:
docker pushrm -s "A useful tool to automate tasks" my-user/my-project
If you want to use a specific README file instead of the current directory’s:
docker pushrm --file docs/README-container.md my-user/my-project
For other registries, simply specify the provider:
# For Quay
docker pushrm --provider quay quay.io/my-user/my-project
# For Harbor
docker pushrm --provider harbor2 registry.example.com/my-project/my-app
Practical use cases
1. CI/CD integration: The tool especially shines in CI/CD pipelines. You can automate synchronization as part of your release process.
2. Differentiated documentation:
If you need the registry documentation to be different from the code repository’s, you can create a README-containers.md file that will automatically take precedence.
3. Multiple registries: If you publish to multiple registries, you can automate documentation synchronization for all of them.
My experience using Claude Code
What caught my attention is how Claude Code suggested using this tool when I was working on a project that required keeping descriptions synchronized between GitHub and Docker Hub.
The AI detected the work pattern and proposed this solution, which saved me considerable time in research and manual configuration.
Advantages I’ve found
- Extreme simplicity: One command and you’re done
- Natural integration: Uses the Docker credentials you already have configured
- Flexibility: Works with multiple registries and configuration options
- Automatable: Perfect for CI/CD
Limitations to keep in mind
- For Quay you need to configure an additional API key
- Harbor with OIDC authentication can give problems
- Only supports markdown, not other formats
Conclusion
docker pushrm is one of those tools that solves a specific problem elegantly. It’s not revolutionary, but it makes a manual and repetitive process automatic and reliable.
For anyone maintaining projects with Docker containers, especially if you publish to multiple registries or have automated pipelines, it’s worth having in the toolkit.
Next time you find yourself copying and pasting READMEs between GitHub and Docker Hub, remember this tool. Your future self will thank you.
Useful links:
Comments