autoversion/README.md

# Autoversion-action

This action will detect new version.

### Tagging: Part of a Complete Deployment Solution
This action works well in combination with:

- [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)

## Usage

The following is an example `.gitea/workflows/main.yml` that will execute when a `push` to the `master` branch occurs.

```yaml
name: Detect Tag

on:
  push:
    branches:
      - master

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: butlerlogic/action-autotag@stable
      env:
        GITEA_TOKEN: "${{ secrets.GITEA_TOKEN }}"
```

To make this work, the workflow must have the checkout action _before_ the autotag action.

This **order** is important!

```yaml
- uses: actions/checkout@v4
- uses: butlerlogic/action-autotag@stable
```

**If the repository is not checked out first, the autotagger cannot find the source files.**

## Configuration

The `GITEA_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:

```yaml
- uses: butlerlogic/action-autotag@stable
  env:
    GITEA_TOKEN: "${{ secrets.GITEA_TOKEN }}"
```

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).

## Optional Configuration Options

There are several options to customize how the tag is created.

### root

Depending on the selected strategy, autotagger will look for the confgured identify file (i.e. `package.json`, `composer.json`, `Dockerfile`, etc) in the project root. If the file is located in a subdirectory, this option can be used to point to the correct file.

```yaml
- uses: butlerlogic/action-autotag@1.0.0
  env:
    GITEA_TOKEN: "${{ secrets.GITEA_TOKEN }}"
  with:
    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:
    GITEA_TOKEN: "${{ secrets.GITEA_TOKEN }}"
  with:
    regex_pattern: "version=([0-9\.]{5}([-\+][\w\.0-9]+)?)"
```

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 simplistic one. If you need a more explicit one the [complete semver 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-]+)*))?)$
```

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:
    GITEA_TOKEN: "${{ secrets.GITEA_TOKEN }}"
  with:
    regex_pattern: "(version=)(?<version>[\d+\.]{3}([-\+][\w\.0-9]+)?)"
```

### 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:
    GITEA_TOKEN: "${{ secrets.GITEA_TOKEN }}"
  with:
    tag_prefix: "v"
```

### 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:
    GITEA_TOKEN: "${{ secrets.GITEA_TOKEN }}"
  with:
    tag_message: "Custom message goes here."
```

### 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:
    GITEA_TOKEN: "${{ secrets.GITEA_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`.

_Example output:_

```
1) Update README.md (coreybutler)
(SHA: c5e09fc45106a4b27b8f4598fb79811b589a4684)

2) Added metadoc capability to introspect the shell/commands. (coreybutler)
(SHA: b690be366a5636d51b1245a1b39c86102ddb8a81)
```

## 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. `tagcreated`: `yes` or `no`.
1. `version` will be the extracted/provided version.

---