autotag/README.md

310 lines
12 KiB
Markdown
Raw Normal View History

2019-09-03 04:12:28 +07:00
# Autotag
2019-09-03 03:40:00 +07:00
This action will auto-generate a Github tag whenever a new version is detected. The following "detection strategies" are available:
2019-09-03 06:45:33 +07:00
1. **package**: Monitor a `package.json` for new versions.
1. **docker**: Monitor a `Dockerfile` for a `LABEL version=x.x.x` value.
1. **regex**: Use a JavaScript [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) with any file for your own custom extraction.
When a version is detected, it is compared to the current list of tags in the Github repository. If a tag does not exist, it will be created.
This action works well in combination with:
2020-01-30 05:55:04 +07:00
- [actions/create-release](https://github.com/actions/create-release) (Auto-release)
- [author/action-publish](https://github.com/author/action-publish) (Auto-publish JavaScript/Node modules)
- [author/action-rollback](https://github.com/author/action-rollback) (Auto-rollback releases on failures)
- [author/template-cross-runtime](https://github.com/author/template-cross-runtime) (a cross-runtime JavaScript repo template)
2019-09-03 06:45:33 +07:00
## Usage
2020-01-28 06:01:06 +07:00
The following is an example `.github/workflows/main.yml` that will execute when a `push` to the `master` branch occurs.
2019-09-03 06:45:33 +07:00
```yaml
2020-01-28 06:01:06 +07:00
name: Create Tag
2019-09-03 06:45:33 +07:00
on:
2019-09-03 06:45:33 +07:00
push:
branches:
2020-01-28 06:01:06 +07:00
- master
2019-09-03 06:45:33 +07:00
jobs:
build:
runs-on: ubuntu-latest
steps:
2020-01-28 05:58:59 +07:00
- uses: actions/checkout@v2
2019-09-20 00:49:09 +07:00
- uses: butlerlogic/action-autotag@stable
env:
2019-09-03 06:45:33 +07:00
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
```
To make this work, the workflow must have the checkout action _before_ the autotag action.
This **order** is important!
```yaml
2020-01-28 06:01:06 +07:00
- uses: actions/checkout@v2
- uses: butlerlogic/action-autotag@stable
2019-09-03 06:45:33 +07:00
```
> If the repository is not checked out first, the autotagger cannot find the package.json file.
## Configuration
The `GITHUB_TOKEN` **must** be provided. Without this, it is not possible to create a new tag. Make sure the autotag action looks like the following example:
2019-09-03 06:45:33 +07:00
```yaml
2020-01-28 06:01:06 +07:00
- uses: butlerlogic/action-autotag@stable
2019-09-03 06:45:33 +07:00
with:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
```
2020-01-24 22:37:17 +07:00
The action will automatically extract the token at runtime. **DO NOT MANUALLY ENTER YOUR TOKEN.** If you put the actual token in your workflow file, you'll make it accessible (in plaintext) to anyone who ever views the repository (it will be in your git history).
2019-09-03 06:45:33 +07:00
2020-04-05 00:42:31 +07:00
## Optional Configurations
2019-09-03 06:45:33 +07:00
There are several options to customize how the tag is created.
2020-04-05 00:42:31 +07:00
### strategy (required)
This is the strategy used to identify the version number/tag from within the code base.
1. _package_: Monitor a `package.json` for new versions. Use this for JavaScript projects based on Node modules (npm, yarn, etc).
1. _docker_: Monitor a `Dockerfile` for a `LABEL version=x.x.x` value. USe this for container projects.
1. _regex*_: Use a JavaScript [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) with any file for your own custom extraction.
2020-04-05 00:09:00 +07:00
> **EXCEPTION**: This property is _not_ required if the `regex_pattern` property is defined, because it is assumed to be "regex".
2020-04-05 00:09:00 +07:00
```yaml
- uses: butlerlogic/action-autotag@1.0.0
env:
2020-04-05 00:09:00 +07:00
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
with:
2020-04-05 00:09:00 +07:00
strategy: docker
```
2020-04-05 00:42:31 +07:00
### root
_Formerly `package_root`_
2020-04-05 00:09:00 +07:00
Depending on the selected strategy, autotagger will look for the `package.json` or `Dockerfile` file in the project root. If the file is located in a subdirectory, this option can be used to point to the correct file.
_Using the **package** strategy:_
```yaml
- uses: butlerlogic/action-autotag@1.0.0
env:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
with:
2020-04-05 00:09:00 +07:00
strategy: package # Optional, since "package" is the default strategy
root: "/path/to/subdirectory"
```
2020-04-05 00:09:00 +07:00
The version number would be extracted from `/path/to/subdirectory/package.json`.
_Using the **docker** strategy:_
```yaml
- uses: butlerlogic/action-autotag@1.0.0
env:
2020-04-05 00:09:00 +07:00
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
with:
2020-04-05 00:09:00 +07:00
strategy: docker
root: "/path/to/subdirectory"
```
The version number would be extracted from `/path/to/subdirectory/Dockerfile`, specifically looking for the `LABEL version=x.x.x` line within the file.
_Using the **regex** strategy:_
```yaml
- uses: butlerlogic/action-autotag@1.0.0
env:
2020-04-05 00:09:00 +07:00
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
with:
2020-04-05 00:09:00 +07:00
strategy: regex # Optional since regex_pattern is defined
root: "/path/to/subdirectory/my.file"
regex_pattern: "version=([0-9\.])"
```
The version will be extracted by scanning the content of `/path/to/subdirectory/my.file` for a string like `version=1.0.0`. See the `regex_pattern` option for more details.
### regex_pattern
An optional attribute containing the regular expression used to extract the version number.
```yaml
- uses: butlerlogic/action-autotag@1.0.0
env:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
with:
regex_pattern: "version=([0-9\.]{5}([-\+][\w\.0-9]+)?)"
```
2020-09-11 01:29:16 +07:00
This attribute is used as the first argument of a [RegExp](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp) object. The first "group" (i.e. what's in the main set of parenthesis/the whole version number) will be used as the version number. For an example, see this [working example](https://regexr.com/51r8j).
The pattern described in this example is a simple one used. If you need a more complex one [complete pattern](https://regex101.com/r/vkijKf/1/) is:
`^((0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?)$`
2020-09-11 06:49:12 +07:00
As of `1.1.2`, JavaScript named patterns are supported, where the group named `version` will be used to populate the tag. For example:
```yaml
- uses: butlerlogic/action-autotag@1.0.0
env:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
with:
regex_pattern: "(version=)(?<version>[\d+\.]{3}([-\+][\w\.0-9]+)?)"
```
2020-04-05 00:42:31 +07:00
### tag_prefix
By default, [semantic versioning](https://semver.org/) is used, such as `1.0.0`. A prefix can be used to add text before the tag name. For example, if `tag_prefix` is set to `v`, then the tag would be labeled as `v1.0.0`.
```yaml
- uses: butlerlogic/action-autotag@1.0.0
env:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
with:
tag_prefix: "v"
```
2020-04-05 00:42:31 +07:00
### tag_suffix
2019-09-03 06:45:33 +07:00
Text can be applied to the end of the tag by setting `tag_suffix`. For example, if `tag_suffix` is ` (beta)`, the tag would be `1.0.0 (beta)`. Please note this example violates semantic versioning and is merely here to illustrate how to add text to the end of a tag name if you _really_ want to.
```yaml
- uses: butlerlogic/action-autotag@1.0.0
env:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
with:
tag_suffix: " (beta)"
```
2020-04-05 00:42:31 +07:00
### tag_message
This is the annotated commit message associated with the tag. By default, a changelog will be generated from the commits between the latest tag and the current reference (HEAD). Setting this option will override the message.
```yaml
- uses: butlerlogic/action-autotag@1.0.0
env:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
with:
tag_message: "Custom message goes here."
```
2020-04-05 00:42:31 +07:00
### commit_message_template
By default, a changelog is generated, containing the commit messages since the last release. The message is generated by applying a commit message template to each commit's data attributes.
```yaml
- uses: butlerlogic/action-autotag@1.0.0
env:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
with:
commit_message_template: "({{sha}} by {{author}}) {{message}}"
```
Optional data points:
1. `number` The commit number (relevant to the overall list)
1. `message` The commit message.
1. `author` The author of the commit.
1. `sha` The SHA value representing the commit.
The default is `{{number}}) {{message}} ({{author}})\nSHA: {{sha}}\n`.
2020-04-05 00:09:00 +07:00
_Example output:_
```
1) Update README.md (coreybutler)
(SHA: c5e09fc45106a4b27b8f4598fb79811b589a4684)
2) Added metadoc capability to introspect the shell/commands. (coreybutler)
(SHA: b690be366a5636d51b1245a1b39c86102ddb8a81)
```
2020-04-05 00:42:31 +07:00
### version
Explicitly set the version instead of using automatic detection.
Useful for projects where the version number may be output by a previous action.
```yaml
- uses: butlerlogic/action-autotag@1.0.0
env:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
with:
version: "${{ steps.previous_step.outputs.version }}"
```
2022-10-12 23:50:38 +07:00
### min_version
2021-01-30 22:09:56 +07:00
Set the minimum version which would be used to create a tag.
The default value (`0.0.1`) prevents a `0.0.0` from being created. This can also be used when introducing Autotag to a repository which has already tagged.
2021-01-31 03:36:10 +07:00
For example, if the version `0.1.0` would already have been published, set the `minVersion` to the next patch to prevent a duplicate tag for that version.
2021-01-30 22:09:56 +07:00
2022-10-12 23:45:15 +07:00
```yaml
- uses: butlerlogic/action-autotag@1.0.0
with:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
2022-10-12 23:50:38 +07:00
min_version: "0.1.1"
2022-10-12 23:45:15 +07:00
```
2021-06-02 17:53:21 +07:00
2022-10-12 23:50:38 +07:00
### dry_run
2021-06-02 17:53:21 +07:00
If this value is true, the tag will not be pushed.
You can check for duplicate versions when creating a pull request.
2021-01-30 22:09:56 +07:00
```yaml
- uses: butlerlogic/action-autotag@1.0.0
with:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
2022-10-12 23:50:38 +07:00
dry_run: true
2021-01-30 22:09:56 +07:00
```
2022-10-12 23:45:15 +07:00
2019-09-03 06:45:33 +07:00
## Developer Notes
If you are building an action that runs after this one, be aware this action produces several [outputs](https://help.github.com/en/articles/metadata-syntax-for-github-actions#outputs):
1. `tagname` will be empty if no tag was created, or it will be the value of the new tag.
2020-04-05 00:09:00 +07:00
1. `tagrequested`: The name of the requested tag. This will be populated even if the tag is not created. This will usually be the same as `tagname` and/or `version` for successful executions. This output is typically used for rollbacks/notifications when the creation of a tag fails.
2019-09-03 06:45:33 +07:00
1. `tagsha`: The SHA of the new tag.
1. `taguri`: The URI/URL of the new tag reference.
2020-04-05 00:09:00 +07:00
1. `tagmessage`: The message applied to the tag reference (this is what shows up on the tag screen on Github).
1. `tagcreated`: `yes` or `no`.
2020-04-05 00:09:00 +07:00
1. `version` will be the extracted/provided version.
1. `prerelease`: "yes" or "no", indicating the tag represents a semantic version pre-release.
1. `build`: "yes" or "no", indicating the tag represents a semantic version build.
2019-09-03 07:14:19 +07:00
---
## Credits
This action was written and is primarily maintained by [Corey Butler](https://github.com/coreybutler).
2020-04-03 22:04:47 +07:00
This project has had great contributions from [these wonderful people](https://github.com/ButlerLogic/action-autotag/graphs/contributors). Additional gratitude goes to [Jaliborc](https://github.com/Jaliborc), who came up with the idea and original implementation for a pattern-based tag extraction (the Regex strategy).
2020-04-03 22:02:39 +07:00
2020-04-05 00:09:00 +07:00
**Active Sponsors**
2020-04-03 22:02:39 +07:00
These sponsors are helping make this project possible.
<table cellpadding="10" cellspacing="0" border="0">
<tr>
<td><a href="https://metadoc.io"><img src="https://github.com/coreybutler/staticassets/raw/master/sponsors/metadoclogobig.png" width="200px"/></a></td>
<td><a href="https://butlerlogic.com"><img src="https://github.com/coreybutler/staticassets/raw/master/sponsors/butlerlogic_logo.png" width="200px"/></a></td>
</tr>
</table>
# Our Ask...
If you use this or find value in it, please consider contributing in one or more of the following ways:
2019-09-03 07:20:16 +07:00
1. Click the "Sponsor" button at the top of the page and make a contribution.
2019-09-03 07:20:16 +07:00
1. Star it!
2019-09-03 07:38:26 +07:00
1. [Tweet about it!](https://twitter.com/intent/tweet?hashtags=github,actions&original_referer=http%3A%2F%2F127.0.0.1%3A91%2F&text=I%20am%20automating%20my%20workflow%20with%20the%20Autotagger%20Github%20action!&tw_p=tweetbutton&url=https%3A%2F%2Fgithub.com%2Fmarketplace%2Factions%2Fautotagger&via=goldglovecb)
2019-09-03 07:20:16 +07:00
1. Fix an issue.
1. Add a feature (post a proposal in an issue first!).
Copyright &copy; 2020 Butler Logic, Corey Butler, and Contributors.