autotag/README.md

138 lines
4.8 KiB
Markdown
Raw Normal View History

2019-09-03 04:12:28 +07:00
# Autotag
2019-09-03 03:40:00 +07:00
2019-09-03 06:51:13 +07:00
This action will read a `package.json` file and compare the `version` attribute to the project's known tags. If a corresponding tag does not exist, it will be created.
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
2019-09-03 06:45:33 +07:00
with:
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 passed in. Without this, it is not possible to create a new tag. Make sure the autotag action looks like the following example:
```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
### Optional Configurations
There are several options to customize how the tag is created.
2019-09-03 06:49:51 +07:00
1. `package_root`
2019-09-20 00:53:54 +07:00
By default, autotag will look for the `package.json` file in the project root. If the file is located in a subdirectory, this option can be used to point to the correct file.
2019-09-03 06:49:51 +07:00
```yaml
- uses: butlerlogic/action-autotag@1.0.0
with:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
package_root: "/path/to/subdirectory"
```
2020-01-24 22:38:54 +07:00
1. `tag_prefix`
2019-09-03 06:45:33 +07:00
By default, `package.json` uses [semantic versioning](https://semver.org/), such as `1.0.0`. A prefix can be used to add text before the tag name. For example, if `tag_prefx` is set to `v`, then the tag would be labeled as `v1.0.0`.
2019-09-03 06:45:33 +07:00
```yaml
- uses: butlerlogic/action-autotag@1.0.0
with:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
2020-01-24 22:38:54 +07:00
tag_prefix: "v"
2019-09-03 06:45:33 +07:00
```
2019-09-03 06:45:33 +07:00
1. `tag_suffix`
2019-09-03 06:45:33 +07:00
Text can also 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.
2019-09-03 06:45:33 +07:00
```yaml
- uses: butlerlogic/action-autotag@1.0.0
with:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
tag_suffix: " (beta)"
```
2019-09-03 06:45:33 +07:00
1. `tag_message`
2019-09-03 06:45:33 +07:00
This is the annotated commit message associated with the tag. By default, a
2019-09-20 00:53:54 +07:00
changelog will be generated from the commits between the latest tag and the new tag (HEAD). Setting this option will override it witha custom message.
2019-09-03 06:45:33 +07:00
```yaml
- uses: butlerlogic/action-autotag@1.0.0
with:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
tag_message: "Custom message goes here."
```
1. `version`
Explicitly set the version instead of automatically detecting from `package.json`.
Useful for non-JavaScript projects where version may be output by a previous action.
```yaml
- uses: butlerlogic/action-autotag@1.0.0
with:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
version: "${{ steps.previous_step.outputs.version }}"
```
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.
1. `tagsha`: The SHA of the new tag.
1. `taguri`: The URI/URL of the new tag reference.
2019-09-03 07:04:57 +07:00
1. `tagmessage`: The messge applied to the tag reference (this is what shows up on the tag screen on Github).
2019-09-03 07:14:19 +07:00
1. `version` will be the version attribute found in the `package.json` file.
---
## Credits
This action was written and is primarily maintained by [Corey Butler](https://github.com/coreybutler).
# 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.
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!).
2019-09-03 07:35:10 +07:00
Copyright © 2019 ButlerLogic, Corey Butler, and Contributors.