{"id":24653867,"url":"https://github.com/joshbeard/docker-hub-tag-delete","last_synced_at":"2026-05-03T23:34:32.884Z","repository":{"id":60956282,"uuid":"546799820","full_name":"joshbeard/docker-hub-tag-delete","owner":"joshbeard","description":"Script and GitHub action for deleting image tags from Docker Hub on a schedule","archived":false,"fork":false,"pushed_at":"2024-06-07T21:23:53.000Z","size":73,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-12-03T01:05:34.676Z","etag":null,"topics":["docker-image-pipeline","dockerhub","github-actions","github-actions-docker"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"0bsd","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joshbeard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-10-06T17:03:30.000Z","updated_at":"2025-04-02T20:57:13.000Z","dependencies_parsed_at":"2025-08-09T05:27:24.249Z","dependency_job_id":"8a755c55-69e1-4304-abe5-ad9131b4a222","html_url":"https://github.com/joshbeard/docker-hub-tag-delete","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/joshbeard/docker-hub-tag-delete","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshbeard%2Fdocker-hub-tag-delete","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshbeard%2Fdocker-hub-tag-delete/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshbeard%2Fdocker-hub-tag-delete/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshbeard%2Fdocker-hub-tag-delete/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joshbeard","download_url":"https://codeload.github.com/joshbeard/docker-hub-tag-delete/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshbeard%2Fdocker-hub-tag-delete/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32589260,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"ssl_error","status_checked_at":"2026-05-03T22:09:10.534Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker-image-pipeline","dockerhub","github-actions","github-actions-docker"],"created_at":"2025-01-25T21:14:21.401Z","updated_at":"2026-05-03T23:34:32.856Z","avatar_url":"https://github.com/joshbeard.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Docker Hub Image Tag Deleter\n\n[![Tests](https://github.com/joshbeard/docker-hub-tag-delete/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/joshbeard/docker-hub-tag-delete/actions/workflows/tests.yml)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/25f78736c6fb48db96bde0f04bda7029)](https://www.codacy.com/gh/joshbeard/docker-hub-tag-delete/dashboard?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=joshbeard/docker-hub-tag-delete\u0026amp;utm_campaign=Badge_Grade)\n[![CodeFactor](https://www.codefactor.io/repository/github/joshbeard/docker-hub-tag-delete/badge)](https://www.codefactor.io/repository/github/joshbeard/docker-hub-tag-delete)\n\n\u003c!-- TODO: Disabled until I cleanup the tests\n[![DeepSource](https://deepsource.io/gh/joshbeard/docker-hub-tag-delete.svg/?label=active+issues\u0026show_trend=true\u0026token=JBOrbjcsB0m6ImmQ5Sl2MMve)](https://deepsource.io/gh/joshbeard/docker-hub-tag-delete/?ref=repository-badge)\n--\u003e\n\nSchedule and handle the deletion of image tags on the [Docker\nHub](https://hub.docker.com).\n\nA GitHub action is also included.\n\n## Getting Started\n\n1. Provide a list of tags in a JSON and/or Markdown file with a deletion date.\n   See [Tag List](#tag-list) below.\n\n2. Run via [cli](#running) or [GitHub Action](#github-action).\n\n## Configuration\n\nConfiguration is handled using environment variables. The GitHub Action uses\ninputs that set these. Refer to [GitHub Action](#github-action) below for\ninformation about its configuration.\n\n### Environment Variables\n\n#### `DOCKERHUB_USERNAME`\n\n__Required__\n\nThe username for authenticating with Docker Hub.\n\n#### `DOCKERHUB_PASSWORD`\n\n__Required__\n\nThe password or access token for authenticating with Docker Hub.\n\n#### `DOCKERHUB_REPOSITORY`\n\n__Required__\n\nThe name of the repository (image) on Docker Hub in the format of\n`\u003cnamespace\u003e/\u003cname\u003e`\n\n#### `DATE_FORMAT`\n\nFormat the source date is in using standard the C standard.\n\nSee \u003chttps://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes\u003e\nfor more information.\n\nDefault: `%B %d, %Y` (October 6, 2022)\n\n#### `DOCKERHUB_API_BASE_URL`\n\nThe base URL of the Docker Hub API.\n\nDefault: _https://hub.docker.com/v2_\n\n#### `JSON_FILE`\n\nThe relative path to a JSON file containing a list of tags and dates.\n\n#### `MARKDOWN_FILE`\n\nThe relative path to a Markdown file containing a table with tags and dates.\n\n#### `MARKDOWN_BEGIN_STRING`\n\nA string that begins the Markdown table block with tags to parse.\n\n#### `MARKDOWN_END_STRING`\n\nA string that ends the Markdown table block with tags.\n\n#### `MARKDOWN_TAG_COLUMN`\n\nThe column number that the tags are listed in.\n\nDefault: `1`\n\n#### `MARKDOWN_DATE_COLUMN`\n\nThe table column number that the date is in.\n\nDefault: `2`\n\n### Tag List\n\nA source for tags and their deletion dates must be provided. This may be\nprovided in a coupld of ways - a JSON file and/or a Markdown table.\n\n#### Tag List: JSON File\n\n```json\n[\n  { \"tags\": [\"1\", \"1.*\"], \"date\": \"October 1, 2022\" },\n  { \"tags\": [\"2\", \"2.*\"], \"date\": \"November 13, 2023\" }\n]\n```\n\n* The JSON file should be a _list_ of _dictionaries_ with a `tag` and `date`\n  key in each one.\n\n* The value of `tags` should be a list of tag\n  [patterns](https://docs.python.org/3/library/fnmatch.html) to match.\n  The value of `date` should be a date in the [DATE_FORMAT](#date-format).\n\n#### Tag List: Markdown Table\n\nThe tag list and deletion dates can be set in a Markdown table using the\nfollowing format:\n\n```plain\n\u003c!-- BEGIN deletion_table --\u003e\n| Tag        | Deletion Date\n| ---------- | ----------------------\n| `1*`       | October 5, 2022\n| `2.*`      | October 5, 2022\n| `foobar`   | December 25, 2021\n\u003c!-- END deletion_table --\u003e\n```\n\n* Use a BEGIN and END comment tag surrounding the table block in a Markdown\n  document. These begin/end comment strings are configurable.\n\n* Only lines that begin with a pipe (`|`) are parsed.\n\n* The header names are irrelevant.\n\n* The number of columns is irrelevant. (set the [tag](#markdown-tag-column)\n  and [date](#markdown-date-column) column values if the tag/date aren't in the\n  first two columns of the table.\n\n* Two-column table with a list of grouped tags in the first column and the\n  deletion date in the second column.\n\n* The table column headers are customizable.\n\n* The tag column may be a single tag or a list of comma-separated tags. The\n  values can optionally be surrounded in backticks and can use wildcards.\n\n* The date column should be a single date value in the configured\n  [date format](#date-format).\n\n## Running\n\nEnsure the _required_ environment variables are set:\n\n```shell\nDOCKERHUB_REPOSITORY=foo/bar\nDOCKERHUB_USERNAME=foo\nDOCKERHUB_PASSWORD=hunter2\n```\n\n```shell\n./hub-tag-delete.py\n```\n\n## GitHub Action\n\nBasic usage:\n\n```yaml\n    - name: Docker Hub Tag Deleter\n      uses: joshbeard/hub-tag-delete@v1\n      with:\n        dockerhub_username: ${{ secrets.DOCKERHUB_USERNAME }}\n        dockerhub_password: ${{ secrets.DOCKERHUB_PASSWORD }}\n        dockerhub_repository: foo/bar\n        markdown_file: README.md\n```\n\n* The GitHub Action exposes all of the [environment\n  variables](#environment-variables) as action inputs. At a minimum, the\n  `dockerhub_username`, `dockerhub_password`, and `dockerhub_repository` must\n  be set in addition to `markdown_file` and/or `json_file`.\n\n* Use `v1` for the action version for now.\n\nAn example showing all inputs:\n\n```yaml\n    - name: Docker Hub Tag Deleter\n      uses: joshbeard/hub-tag-delete@v1\n      with:\n        dockerhub_username: ${{ secrets.DOCKERHUB_USERNAME }}\n        dockerhub_password: ${{ secrets.DOCKERHUB_PASSWORD }}\n        dockerhub_repository: foo/bar\n        dockerhub_api_base_url: https://hub.docker.com/v2\n        date_format: '%B %d, %Y'\n        json_file: images.json\n        markdown_file: README.md\n        markdown_begin_string: '\u003c!-- BEGIN deletion_table --\u003e'\n        markdown_end_string: '\u003c!-- END deletion_table --\u003e'\n        markdown_tag_column: 1\n        markdown_date_column: 2\n```\n\nRefer to the `inputs` section of the [`action.yml`](action.yml) file for\nmore information.\n\nSee an example of using this in the\n[joshbeard/docker-ansible](https://github.com/joshbeard/docker-ansible/)\nrepository.\n\n## Developer Notes\n\n### Local Python Environment\n\nCreate a virtual environment and activate it:\n\n```shell\npython -m venv env\n. env/bin/activate\n```\n\nInstall dependencies:\n\n```shell\npip install -r requirements.txt\n```\n\nSet the [required environment variables](#environment-variables). See the\n[Running](#running) section.\n\n### Using Docker\n\nTo build a local image from the repository:\n\n```shell\ndocker build -t hubclean:local .\n```\n\nTo run the local image, pass along the required environment variables. For\nexample, using the `--env-file` option with the `docker run` command:\n\n```shell\ndocker run --rm -v ${PWD}:/src -w /src --env-file env.local -it hubclean:local\n```\n\nRefer to the [Running](#running) section for an example of these required\n[environment variables](#environment-variables).\n\nTo launch an interactive shell in the Docker container:\n\n```shell\ndocker run --rm -v ${PWD}:/src -w /src --env-file env.local -it hubclean:local sh\n```\n\nTo activate the Python virtual environment in the container:\n\n```shell\n. /var/hub-tag-delete-venv/bin/activate\n```\n\n* The script is located at `/usr/bin/hub-tag-delete.py`\n* The Python virtual environment is under `/var/hub-tag-delete-venv`\n* The image is based on Alpine Linux (via `python:3.x-alpine`)\n\n## Branching Scheme\n\n* `master` is the default branch that changes should be pulled into.\n* `v1` is a \"stable\" branch.\n* _tags_ are created by maintainer based on changes.\n\n## TODO\n\n* Improve error handling (v1)\n* Improve output (v1)\n* List on Marketplace once (v1) items are completed\n* Improve [tests](tests/)\n* CLI arguments in addition to existing env vars?\n* GitLab registry support\n* Build and publish image to Docker Hub (of this tool)\n* Provide example GitLab pipeline config (using published image)\n* Ongoing: general improvements\n\n## Authors\n\n* Josh Beard, [joshbeard.me](https://joshbeard.me)\n\n## License\n\n[BSD Zero Clause License (0BSD)](LICENSE)\n\n## Repository Integrations\n\n* [Codacy](https://app.codacy.com/gh/joshbeard/docker-hub-tag-delete/)\n* [CodeFactor](https://www.codefactor.io/repository/github/joshbeard/docker-hub-tag-delete)\n* [Deepsource](https://deepsource.io/gh/joshbeard/docker-hub-tag-delete/)\n* [Renovate](https://www.mend.io/free-developer-tools/renovate/)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshbeard%2Fdocker-hub-tag-delete","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoshbeard%2Fdocker-hub-tag-delete","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshbeard%2Fdocker-hub-tag-delete/lists"}