actions/semantic-release-action
5
0
Fork 0
mirror of https://github.com/cycjimmy/semantic-release-action.git synced 2025-11-07 10:46:56 +00:00
Code Activity Actions

docs(*): optimize documents

Browse source
This commit is contained in:
cycjimmy 2020-03-21 23:26:05 +08:00
parent db8c9adefb
commit e91639a768
1 changed files with 102 additions and 42 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

144
README.md
View file

@ -1,39 +1,19 @@
# Semantic Release Action # Semantic Release Action
![][workflows-badge-image] ![][workflows-badge-image]
[![Release date][release-date-image]][release-url]
[![semantic-release][semantic-image]][semantic-url] [![semantic-release][semantic-image]][semantic-url]
![npm license][license-image] [![npm license][license-image]][license-url]
[workflows-badge-image]: https://github.com/cycjimmy/semantic-release-action/workflows/Test%20Release/badge.svg
[semantic-url]: https://github.com/semantic-release/semantic-release
[semantic-image]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
[license-image]: https://img.shields.io/npm/l/@cycjimmy/semantic-release-action.svg?style=flat-square
GitHub Action for [Semantic Release](https://github.com/semantic-release/semantic-release). GitHub Action for [Semantic Release](https://github.com/semantic-release/semantic-release).
## Usage ## Usage
#### Step1: Set any [Semantic Release Configuration](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration) in your repository. ### Step1: Set any [Semantic Release Configuration](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration) in your repository.
#### Step2: [Add Secrets](https://help.github.com/en/articles/virtual-environments-for-github-actions#creating-and-using-secrets-encrypted-variables) in your repository for the [Semantic Release Authentication](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/ci-configuration.md#authentication) Environment Variables. ### Step2: [Add Secrets](https://help.github.com/en/articles/virtual-environments-for-github-actions#creating-and-using-secrets-encrypted-variables) in your repository for the [Semantic Release Authentication](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/ci-configuration.md#authentication) Environment Variables.
#### Step3: Add a [Workflow File](https://help.github.com/en/articles/workflow-syntax-for-github-actions) to your repository to create custom automated processes. ### Step3: Add a [Workflow File](https://help.github.com/en/articles/workflow-syntax-for-github-actions) to your repository to create custom automated processes.
* inputs:
* `semantic_version`: [Optional] Specify specifying version range for semantic-release. If no version range is specified, latest version will be used by default.
* `branches`: [Optional] The branches on which releases should happen. It will override the branches attribute in your configuration file. If the attribute is not configured on both sides, the default is `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`. **Support for semantic-release above v16**. See https://semantic-release.gitbook.io/semantic-release/usage/configuration#branches for more information.
* `branch`: [Optional] The branch on which releases should happen. It will override the branch attribute in your configuration file. If the attribute is not configured on both sides, the default is master. **Support for semantic-release older than v16**.
* `extra_plugins`: [Optional] Extra plugins for pre-install. You can also specify specifying version range for the extra plugins if you prefer.
* `dry_run`: [Optional] Whether to run semantic release in `dry-run` mode. It will override the dryRun attribute in your configuration file.
* outputs:
* `new_release_published`: Whether a new release was published. `true` or `false`
* `new_release_version`: Version of the new release
* `new_release_major_version`: Major version of the new release
* `new_release_minor_version`: Minor version of the new release
* `new_release_patch_version`: Patch version of the new release
* `new_release_notes`: The release notes for the new release.
### Examples
#### A simple example
#### Basic Usage:
```yaml ```yaml
steps: steps:
- name: Checkout - name: Checkout
@ -45,8 +25,20 @@ steps:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
``` ```
#### Setting `semantic_version` and `branch | branches` manually **IMPORTANT**: `GITHUB_TOKEN` does not have the required permissions to operate on protected branches.
It is recommended to specify specifying version range for semantic-release. If no version range is specified, latest version will be used by default. If you are using this action for protected branches, replace `GITHUB_TOKEN` with [Personal Access Token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line).
### Inputs
| Input Parameter | Required | Description |
|:----------------:|:--------:|-------------|
| semantic_version | false | [Details](#semantic_version) |
| branches | false | [Details](#branches) |
| branch | false | [Details](#branch) |
| extra_plugins | false | [Details](#extra_plugins) |
| dry_run | false | [Details](#dry_run) |
#### semantic_version
> {Optional Input Parameter} Specify specifying version range for semantic-release. If no version range is specified, latest version will be used by default.
```yaml ```yaml
steps: steps:
@ -57,12 +49,16 @@ steps:
with: with:
semantic_version: 15.13.28 # It is recommended to specify specifying version range semantic_version: 15.13.28 # It is recommended to specify specifying version range
# for semantic-release. # for semantic-release.
branch: master # you can set branch for semantic-release older than v16.
env: env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
``` ```
**It is recommended to manually specify a version of semantic-release and its plugins to prevent errors caused during the official semantic-release upgrade.**
#### branches
> {Optional Input Parameter} The branches on which releases should happen. `branches` supports for **semantic-release above v16**.
```yaml ```yaml
steps: steps:
- name: Checkout - name: Checkout
@ -92,11 +88,48 @@ steps:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
``` ```
#### Passing Extra Plugins with `extra_plugins` `branches` will override the `branches` attribute in your configuration file. If the attribute is not configured on both sides, the default is:
```
[
'+([0-9])?(.{+([0-9]),x}).x',
'master',
'next',
'next-major',
{name: 'beta', prerelease: true},
{name: 'alpha', prerelease: true}
]
```
See [configuration#branches](https://semantic-release.gitbook.io/semantic-release/usage/configuration#branches) for more information.
#### branch
> {Optional Input Parameter} Similar to parameter `branches`. The branch on which releases should happen. `branch` only supports for **semantic-release older than v16**.
```yaml
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Semantic Release
uses: cycjimmy/semantic-release-action@v2
with:
semantic_version: 15.13.28
# you can set branch for semantic-release older than v16.
branch: your-branch
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
```
It will override the `branch` attribute in your configuration file. If the attribute is not configured on both sides, the default is `master`.
#### extra_plugins
> {Optional Input Parameter} Extra plugins for pre-install.
##### Passing Extra Plugins with `extra_plugins`:
The action can be used with `extra_plugins` option to specify plugins which are not in the [default list of plugins of semantic release](https://semantic-release.gitbook.io/semantic-release/usage/plugins#default-plugins). When using this option, please make sure that these plugins are also mentioned in your [semantic release config's plugins](https://semantic-release.gitbook.io/semantic-release/usage/configuration#plugins) array. For example, if you want to use `@semantic-release/git` and `@semantic-release/changelog` extra plugins, these must be added to `extra_plugins` in your actions file and `plugins` in your [release config file](https://semantic-release.gitbook.io/semantic-release/usage/configuration#configuration-file) as shown bellow: The action can be used with `extra_plugins` option to specify plugins which are not in the [default list of plugins of semantic release](https://semantic-release.gitbook.io/semantic-release/usage/plugins#default-plugins). When using this option, please make sure that these plugins are also mentioned in your [semantic release config's plugins](https://semantic-release.gitbook.io/semantic-release/usage/configuration#plugins) array. For example, if you want to use `@semantic-release/git` and `@semantic-release/changelog` extra plugins, these must be added to `extra_plugins` in your actions file and `plugins` in your [release config file](https://semantic-release.gitbook.io/semantic-release/usage/configuration#configuration-file) as shown bellow:
_github-action_ ##### Github Action Workflow:
```yaml ```yaml
steps: steps:
- name: Checkout - name: Checkout
@ -113,20 +146,19 @@ steps:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
``` ```
_release-config_ **It is recommended to manually specify a version of semantic-release and its plugins to prevent errors caused during the official semantic-release upgrade.**
##### Release Config:
```diff ```diff
plugins: [ plugins: [
. .
.
+ "@semantic-release/changelog" + "@semantic-release/changelog"
+ "@semantic-release/git", + "@semantic-release/git",
] ]
``` ```
#### Manually Specify a Version of Semantic-release and Its Plugins #### dry_run
> {Optional Input Parameter} Whether to run semantic release in `dry-run` mode.<br> It will override the dryRun attribute in your configuration file.
It is recommended to manually specify a version of semantic-release and its plugins to prevent errors caused during the official semantic-release upgrade.
```yaml ```yaml
steps: steps:
@ -135,16 +167,23 @@ steps:
- name: Semantic Release - name: Semantic Release
uses: cycjimmy/semantic-release-action@v2 uses: cycjimmy/semantic-release-action@v2
with: with:
semantic_version: 15.14.0 dry_run: true
extra_plugins: |
@semantic-release/git@7.0.18
env: env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
``` ```
#### Using Output Variables ### Outputs
| Output Parameter | Description |
|:-------------------------:|---|
| new_release_published | Whether a new release was published (`true` or `false`) |
| new_release_version | Version of the new release. (e.g. `1.3.0`) |
| new_release_major_version | Major version of the new release. (e.g. `1`) |
| new_release_minor_version | Minor version of the new release. (e.g. `3`) |
| new_release_patch_version | Patch version of the new release. (e.g. `0`) |
| new_release_notes | The release notes for the new release. |
Using Output Variables:
```yaml ```yaml
steps: steps:
- name: Checkout - name: Checkout
@ -158,8 +197,29 @@ steps:
- name: Do something when a new release published - name: Do something when a new release published
if: steps.semantic.outputs.new_release_published == 'true' if: steps.semantic.outputs.new_release_published == 'true'
run: echo ${{ steps.semantic.outputs.new_release_version }} run: |
echo ${{ steps.semantic.outputs.new_release_version }}
echo ${{ steps.semantic.outputs.new_release_major_version }}
echo ${{ steps.semantic.outputs.new_release_minor_version }}
echo ${{ steps.semantic.outputs.new_release_patch_version }}
``` ```
## [CHANGELOG](./docs/CHANGELOG.md) ## Changelog
See [CHANGELOG.md][changelog-url].
## License
This project are released under the [MIT License][license-url].
<!-- Links: -->
[workflows-badge-image]: https://github.com/cycjimmy/semantic-release-action/workflows/Test%20Release/badge.svg
[release-date-image]: https://img.shields.io/github/release-date/cycjimmy/semantic-release-action
[release-url]: https://github.com/cycjimmy/semantic-release-action/releases
[semantic-image]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
[semantic-url]: https://github.com/semantic-release/semantic-release
[license-image]: https://img.shields.io/npm/l/@cycjimmy/semantic-release-action.svg
[license-url]: https://github.com/cycjimmy/semantic-release-action/blob/master/LICENSE
[changelog-url]: https://github.com/cycjimmy/semantic-release-action/blob/master/docs/CHANGELOG.md