{"id":15294725,"url":"https://github.com/mateimicu/auto-tag","last_synced_at":"2025-04-13T14:54:08.196Z","repository":{"id":35091962,"uuid":"205390141","full_name":"mateimicu/auto-tag","owner":"mateimicu","description":"Automatically tag a branch based on configurable rules","archived":false,"fork":false,"pushed_at":"2023-04-10T03:32:25.000Z","size":588,"stargazers_count":11,"open_issues_count":20,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-13T14:53:59.906Z","etag":null,"topics":["automation","ci","ci-cd","cicd","detector","devops","git","pypi","python","semantic","tag","tagging","tags","triggers","upstream","version-manager","versioning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mateimicu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-08-30T13:41:35.000Z","updated_at":"2023-02-27T21:01:29.000Z","dependencies_parsed_at":"2023-01-16T22:22:12.002Z","dependency_job_id":null,"html_url":"https://github.com/mateimicu/auto-tag","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateimicu%2Fauto-tag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateimicu%2Fauto-tag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateimicu%2Fauto-tag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateimicu%2Fauto-tag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mateimicu","download_url":"https://codeload.github.com/mateimicu/auto-tag/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248732512,"owners_count":21152851,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["automation","ci","ci-cd","cicd","detector","devops","git","pypi","python","semantic","tag","tagging","tags","triggers","upstream","version-manager","versioning"],"created_at":"2024-09-30T17:06:30.700Z","updated_at":"2025-04-13T14:54:08.175Z","avatar_url":"https://github.com/mateimicu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Auto-Tag\n![PyPI](https://img.shields.io/pypi/v/auto-tag)\n![PyPI - Implementation](https://img.shields.io/pypi/implementation/auto-tag)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/auto-tag)\n[![codecov](https://codecov.io/gh/mateimicu/auto-tag/branch/master/graph/badge.svg)](https://codecov.io/gh/mateimicu/auto-tag)\n![PyPI - License](https://img.shields.io/pypi/l/auto-tag)\n\n\nAutomatically tag a branch with the next semantic version tag.\n\nThis is useful if you want to generate tags every time something is merged.\nMicroservice and GitOps repository are good candidates for this type of action.\n\n\n# TOC\n\n - [Install](#how-to-install)\n - [How it Works](#how-it-works)\n - [Exampels](#examples)\n - [Detectors](#detectors)\n - [Git Author](#git-author)\n\n# How to install\n\n```bash\n~ $ pip install auto-tag\n```\n\nTo see if it works, you can try\n\n```bash\n~ $ auto-tag  -h\nusage: auto-tag [-h] [-b BRANCH] [-r REPO]\n                [-u [UPSTREAM_REMOTE [UPSTREAM_REMOTE ...]]]\n                [-l {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET}]\n                [--name NAME] [--email EMAIL] [-c CONFIG]\n                [--skip-tag-if-one-already-present] [--append-v-to-tag]\n                [--tag-search-strategy {biggest-tag-in-repo,biggest-tag-in-branch,latest-tag-in-repo,latest-tag-in-branch}]\n\n.....\n```\n\n# How it Works\n\nThe flow is as follows:\n- figure our repository based on the argument\n- load detectors from file if specified (`-c` option), if none specified load default ones (see [Detectors](#detectors))\n- check for the last tag (depending on the search strategy see [Search Strategy](#search-strategy)\n- look at all commits done after that tag on a specific branch (or from the start of the repository if no tag is found)\n- apply the detector (see [Detectors](#detectors)) on each commit and save the highest change detected (PATH, MINOR, MAJOR)\n- bump the last tag with the approbate change  and apply it using the default git author in the system or a specific one (see [Git Author](#git-author))\n- if an upstream was specified push the tag to that upstream\n\n\n# Examples\n\nHere we can see in commit `2245d5d` that it stats with `feature(`\nso the latest know tag (`0.2.1`) was bumped to `0.3.0`\n```\n~ $ git log --oneline\n2245d5d (HEAD -\u003e master) feature(component) commit #4\n939322f commit #3\n9ef3be6 (tag: 0.2.1) commit #2\n0ee81b0 commit #1\n~ $ auto-tag\n2019-08-31 14:10:24,626: Start tagging \u003cgit.Repo \"/Users/matei/git/test-auto-tag-branch/.git\"\u003e\n2019-08-31 14:10:24,649: Bumping tag 0.2.1 -\u003e 0.3.0\n2019-08-31 14:10:24,658: No push remote was specified\n~ $ git log --oneline\n2245d5d (HEAD -\u003e master, tag: 0.3.0) feature(component) commit #4\n939322f commit #3\n9ef3be6 (tag: 0.2.1) commit #2\n0ee81b0 commit #1\n```\n\n\nIn this example we can see `2245d5deb5d97d288b7926be62d051b7eed35c98` introducing a feature that will trigger a MINOR change but we can also see `0de444695e3208b74d0b3ed7fd20fd0be4b2992e` having a `BREAKING_CHANGE` that will introduce a MAJOR bump, this is the reason the tag moved from `0.2.1` to `1.0.0`\n```\n~ $ git log\ncommit 0de444695e3208b74d0b3ed7fd20fd0be4b2992e (HEAD -\u003e master)\nAuthor: Matei-Marius Micu \u003cmicumatei@gmail.com\u003e\nDate:   Fri Aug 30 21:58:01 2019 +0300\n\n    fix(something) ....\n\n    BREAKING_CHANGE: this must trigger major version bump\n\ncommit 65bf4b17669ea52f84fd1dfa4e4feadbc299a80e\nAuthor: Matei-Marius Micu \u003cmicumatei@gmail.com\u003e\nDate:   Fri Aug 30 21:57:47 2019 +0300\n\n    fix(something) ....\n\ncommit 2245d5deb5d97d288b7926be62d051b7eed35c98\nAuthor: Matei-Marius Micu \u003cmicumatei@gmail.com\u003e\nDate:   Fri Aug 30 19:52:10 2019 +0300\n\n    feature(component) commit #4\n\ncommit 939322f1efaa1c07b7ed33f2923526f327975cfc\nAuthor: Matei-Marius Micu \u003cmicumatei@gmail.com\u003e\nDate:   Fri Aug 30 19:51:24 2019 +0300\n\n    commit #3\n\ncommit 9ef3be64c803d7d8d3b80596485eac18e80cb89d (tag: 0.2.1)\nAuthor: Matei-Marius Micu \u003cmicumatei@gmail.com\u003e\nDate:   Fri Aug 30 19:51:18 2019 +0300\n\n    commit #2\n\ncommit 0ee81b0bed209941720ee602f76341bcb115b87d\nAuthor: Matei-Marius Micu \u003cmicumatei@gmail.com\u003e\nDate:   Fri Aug 30 19:50:25 2019 +0300\n\n    commit #1\n~ $ auto-tag\n2019-08-31 14:10:24,626: Start tagging \u003cgit.Repo \"/Users/matei/git/test-auto-tag-branch/.git\"\u003e\n2019-08-31 14:10:24,649: Bumping tag 0.2.1 -\u003e 1.0.0\n2019-08-31 14:10:24,658: No push remote was specified\n~ $ git log\ncommit 0de444695e3208b74d0b3ed7fd20fd0be4b2992e (HEAD -\u003e master, tag: 1.0.0)\nAuthor: Matei-Marius Micu \u003cmicumatei@gmail.com\u003e\nDate:   Fri Aug 30 21:58:01 2019 +0300\n\n    fix(something) ....\n\n    BREAKING_CHANGE: this must trigger major version bump\n\ncommit 65bf4b17669ea52f84fd1dfa4e4feadbc299a80e\nAuthor: Matei-Marius Micu \u003cmicumatei@gmail.com\u003e\nDate:   Fri Aug 30 21:57:47 2019 +0300\n\n    fix(something) ....\n\ncommit 2245d5deb5d97d288b7926be62d051b7eed35c98\nAuthor: Matei-Marius Micu \u003cmicumatei@gmail.com\u003e\nDate:   Fri Aug 30 19:52:10 2019 +0300\n\n    feature(component) commit #4\n\ncommit 939322f1efaa1c07b7ed33f2923526f327975cfc\nAuthor: Matei-Marius Micu \u003cmicumatei@gmail.com\u003e\nDate:   Fri Aug 30 19:51:24 2019 +0300\n\n    commit #3\n\ncommit 9ef3be64c803d7d8d3b80596485eac18e80cb89d (tag: 0.2.1)\nAuthor: Matei-Marius Micu \u003cmicumatei@gmail.com\u003e\nDate:   Fri Aug 30 19:51:18 2019 +0300\n\n    commit #2\n\ncommit 0ee81b0bed209941720ee602f76341bcb115b87d\nAuthor: Matei-Marius Micu \u003cmicumatei@gmail.com\u003e\nDate:   Fri Aug 30 19:50:25 2019 +0300\n\n    commit #1\n```\n# Detectors\n\nIf you want to detect what commit enforces a specific tag bump(PATH, MINOR, MAJOR) you can configure detectors.\nThey are configured in a yaml file that looks like this:\n```yaml\ndetectors:\n\n  check_for_feature_heading:\n    type: CommitMessageHeadStartsWithDetector\n    produce_type_change: MINOR\n    params:\n      pattern: 'feature'\n\n\n  check_for_breaking_change:\n    type: CommitMessageContainsDetector\n    produce_type_change: MAJOR\n    params:\n      pattern: 'BREAKING_CHANGE'\n      case_sensitive: false\n```\nHere is the default configuration for detectors if none is specified.\nWe can see we have two detectors `check_for_feature_heading` and `check_for_breaking_change`, with a type, what change they will trigger and specific parameters for each one.\nThis configuration will do the following:\n- if the commit message  starts with `feature(` a MINOR change will BE triggered\n- if the commit has `BREAKIN_CHANGE` in the message a MAJOR change will be triggered\nThe bump on the tag will be based on the higher priority found.\n\nThe `type` and `produce_type_change` parameters are required `params` is specific to every detector.\n\nTo pass the file to the process just use the `-c` CLI parameter.\n\nCurrently we support the following triggers:\n  - CommitMessageHeadStartsWithDetector\n    - Parameters:\n      - `case_sensitive` of type `bool`, if the comparison is case sensitive\n      - `strip` of type `bool`, if we strip the spaces from the commit message\n      - `pattern` of type `string`, what pattern is searched at the start of the commit message\n  - CommitMessageContainsDetector\n      - `case_sensitive` of type `bool`, if the comparison is case sensitive\n      - `strip` of type `bool`, if we strip the spaces from the commit message\n      - `pattern` of type `string`, what pattern is searched in the body of the commit message\n  - CommitMessageMatchesRegexDetector\n      - `strip` of type `bool`, if we strip the spaces from the commit message\n      - `pattern` of type `string`, what regex pattern to match against the commit message\n\nThe regex detector is the most powerful one.\n\n# Git Author\nWhen creating and tag we need to specify a git author, if a global one is not set (or if we want to make this one with a specific user), we have the option to specify one.\nThe following options will add a temporary config to this repository(local config). After the tag was created it will restore the existing config (if any was present)\n```\n  --name NAME           User name used for creating git objects.If not\n                        specified the system one will be used.\n  --email EMAIL         Email name used for creating git objects.If not\n                        specified the system one will be used.\n```\nIf another user interacts with git while this process is taking place it will use the temporary config, but we assume we are run in a CI pipeline and this is the only process interacting with git.\n\n# Search Strategy\n\nIf you want to bump a tag first you need to find the last one, we have a few  implementations to search for the last tag that can be configured with `--tag-search-strategy` CLI option.\n\n* `biggest-tag-in-repo` consider all tags **in the repository** as semantic versions and pick the biggest one\n* `biggest-tag-in-branch` consider all tags **on the specified branch** as semantic versions and pick the biggest one\n* `latest-tag-in-repo` compare `commit date` for each commit that has a tag **in the repository** and take the latest\n* `latest-tag-in-branch` compare `commit date` for each commit that has a tag **one the specifid branch** and take the latest\n\n---\nThis project is licensed under the terms of the MIT license.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmateimicu%2Fauto-tag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmateimicu%2Fauto-tag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmateimicu%2Fauto-tag/lists"}