> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# kohirens/version-release

Provides updating a CHANGELOG.md based on commit messages,
and produce a release tag based on semantic versioning.
Add to your CI pipeline to automate this process.

**Disclaimer**
This Orb does not collect any data or make use of your information.


## Commands

### gh-has-release

Check if the release exist on GitHub.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `attach_workspace_path` | string | . | Set where to attach the workspace. |
| `file` | string | has-release.txt | File containing the response for checking if the release was found or not. |
| `owner` | string |  | GitHub organization containing the repository to check. |
| `repo` | string |  | GitHub repository to check. |
| `tag_cmd` | string |  | Command to run to get the release tag, will override the auto generated value. |
| `tag_env_var` | string |  | Environment variable to get the release tag, will override the auto generated value. |
| `tag_file` | string |  | File to get the release tag, will override the auto generated value. |

## Jobs

### gh-has-release

Check if the release exist on GitHub.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `attach_workspace_path` | string | . | Set where to attach the workspace. |
| `do_attach_workspace` | boolean | false | Set this to `true` to attaching the workspace or false to skip this step.
 |
| `do_checkout` | boolean | true | In case you need to customize. |
| `exec_img_tag` | string | VERSION_RELEASE_IMAGE | Version of the executor image to pull. |
| `file` | string | has-release.txt | File containing the response for checking if the release was found or not. |
| `owner` | string |  | GitHub organization containing the repository to check. |
| `repo` | string |  | GitHub repository to check. |
| `tag_cmd` | string |  | Command to run to get the release tag, will override the auto generated value. |
| `tag_env_var` | string |  | Environment variable to get the release tag, will override the auto generated value. |
| `tag_file` | string |  | File to get the release tag, will override the auto generated value. |

### publish-changelog

Commit changes to the changelog and merge into a remote branch using the
process:

1. Configure Git to allow a commit.
2. Making a new branch.
3. Detect and commit the changes to the CHANGELOG, if none, then exit.
4. Pushing the branch back to remote GitHub.
5. Use the GitHub CLI to make a PR.
6. Then immediately merge the changes in the desired branch.

We use a PR instead of a push in case the branch is protected from direct
pushes.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `add_files_to_commit` | string |  | A text file (UTF-8) containing 1 file per line to add along with the
changelog commit. The path should be relative to the root of the
repository. Line endings can be Linux, Mac, or Windows. These are usually
files that need to be generated with the next semantic tag or other
release information.
 |
| `attach_workspace_path` | string | . | Set where to attach the workspace. |
| `changelog_file` | string | CHANGELOG.md | Location to output/update the CHANGELOG file. |
| `committer_email` | string |  | Git user email address to use when commiting the changelog. |
| `committer_gpg_key` | string |  | Git user GPG key to use when commiting the changelog. |
| `committer_name` | string |  | Git username to use when commiting the changelog. |
| `do_attach_workspace` | boolean | false | Set this to `true` to attaching the workspace or false to skip this step. If you do set this to false, then you may want to set `do_checkout` to true.
 |
| `do_checkout` | boolean | true | Set this to true to perform a checkout step, or false to skip. If you do set this to false, then you may want to set `do_attach_workspace` to true.
 |
| `enable_tag_v_prefix` | boolean | false | Prefix git tags with a "v" before the semantic version number.
 |
| `exec_img_tag` | string | 5.1.10 | Version of the executor image to pull. |
| `github_api_url` | string | https://api.github.com | Github API URL. |
| `github_server` | string | github.com | GitHub server domain name. |
| `main_trunk_branch` | string | main | Name of the main trunk branch to tag. |
| `merge_type` | enum | rebase | Type of merge to perform, choose between merge|squash|rebase. |
| `tag_cmd` | string |  | Command to run to get the semantic version tag, will override the auto
generated value.
 |
| `tag_env_var` | string |  | Environment variable to get the semantic version tag, will override the
auto generated value.
 |
| `tag_file` | string |  | File to get the semantic version tag, will override the auto generated
value.
 |
| `working_directory` | string | . | In case you need to customize, defaults to the current dir. |

### publish-docker-hub

Publish an image to Docker Hub.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `attach_workspace_path` | string | . | Set where to attach the workspace. |
| `build_args` | string |  | Build arguments, for example --build-arg "foo". |
| `build_context` | string | . | Set where to attach the workspace. |
| `do_attach_workspace` | boolean | false | Set this to `true` to attaching the workspace or false to skip this
step. If you do set this to false, then you may want to set
`do_checkout` to true.
 |
| `do_checkout` | boolean | true | Set this to true to perform a checkout step, or false to skip.
If you do set this to false, then you may want to set
`do_attach_workspace` to true.
 |
| `docker_buildkit` | string | 1 | Set the Docker environment variable DOCKER_BUILDKIT |
| `dockerfile` | string | Dockerfile | Path to the Docker environment variable DOCKER_BUILDKIT |
| `env_file` | string |  | Environment file containing variable value pairs to export to the build environment. |
| `image_tag` | string |  | Obsolete, use tags parameter instead. This parameter will be removed in the next major release. A single tag to stamp the image in Docker Hub. |
| `repository` | string |  | Docker Hub image repository for example "kohirens/version-release".
 |
