mirror of
https://github.com/peter-evans/dockerhub-description.git
synced 2024-11-23 20:49:33 +01:00
102 lines
4.7 KiB
Markdown
102 lines
4.7 KiB
Markdown
# Docker Hub Description
|
|
[](https://github.com/marketplace/actions/docker-hub-description)
|
|
|
|
A GitHub action to update a Docker Hub repository description from `README.md`.
|
|
|
|
This is useful if you `docker push` your images to Docker Hub. It provides an easy, automated way to keep your Docker Hub repository description in sync with your GitHub repository `README.md` file.
|
|
|
|
## Usage
|
|
|
|
```yml
|
|
- name: Docker Hub Description
|
|
uses: peter-evans/dockerhub-description@v2
|
|
env:
|
|
DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
|
|
DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_PASSWORD }}
|
|
DOCKERHUB_REPOSITORY: peterevans/dockerhub-description
|
|
```
|
|
|
|
#### Required environment variables
|
|
|
|
- `DOCKERHUB_USERNAME` - Docker Hub username. If updating a Docker Hub repository belonging to an organization, this user must have `Admin` permissions for the repository. Aliases: `DOCKER_USERNAME`
|
|
- `DOCKERHUB_PASSWORD` - Docker Hub password. Fallback to `DOCKER_PASSWORD` if set. Aliases: `DOCKER_PASSWORD`
|
|
- `DOCKERHUB_REPOSITORY` - The Docker Hub repository to update in the format `<namespace>/<name>`. May also be passed as a secret if considered sensitive. Aliases: `DOCKER_REPOSITORY`, `GITHUB_REPOSITORY`
|
|
|
|
**Note**: Docker Hub [Personal Access Tokens](https://docs.docker.com/docker-hub/access-tokens/) cannot be used as they are not supported by the API. See [here](https://github.com/docker/hub-feedback/issues/1927) and [here](https://github.com/docker/hub-feedback/issues/1914) for further details. Unfortunately, this means that enabling the new 2FA feature on Docker Hub will prevent the action from working.
|
|
|
|
#### Optionally specifying the file path
|
|
|
|
The action assumes that there is a file called `README.md` located at the root of the repository.
|
|
If this is not the case, the path can be overridden with an environment variable.
|
|
|
|
```yml
|
|
- name: Docker Hub Description
|
|
uses: peter-evans/dockerhub-description@v2
|
|
env:
|
|
DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
|
|
DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_PASSWORD }}
|
|
DOCKERHUB_REPOSITORY: peterevans/dockerhub-description
|
|
README_FILEPATH: ./some-path/README.md
|
|
```
|
|
|
|
#### Examples
|
|
|
|
The following workflow updates the Docker Hub repository description whenever there are changes to `README.md` and the workflow file itself on the `master` branch. This workflow assumes its location to be `.github/workflows/dockerhub-description.yml`.
|
|
|
|
```yml
|
|
name: Update Docker Hub Description
|
|
on:
|
|
push:
|
|
branches:
|
|
- master
|
|
paths:
|
|
- README.md
|
|
- .github/workflows/dockerhub-description.yml
|
|
jobs:
|
|
dockerHubDescription:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v2
|
|
- name: Docker Hub Description
|
|
uses: peter-evans/dockerhub-description@v2
|
|
env:
|
|
DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
|
|
DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_PASSWORD }}
|
|
DOCKERHUB_REPOSITORY: peterevans/dockerhub-description
|
|
```
|
|
|
|
Updates the Docker Hub repository description whenever a new release is created.
|
|
|
|
```yml
|
|
name: Update Docker Hub Description
|
|
on: release
|
|
jobs:
|
|
dockerHubDescription:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v2
|
|
- name: Docker Hub Description
|
|
uses: peter-evans/dockerhub-description@v2
|
|
env:
|
|
DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
|
|
DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_PASSWORD }}
|
|
DOCKERHUB_REPOSITORY: peterevans/dockerhub-description
|
|
```
|
|
|
|
## Using the Docker image independently of GitHub Actions
|
|
|
|
The image can be executed in other environments independently of GitHub Actions.
|
|
Simply volume mount the location of the `README.md` file to the container and set environment variables as follows.
|
|
|
|
```bash
|
|
docker run -v $PWD:/workspace \
|
|
-e DOCKERHUB_USERNAME='user1' \
|
|
-e DOCKERHUB_PASSWORD='xxxxx' \
|
|
-e DOCKERHUB_REPOSITORY='user1/my-docker-image' \
|
|
-e README_FILEPATH='/workspace/README.md' \
|
|
peterevans/dockerhub-description:2.3
|
|
```
|
|
|
|
## License
|
|
|
|
[MIT](LICENSE)
|