Schedule and handle the deletion of image tags on the Docker Hub.
A GitHub action is also included.
-
Provide a list of tags in a JSON and/or Markdown file with a deletion date. See Tag List below.
-
Run via cli or GitHub Action.
Configuration is handled using environment variables. The GitHub Action uses inputs that set these. Refer to GitHub Action below for information about its configuration.
Required
The username for authenticating with Docker Hub.
Required
The password or access token for authenticating with Docker Hub.
Required
The name of the repository (image) on Docker Hub in the format of
<namespace>/<name>
Format the source date is in using standard the C standard.
See https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes for more information.
Default: %B %d, %Y (October 6, 2022)
The base URL of the Docker Hub API.
Default: https://hub.docker.com/v2
The relative path to a JSON file containing a list of tags and dates.
The relative path to a Markdown file containing a table with tags and dates.
A string that begins the Markdown table block with tags to parse.
A string that ends the Markdown table block with tags.
The column number that the tags are listed in.
Default: 1
The table column number that the date is in.
Default: 2
A source for tags and their deletion dates must be provided. This may be provided in a coupld of ways - a JSON file and/or a Markdown table.
[
{ "tags": ["1", "1.*"], "date": "October 1, 2022" },
{ "tags": ["2", "2.*"], "date": "November 13, 2023" }
]-
The JSON file should be a list of dictionaries with a
taganddatekey in each one. -
The value of
tagsshould be a list of tag patterns to match. The value ofdateshould be a date in the DATE_FORMAT.
The tag list and deletion dates can be set in a Markdown table using the following format:
<!-- BEGIN deletion_table -->
| Tag | Deletion Date
| ---------- | ----------------------
| `1*` | October 5, 2022
| `2.*` | October 5, 2022
| `foobar` | December 25, 2021
<!-- END deletion_table -->
-
Use a BEGIN and END comment tag surrounding the table block in a Markdown document. These begin/end comment strings are configurable.
-
Only lines that begin with a pipe (
|) are parsed. -
The header names are irrelevant.
-
The number of columns is irrelevant. (set the tag and date column values if the tag/date aren't in the first two columns of the table.
-
Two-column table with a list of grouped tags in the first column and the deletion date in the second column.
-
The table column headers are customizable.
-
The tag column may be a single tag or a list of comma-separated tags. The values can optionally be surrounded in backticks and can use wildcards.
-
The date column should be a single date value in the configured date format.
Ensure the required environment variables are set:
DOCKERHUB_REPOSITORY=foo/bar
DOCKERHUB_USERNAME=foo
DOCKERHUB_PASSWORD=hunter2./hub-tag-delete.pyBasic usage:
- name: Docker Hub Tag Deleter
uses: joshbeard/hub-tag-delete@v1
with:
dockerhub_username: ${{ secrets.DOCKERHUB_USERNAME }}
dockerhub_password: ${{ secrets.DOCKERHUB_PASSWORD }}
dockerhub_repository: foo/bar
markdown_file: README.md-
The GitHub Action exposes all of the environment variables as action inputs. At a minimum, the
dockerhub_username,dockerhub_password, anddockerhub_repositorymust be set in addition tomarkdown_fileand/orjson_file. -
Use
v1for the action version for now.
An example showing all inputs:
- name: Docker Hub Tag Deleter
uses: joshbeard/hub-tag-delete@v1
with:
dockerhub_username: ${{ secrets.DOCKERHUB_USERNAME }}
dockerhub_password: ${{ secrets.DOCKERHUB_PASSWORD }}
dockerhub_repository: foo/bar
dockerhub_api_base_url: https://hub.docker.com/v2
date_format: '%B %d, %Y'
json_file: images.json
markdown_file: README.md
markdown_begin_string: '<!-- BEGIN deletion_table -->'
markdown_end_string: '<!-- END deletion_table -->'
markdown_tag_column: 1
markdown_date_column: 2Refer to the inputs section of the action.yml file for
more information.
See an example of using this in the joshbeard/docker-ansible repository.
Create a virtual environment and activate it:
python -m venv env
. env/bin/activateInstall dependencies:
pip install -r requirements.txtSet the required environment variables. See the Running section.
To build a local image from the repository:
docker build -t hubclean:local .To run the local image, pass along the required environment variables. For
example, using the --env-file option with the docker run command:
docker run --rm -v ${PWD}:/src -w /src --env-file env.local -it hubclean:localRefer to the Running section for an example of these required environment variables.
To launch an interactive shell in the Docker container:
docker run --rm -v ${PWD}:/src -w /src --env-file env.local -it hubclean:local shTo activate the Python virtual environment in the container:
. /var/hub-tag-delete-venv/bin/activate- The script is located at
/usr/bin/hub-tag-delete.py - The Python virtual environment is under
/var/hub-tag-delete-venv - The image is based on Alpine Linux (via
python:3.x-alpine)
masteris the default branch that changes should be pulled into.v1is a "stable" branch.- tags are created by maintainer based on changes.
- Improve error handling (v1)
- Improve output (v1)
- List on Marketplace once (v1) items are completed
- Improve tests
- CLI arguments in addition to existing env vars?
- GitLab registry support
- Build and publish image to Docker Hub (of this tool)
- Provide example GitLab pipeline config (using published image)
- Ongoing: general improvements
- Josh Beard, joshbeard.me