| `tag_cmd` | string |  | Command to run to get the semantic version tag, will override the auto generated value. |
| `tag_env_var` | string |  | Environment variable to get the semantic version tag, will override the auto generated value. |
| `tag_file` | string |  | File to get the semantic version tag, will override the auto generated value. |
| `tags` | string |  | Tags to stamp the image and push to Docker Hub. Space delimited. |
| `target` | string |  | Set the build target,
see https://docs.docker.com/engine/reference/commandline/build/#target
 |

### tag-and-release

Publish a tag on a specified branch.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `abort_dupe_release` | boolean | false | Gracefully abort publishing a release if it already exists. |
| `attach_workspace_path` | string | . | Set where to attach the workspace. |
| `do_attach_workspace` | boolean | false | Set to `true` to perform attach_workspace. |
| `do_checkout` | boolean | true | Set to `false` to skip performing a checkout. |
| `enable_tag_v_prefix` | boolean | false | Prefix git tags with a "v" before the semantic version number.
 |
| `exec_img_tag` | string | 5.1.10 | Version of the executor image to pull. |
| `github_api_url` | string | https://api.github.com | Github API URL. |
| `github_server` | string | github.com | GitHub server domain name. |
| `main_trunk_branch` | string | main | Name of the main trunk branch to tag. |
| `owner` | string |  | GitHub organization containing the repository to check. |
| `release_file` | string | has-release.txt | File containing the response for checking if the release was found or not. |
| `repo` | string |  | GitHub repository to check. |
| `tag_cmd` | string |  | Command to run to get the semantic version tag, will override the auto generated value. |
| `tag_env_var` | string |  | Environment variable to get the semantic version tag, will override the auto generated value. |
| `tag_file` | string |  | File to get the semantic version tag, will override the auto generated value. |
| `working_directory` | string | . | In case you need to customize, defaults to the current dir. |

### workflow-selector

Selects a workflow to execute when code is merged into main.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `attach_workspace_path` | string | . | Set where to attach the workspace. |
| `changelog_file` | string | CHANGELOG.md | Location to output/update the CHANGELOG file. |
| `circle_token_var` | env_var_name | CIRCLE_TOKEN | Set the environment variable that has the CircleCI API token. |
| `circleci_api_host` | string | https://circleci.com | Host URL of CircleCI API, i.e. https://circleci.com |
| `circleci_app_host` | string | https://app.circleci.com | Host URL of CircleCI Web UI, i.e. https://app.circleci.com |
| `do_attach_workspace` | boolean | false | Set this to `true` to attaching the workspace or false to skip this step.
 |
| `do_checkout` | boolean | true | In case you need to customize. |
| `enable_tag_v_prefix` | boolean | false | Prefix git tags with a "v" before the semantic version number.
 |
| `exec_img_tag` | string | 5.1.10 | Version of the executor image to pull. |
| `github_api_url` | string | https://api.github.com | Github API URL. |
| `github_server` | string | github.com | GitHub server domain name. |
| `main_trunk_branch` | string | main | Name of the main trunk branch to tag. |
| `tag_cmd` | string |  | Command to run to get the semantic version tag, will override the auto generated value. |
| `tag_env_var` | string |  | Environment variable to get the semantic version tag, will override the auto generated value. |
| `tag_file` | string |  | File to get the semantic version tag, will override the auto generated value. |
| `vcs_type` | enum | gh | VCS type. Only Github `gh` is supported. No BitBucket `bb` yet. |
| `working_directory` | string | . | In case you need to customize, defaults to the current dir. |

## Executors

### cimg-base

CircleCI base image

| Parameter | Type | Default | Description |
|---|---|---|---|
| `exec_img_tag` | string | 2023.04 |  |

### default

version release executor with git-tool-belt.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `exec_img_tag` | string | 5.1.10 |  |

## Examples

### auto-release

Will trigger when changes are merged into the main trunk. A new changelog will
be generated and auto merged into the main trunk; then a release will be
published for the main trunk branch in this example.

There are some prerequisites, so please go to
https://github.com/kohirens/version-release/blob/5.1.10/docs/how-to-release.md
which provides details on how to setup the following:

  1. Allow CircleCI to write back to a Github repository on your behalf
     to make branches and pull-request, via SSH and API.
  2. Allow CircleCI to trigger workflows using the CircleCI API.

Required Environment Variables:

  * CIRCLE_TOKEN
  * GH_WRITE_TOKEN


```yaml
version: '2.1'
orbs:
  avr: kohirens/version-release@latest
workflows:
  on-tag-release:
    jobs:
      - add-your-jobs-here:
          context: << pipeline.parameters.ctx_auto_release >>
          filters:
            branches:
              ignore: /.*/
            tags:
              only: /^v?\d+\.\d+\.\d+$/
  publish-changelog:
    jobs:
      - vr/publish-changelog:
          committer_email: rando@example.com
          committer_name: rando
          context: << pipeline.parameters.ctx_auto_release >>
    when:
      and:
        - equal:
            - publish-changelog
            - << pipeline.parameters.triggered_flow >>
  publish-release-tag:
    jobs:
      - vr/tag-and-release:
          context: << pipeline.parameters.ctx_auto_release >>
    when:
      and:
        - equal:
            - publish-release-tag
            - << pipeline.parameters.triggered_flow >>
  workflow-selector:
    jobs:
      - vr/workflow-selector:
          context: << pipeline.parameters.ctx_auto_release >>
    when:
      and:
        - equal:
            - workflow-selector
            - << pipeline.parameters.triggered_flow >>
        - equal:
            - main
            - << pipeline.git.branch >>
```