13

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!

blacklabelops
  • 4,708
  • 5
  • 25
  • 42

3 Answers3

12

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.
Community
  • 1
  • 1
VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250
  • Thanks for your answer but I have builds on several tags and branches and the README.md seems random in this context. How can I control this? – blacklabelops Jan 27 '16 at 10:37
  • @maybeg is your README near your Dockerfile? – VonC Jan 27 '16 at 11:19
  • The readme is right next to the Dockerfile in the same folder. – blacklabelops Jan 27 '16 at 12:52
  • @maybeg And do you have a global README, at the root folder of your repo? – VonC Jan 27 '16 at 12:53
  • @maybeg that might be cause for uncertainty, as I see that https://github.com/tombatossals/dockerhub/tree/master/nodejs has none in its root folder. – VonC Jan 27 '16 at 12:54
  • Is there an API call where I can set the description of the repo? – blacklabelops Jan 27 '16 at 12:59
  • @maybeg Not that I know of. I have edited the answer to include links to similar issues reported in the DockerHub project. – VonC Jan 27 '16 at 15:10
  • Currently, there is no mention of `README.md` in [DockerHub doc](https://docs.docker.com/docker-hub/builds/#understand-the-build-process) link. – natenho Aug 04 '19 at 18:51
  • @natenho Agreed. That was in 2016. – VonC Aug 04 '19 at 18:59
  • I've just opened [this issue](https://github.com/docker/docker.github.io/issues/9202) to update that documentation, as I could not find the current process information. – natenho Aug 04 '19 at 19:03
  • @natenho Good initiative, thank you. I will follow this issue (https://github.com/docker/docker.github.io/issues/9202) – VonC Aug 04 '19 at 19:13
  • @blacklabelops There is an API you can use to push the README.md content. See my answer for a utility I created to handle that call. https://stackoverflow.com/questions/35032775/dockerhub-repository-description/57671333#57671333 – peterevans Sep 27 '19 at 03:06
5

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

    - name: Docker Hub Description
      uses: peter-evans/dockerhub-description@v2.1.0
      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
peterevans
  • 34,297
  • 7
  • 84
  • 83
3

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.

Chris
  • 567
  • 6
  • 24