dockerhub-description/README.md

167 lines
6.3 KiB
Markdown
Raw Normal View History

2019-06-25 12:33:09 +02:00
# Docker Hub Description
2019-06-25 12:53:47 +02:00
[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-Docker%20Hub%20Description-blue.svg?colorA=24292e&colorB=0366d6&style=flat&longCache=true&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAM6wAADOsB5dZE0gAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3NjYXBlLm9yZ5vuPBoAAAERSURBVCiRhZG/SsMxFEZPfsVJ61jbxaF0cRQRcRJ9hlYn30IHN/+9iquDCOIsblIrOjqKgy5aKoJQj4O3EEtbPwhJbr6Te28CmdSKeqzeqr0YbfVIrTBKakvtOl5dtTkK+v4HfA9PEyBFCY9AGVgCBLaBp1jPAyfAJ/AAdIEG0dNAiyP7+K1qIfMdonZic6+WJoBJvQlvuwDqcXadUuqPA1NKAlexbRTAIMvMOCjTbMwl1LtI/6KWJ5Q6rT6Ht1MA58AX8Apcqqt5r2qhrgAXQC3CZ6i1+KMd9TRu3MvA3aH/fFPnBodb6oe6HM8+lYHrGdRXW8M9bMZtPXUji69lmf5Cmamq7quNLFZXD9Rq7v0Bpc1o/tp0fisAAAAASUVORK5CYII=)](https://github.com/marketplace/actions/docker-hub-description)
2019-06-25 12:33:09 +02:00
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
2019-08-12 07:18:43 +02:00
```yml
2023-10-12 10:32:58 +02:00
- uses: actions/checkout@v4
2019-08-12 07:18:43 +02:00
- name: Docker Hub Description
2024-01-25 13:25:01 +01:00
uses: peter-evans/dockerhub-description@v4
2020-09-25 04:38:47 +02:00
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_PASSWORD }}
repository: peterevans/dockerhub-description
2019-06-25 12:33:09 +02:00
```
2020-09-25 04:38:47 +02:00
### Action inputs
2019-06-25 12:33:09 +02:00
2020-09-25 04:38:47 +02:00
| Name | Description | Default |
| --- | --- | --- |
| `username` | (**required**) Docker Hub username. If updating a Docker Hub repository belonging to an organization, this user must have `Admin` permissions for the repository. | |
2022-07-21 07:26:40 +02:00
| `password` | (**required**) Docker Hub password or [Personal Access Token](https://docs.docker.com/docker-hub/access-tokens/) with `read/write/delete` scope. | |
2020-09-25 07:42:31 +02:00
| `repository` | Docker Hub repository in the format `<namespace>/<name>`. | `github.repository` |
| `short-description` | Docker Hub repository short description. | |
2020-09-25 04:38:47 +02:00
| `readme-filepath` | Path to the repository readme. | `./README.md` |
2023-03-05 03:19:28 +01:00
| `enable-url-completion` | Enables completion of relative URLs to absolute ones. See also [known Issues](#url-completion-known-issues). | `false` |
| `image-extensions` | File extensions that will be treated as images. | `bmp,gif,jpg,jpeg,png,svg,webp` |
2019-06-25 12:33:09 +02:00
#### Content limits
DockerHub has content limits.
2023-04-07 02:21:58 +02:00
The readme content is limited to 25,000 bytes, and `short-description` is limited to 100 bytes.
This action truncates content to prevent the request being rejected.
If the content has been truncated a warning will be issued in the run log.
2020-09-25 07:42:31 +02:00
#### Specifying the file path
2019-06-25 12:33:09 +02:00
The action assumes that there is a file called `README.md` located at the root of the repository.
2020-09-25 04:38:47 +02:00
If this is not the case the path can be specified with the `readme-filepath` input.
2019-06-25 12:33:09 +02:00
2019-08-12 07:18:43 +02:00
```yml
- name: Docker Hub Description
2024-01-25 13:25:01 +01:00
uses: peter-evans/dockerhub-description@v4
2020-09-25 04:38:47 +02:00
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_PASSWORD }}
repository: peterevans/dockerhub-description
readme-filepath: ./path/to/README.md
2019-06-25 12:33:09 +02:00
```
2021-03-31 10:25:28 +02:00
#### Using the GitHub repository description
The GitHub repository description can be used for the Docker Hub `short-descripton` by passing the description from the event context.
```yml
- name: Docker Hub Description
2024-01-25 13:25:01 +01:00
uses: peter-evans/dockerhub-description@v4
2021-03-31 10:25:28 +02:00
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_PASSWORD }}
repository: peterevans/dockerhub-description
short-description: ${{ github.event.repository.description }}
```
2020-09-25 04:38:47 +02:00
### Examples
2019-06-25 12:33:09 +02:00
2021-05-12 10:12:31 +02:00
The following workflow updates the Docker Hub repository description whenever there are changes to `README.md` and the workflow file itself on the `main` branch. This workflow assumes its location to be `.github/workflows/dockerhub-description.yml`.
2019-11-10 13:59:08 +01:00
2019-08-12 07:18:43 +02:00
```yml
name: Update Docker Hub Description
2019-08-12 10:31:07 +02:00
on:
push:
branches:
2021-05-12 10:12:31 +02:00
- main
2019-11-10 13:59:08 +01:00
paths:
- README.md
- .github/workflows/dockerhub-description.yml
2019-08-12 07:18:43 +02:00
jobs:
dockerHubDescription:
runs-on: ubuntu-latest
steps:
2023-10-12 10:32:58 +02:00
- uses: actions/checkout@v4
2020-09-25 04:38:47 +02:00
2019-08-12 07:18:43 +02:00
- name: Docker Hub Description
2024-01-25 13:25:01 +01:00
uses: peter-evans/dockerhub-description@v4
2020-09-25 04:38:47 +02:00
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_PASSWORD }}
repository: peterevans/dockerhub-description
2021-03-31 10:25:28 +02:00
short-description: ${{ github.event.repository.description }}
enable-url-completion: true
2019-06-25 12:33:09 +02:00
```
Updates the Docker Hub repository description whenever a new release is created.
2019-11-10 13:59:08 +01:00
2019-08-12 07:18:43 +02:00
```yml
name: Update Docker Hub Description
2019-08-12 10:31:07 +02:00
on: release
2019-08-12 07:18:43 +02:00
jobs:
dockerHubDescription:
runs-on: ubuntu-latest
steps:
2023-10-12 10:32:58 +02:00
- uses: actions/checkout@v4
2020-09-25 04:38:47 +02:00
2019-08-12 07:18:43 +02:00
- name: Docker Hub Description
2024-01-25 13:25:01 +01:00
uses: peter-evans/dockerhub-description@v4
2020-09-25 04:38:47 +02:00
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_PASSWORD }}
repository: peterevans/dockerhub-description
2021-03-31 10:25:28 +02:00
short-description: ${{ github.event.repository.description }}
2019-06-25 12:33:09 +02:00
```
2023-03-05 03:19:28 +01:00
### URL completion known Issues
2023-03-05 03:19:28 +01:00
The completion of relative URLs has some known issues:
1. Relative markdown links in inline-code and code blocks **are also converted**:
```markdown
[link in inline code](#table-of-content)
```
will be converted into
```markdown
[link in inline code](https://github.com/peter-evans/dockerhub-description/blob/main/./README.md#table-of-content)
```
2. Links containing square brackets (`]`) in the text fragment **are not converted**:
```markdown
[[link text with square brackets]](#table-of-content)
```
3. [Reference-style links/images](https://www.markdownguide.org/basic-syntax/#reference-style-links) **are not converted**.
```markdown
[table-of-content][toc]
...
[toc]: #table-of-content "Table of content"
```
2023-03-05 03:19:28 +01:00
## 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:3
```
2019-06-25 12:33:09 +02:00
## License
2019-11-10 13:59:08 +01:00
[MIT](LICENSE)