semantic-release-action/README.md

Semantic Release Action

GitHub Action for Semantic Release.

Usage

Step1: Set any Semantic Release Configuration in your repository.

Step2: Add Secrets in your repository for the Semantic Release Authentication Environment Variables.

Step3: Add a Workflow File to your repository to create custom automated processes.

Basic Usage:

steps:
  - name: Checkout
    uses: actions/checkout@v2
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v2
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

IMPORTANT: GITHUB_TOKEN does not have the required permissions to operate on protected branches. If you are using this action for protected branches, replace GITHUB_TOKEN with Personal Access Token.

Inputs

Input Parameter	Required	Description
semantic_version	false	Details
branches	false	Details
branch	false	Details
extra_plugins	false	Details
dry_run	false	Details

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.

steps:
  - name: Checkout
    uses: actions/checkout@v2
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v2
    with:
      semantic_version: 15.13.28  # It is recommended to specify specifying version range
                                  # for semantic-release.
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_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.

steps:
  - name: Checkout
    uses: actions/checkout@v2
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v2
    with:
      semantic_version: 16
      # you can set branches for semantic-release above v16.
      branches: |    
        [
          '+([0-9])?(.{+([0-9]),x}).x',
          'master', 
          'next', 
          'next-major', 
          {
            name: 'beta', 
            prerelease: true
          }, 
          {
            name: 'alpha', 
            prerelease: true
          }
        ]
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

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

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. When using this option, please make sure that these plugins are also mentioned in your semantic release config's 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 as shown bellow:

Github Action Workflow:

steps:
  - name: Checkout
    uses: actions/checkout@v2
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v2
    with:
      # You can specify specifying version range for the extra plugins if you prefer.
      extra_plugins: |
        @semantic-release/changelog@3.0.0
        @semantic-release/git        
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_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.

Release Config:

  plugins: [
    .
+   "@semantic-release/changelog"
+   "@semantic-release/git",
  ]

dry_run

{Optional Input Parameter} Whether to run semantic release in dry-run mode.
It will override the dryRun attribute in your configuration file.

steps:
  - name: Checkout
    uses: actions/checkout@v2
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v2
    with:
      dry_run: true
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

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:

steps:
  - name: Checkout
    uses: actions/checkout@v2
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v2
    id: semantic   # Need an `id` for output variables
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
      
  - name: Do something when a new release published
    if: steps.semantic.outputs.new_release_published == 'true'
    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

See CHANGELOG.md.

License

This project are released under the MIT License.