Skip to content

Latest commit

 

History

History
217 lines (180 loc) · 9.17 KB

README.md

File metadata and controls

217 lines (180 loc) · 9.17 KB

Release Please Action

Conventional Commits

Automate releases with Conventional Commit Messages.

Setting up this action

  1. If you haven't already done so, create a .github/workflows folder in your repository (this is where your actions will live).

  2. Now create a .github/workflows/release-please.yml file with these contents:

     on:
       push:
         branches:
           - main
     name: release-please
     jobs:
       release-please:
         runs-on: ubuntu-latest
         steps:
           - uses: GoogleCloudPlatform/release-please-action@v2
             with:
               token: ${{ secrets.GITHUB_TOKEN }}
               release-type: node
               package-name: release-please-action
  3. Merge the above action into your repository and make sure new commits follow the Conventional Commits convention, release-please will start creating Release PRs for you.

Configuration

input description
token A GitHub secret token, you will most likely want to use the special secrets.GITHUB_TOKEN
release-type What type of project is this a release for? Reference Release types supported; new types of releases can be added here
package-name A name for the artifact releases are being created for (this might be the name field in a setup.py or package.json)
bump-minor-pre-major Should breaking changes before 1.0.0 produce minor bumps? Default No
path create a release from a path other than the repository's root
monorepo-tags add prefix to tags and branches, allowing multiple libraries to be released from the same repository.
changelog-types A JSON formatted String containing to override the outputted changelog sections
version-file provide a path to a version file to increment (used by ruby releaser)
fork Should the PR be created from a fork (does not work with secrets.GITHUB_TOKEN)
command release-please command to run, either github-release, or release-pr (defaults to running both)
output description
release_created true if the release was created, false otherwise
upload_url Directly related to Create a release API
html_url Directly related to Create a release API
tag_name Directly related to Create a release API
major Number representing major semver value
minor Number representing minor semver value
patch Number representing patch semver value
sha sha that a GitHub release was tagged at
pr The PR number of an opened release (undefined if no release created)

Release types supported

Release Please automates releases for the following flavors of repositories:

release type description
node A Node.js repository, with a package.json and CHANGELOG.md
python A Python repository, with a setup.py, setup.cfg, version.py and CHANGELOG.md
ruby A Ruby repository, with version.rb and CHANGELOG.md
terraform-module A terraform module, with a version in the README.md, and a CHANGELOG.md
simple A repository with a version.txt and a CHANGELOG.md

How release please works

Release Please automates CHANGELOG generation, the creation of GitHub releases, and version bumps for your projects. Release Please does so by parsing your git history, looking for Conventional Commit messages, and creating release PRs.

What's a Release PR?

Rather than continuously releasing what's landed to your default branch, release-please maintains Release PRs:

These Release PRs are kept up-to-date as additional work is merged. When you're ready to tag a release, simply merge the release PR.

How should I write my commits?

Release Please assumes you are using Conventional Commit messages.

The most important prefixes you should have in mind are:

  • fix: which represents bug fixes, and correlates to a SemVer patch.
  • feat: which represents a new feature, and correlates to a SemVer minor.
  • feat!:, or fix!:, refactor!:, etc., which represent a breaking change (indicated by the !) and will result in a SemVer major.

Overriding the Changelog Sections

To output more commit information in the changelog, a JSON formatted String can be added to the Action using the changelog-types input parameter. This could look something like this:

    on:
      push:
        branches:
          - main
    name: release-please
    jobs:
      release-please:
        runs-on: ubuntu-latest
        steps:
          - uses: GoogleCloudPlatform/release-please-action@v2
            with:
              token: ${{ secrets.GITHUB_TOKEN }}
              release-type: node
              package-name: release-please-action
              changelog-types: '[{"type":"feat","section":"Features","hidden":false},{"type":"fix","section":"Bug Fixes","hidden":false},{"type":"chore","section":"Miscellaneous","hidden":false}]'

Automating publication to npm

With a few additions, the Release Please action can be made to publish to npm when a Release PR is merged:

on:
  push:
    branches:
      - main
name: release-please
jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: GoogleCloudPlatform/release-please-action@v2
        id: release
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          release-type: node
          package-name: test-release-please
      # The logic below handles the npm publication:
      - uses: actions/checkout@v2
        # these if statements ensure that a publication only occurs when
        # a new release is created:
        if: ${{ steps.release.outputs.release_created }}
      - uses: actions/setup-node@v1
        with:
          node-version: 12
          registry-url: 'https://registry.npmjs.org'
        if: ${{ steps.release.outputs.release_created }}
      - run: npm ci
        if: ${{ steps.release.outputs.release_created }}
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
        if: ${{ steps.release.outputs.release_created }}

So that you can keep 2FA enabled for npm publications, we recommend setting registry-url to your own Wombat Dressing Room deployment.

Creating major/minor tags

If you are using release-please to publish a GitHub action, you will likely want to tag a major and minor tag during a release, i.e., if you are releasing v2.8.3, you will also want to update tags v2 and v2.8. This allows your users to pin to v2, and get updates to your library without updating their workflows.

The release-please-action has the outputs major, minor, and release_created to facilitate this. These outputs can be used conditionally, like so:

on:
  push:
    branches:
      - main
name: release-please
jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: GoogleCloudPlatform/release-please-action@v2
        id: release
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          release-type: node
          package-name: ${{env.ACTION_NAME}}
          command: github-release
      - uses: actions/checkout@v2
      - name: tag major and patch versions
        if: ${{ steps.release.outputs.release_created }}
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
          git remote add gh-token "https://${{ secrets.GITHUB_TOKEN}}@github.com/google-github-actions/release-please-action.git"
          git tag -d v${{ steps.release.outputs.major }} || true
          git tag -d v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }} || true
          git push origin :v${{ steps.release.outputs.major }} || true
          git push origin :v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }} || true
          git tag -a v${{ steps.release.outputs.major }} -m "Release v${{ steps.release.outputs.major }}"
          git tag -a v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }} -m "Release v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }}"
          git push origin v${{ steps.release.outputs.major }}
          git push origin v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }}

License

Apache Version 2.0