# update-tags-action
**Easily create/update one or more Git tags in a GitHub repository.**
[](https://github.com/jimeh/update-tags-action/releases)
[](https://github.com/jimeh/update-tags-action/issues)
[](https://github.com/jimeh/update-tags-action/pulls)
[](https://github.com/jimeh/update-tags-action/blob/main/LICENSE)
Generally useful for moving major (`v1`) and minor (`v1.2`) tags to same commit
as the latest `v1.x.x` tag.
This action
[uses itself](https://github.com/jimeh/update-tags-action/blob/main/.github/workflows/ci.yml)
to move its own major and minor tags.
## Examples
### Basic
```yaml
- uses: jimeh/update-tags-action@v2
with:
tags: v2,v2.2
```
```yaml
- uses: jimeh/update-tags-action@v2
with:
tags: |
v2
v2.2
```
### Deriving Tags from Version
Automatically derive major and minor tags from a semver version string:
```yaml
- uses: jimeh/update-tags-action@v2
with:
derive_from: v1.2.3
# Creates tags: v1, v1.2
```
With a custom template (major tag only):
```yaml
- uses: jimeh/update-tags-action@v2
with:
derive_from: v1.2.3
derive_from_template: '{{prefix}}{{major}}'
# Creates tag: v1
```
Combine derived tags with explicit tags:
```yaml
- uses: jimeh/update-tags-action@v2
with:
derive_from: v1.2.3
tags: latest
# Creates tags: latest, v1, v1.2
```
### With Release Please
This example uses
[jimeh/release-please-manifest-action](https://github.com/jimeh/release-please-manifest-action),
but you can just as easily use the official
[google-github-actions/release-please-action](https://github.com/google-github-actions/release-please-action)
instead.
First you'll want the workflow setup to run on push:
```yaml
on: [push]
```
Then you'll want a release-please job which only runs on pushes to your `main`
branch, and exposes relevant outputs from release please:
```yaml
jobs:
# [...]
release-please:
runs-on: ubuntu-latest
if: ${{ github.ref == 'refs/heads/main' }}
outputs:
release_created: ${{ steps.release-please.outputs.release_created }}
tag_name: ${{ steps.release-please.outputs.tag_name }}
permissions:
contents: write
issues: write
pull-requests: write
steps:
- uses: jimeh/release-please-manifest-action@v3
id: release-please
```
And finally a job to create MAJOR and MINOR release tags, which only runs when
release-please reports having created a release:
```yaml
jobs:
# [...]
release-tags:
runs-on: ubuntu-latest
needs: release-please
if: ${{ needs.release-please.outputs.release_created }}
permissions:
contents: write
steps:
- uses: jimeh/update-tags-action@v2
with:
derive_from: ${{ needs.release-please.outputs.tag_name }}
# Creates tags: v2, v2.2 (for tag_name v2.2.0)
```
## Inputs
| name | description | required | default |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | --------------------------------------------------- |
| `tags` | List/CSV of tags to create/update.
| `false` | `""` |
| `derive_from` | Semver version string to derive tags from (e.g., 'v1.2.3'). When provided, generates tags using derive_from_template input. Default template will produce major and minor tags. (e.g., 'v1', 'v1.2')
| `false` | `""` |
| `derive_from_template` | Handlebars template for deriving tags from the derive_from input. CSV/newline-delimited list with placeholders: {{prefix}}, {{major}}, {{minor}}, {{patch}}, {{prerelease}}, {{build}}, {{version}}.
| `false` | `{{prefix}}{{major}},{{prefix}}{{major}}.{{minor}}` |
| `ref` | The SHA or ref to tag. Defaults to SHA of current commit.
| `false` | `${{ github.sha }}` |
| `when_exists` | What to do if the tag already exists. Must be one of 'update', 'skip', or 'fail'.
| `false` | `update` |
| `annotation` | Optional annotation message for tags. If provided, creates annotated tags. If empty, creates lightweight tags.
| `false` | `""` |
| `dry_run` | If true, logs planned operations without executing them.
| `false` | `false` |
| `github_token` | The GitHub token to use for authentication.
| `false` | `${{ github.token }}` |
### Derive Template Syntax
The `derive_from_template` input uses [Handlebars](https://handlebarsjs.com/)
for template rendering. Splitting the template into separate tags by comma or
newline is done after the template is rendered.
Available placeholders:
| Placeholder | Description |
| ---------------- | ----------------------------------------------------- |
| `{{prefix}}` | `v` or `V` if input had a prefix, empty otherwise |
| `{{major}}` | Major version number |
| `{{minor}}` | Minor version number |
| `{{patch}}` | Patch version number |
| `{{prerelease}}` | Prerelease identifier (e.g., `beta.1`), empty if none |
| `{{build}}` | Build metadata (e.g., `build.123`), empty if none |
| `{{version}}` | Full version string without prefix |
#### Conditional Sections
Use Handlebars `{{#if}}` blocks to include content only when a variable has a
value. This is useful for optional components like prerelease or build metadata:
```yaml
- uses: jimeh/update-tags-action@v2
with:
# Creates tag: v1-beta.1
derive_from: v1.2.3-beta.1
derive_from_template: |
{{prefix}}{{major}}{{#if prerelease}}-{{prerelease}}{{/if}}
```
For a stable release without prerelease:
```yaml
- uses: jimeh/update-tags-action@v2
with:
# Creates tag: v1 (prerelease section omitted)
derive_from: v1.2.3
derive_from_template: |
{{prefix}}{{major}}{{#if prerelease}}-{{prerelease}}{{/if}}
```
You can also use `{{#unless}}` for inverse logic:
```yaml
- uses: jimeh/update-tags-action@v2
with:
# Creates tag: v1-stable (only for non-prerelease versions)
derive_from: v1.2.3
derive_from_template: |
{{prefix}}{{major}}{{#unless prerelease}}-stable{{/unless}}
```
## Outputs
| name | description |
| --------- | ---------------------------------------------- |
| `tags` | List of tags that were created/updated.
|
| `created` | List of tags that were created.
|
| `updated` | List of tags that were updated.
|
| `skipped` | List of tags that were skipped.
|
## Runs
This action is a `node24` action.
## License
[MIT](https://github.com/jimeh/update-tags-action/blob/main/LICENSE)