Dockerhub Repository Description

Question

Does anybody know how dockerhub manages the description on automatic build repositories?

Dockerhub has the nice feature that the README.md from the source repository is taken as the repository description. In practise the description of the repository is not always the latest README.md from the master branch. It appears to be quite random or related to latest builds.

Example Repository:

• /
• Dockerfile
• README.md

Branches:

• master

Tags:

• V1.0
• V1.1
• V2.0
• V2.1

Now the problem: If I put all Tags on Autobuild then it is not reproducable which README.md will be shown in the repositories description.

Is there a trick to it or is there an API can where I can set the description?

My wish is that always the latest commit of my master/README.md will be displayed!

Answer 1

If you're looking for a tool to update the README, have a look at docker-pushrm. It is a Docker CLI plugin that adds a new command to Docker: docker pushrm (for: push readme). To update the README on Dockerhub run:

docker pushrm my-user/my-repo

It uses the saved Docker login, so it "just works" after a docker login. It also supports other container registries (Quay, Harbor).

For CI use it's also available as a Docker container and a github action.

If you're looking for a technical answer, have a look at the code of docker-pushrm. In short: You need to make a REST API request with your username/password to get a JWT token. And then make another REST API request with that JWT token to update repo info.

Answer 2

The DockerHub doc mentions:

The build process looks for a README.md in the same directory as your Dockerfile.

(see for instance tombatossals/dockerhub/nodejs)

If you have a README.md file in your repository, it is used in the repository as the full description.

If you change the full description after a build, is overwritten the next time the Automated Build runs.
To make changes, modify the README.md in your Git repository.

Note, as mentioned here by Andy, this does not work for manual build.

For manual builds (where you push your own image), Docker Hub does not peek inside your image and has no way to know about your Readme.
You'll need to manually add your Readme text to the Information section.

---

The OP asks:

Is there an API call where I can set the description of the repo?

Not that I know of (Docker Hub API was deprecated in docker 1.8+)

---

Issue 467 reports the same uncertainty:

Sometimes the automated build system will still use the top-level README file.

And issue 402 reports:

"Every once in a while, the content in the Full Description and the Dockerfile page will be from an old release tag."

And then:

"Has the specification for pulling READMEs changed? It now takes the top-level README from the source repository instead of from the directory where the Dockerfile is specified; considering a common use-case is a repository of Dockerfiles this has completely messed up the documentation."

Issue 300 confirms:

I notice two obvious failings here:

• a) The README.md is not respected in the sub-directory where the Dockerfile is
• b) Even if the README.md is at the repoository's top-level (as well as the Dockerfile) "sometimes" it is not read in and the description is left blank; even after force pushes to the underlying repository.

Answer 3

dockerhub-description GitHub Action can update the Docker Hub description from a README.md file.

    - name: Docker Hub Description
      uses: peter-evans/[email protected]
      env:
        DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
        DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_PASSWORD }}
        DOCKERHUB_REPOSITORY: peterevans/dockerhub-description

You can also use it independently of GitHub Actions in other CI tools.

    docker run -v $PWD:/workspace \
      -e DOCKERHUB_USERNAME='user1' \
      -e DOCKERHUB_PASSWORD='xxxxx' \
      -e DOCKERHUB_REPOSITORY='my-docker-image' \
      -e README_FILEPATH='/workspace/README.md' \
      peterevans/dockerhub-description:2.1.0