From f645547f2f30eb59179f1d22da13612ba5090f38 Mon Sep 17 00:00:00 2001 From: "Alisson R. Perez" Date: Wed, 23 Oct 2019 14:47:24 -0300 Subject: [PATCH] docs(recipes): GitHub actions (#1317) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Natan Sągol --- docs/recipes/README.md | 1 + docs/recipes/github-actions.md | 68 ++++++++++++++++++++++++++++++++++ docs/usage/ci-configuration.md | 1 + 3 files changed, 70 insertions(+) create mode 100644 docs/recipes/github-actions.md diff --git a/docs/recipes/README.md b/docs/recipes/README.md index d839f0d59b..000ddd7a55 100644 --- a/docs/recipes/README.md +++ b/docs/recipes/README.md @@ -4,6 +4,7 @@ - [CircleCI 2.0 workflows](circleci-workflows.md) - [Travis CI](travis.md) - [GitLab CI](gitlab-ci.md) +- [GitHub Actions](github-actions.md) ## Git hosted services - [Git authentication with SSH keys](git-auth-ssh-keys.md) diff --git a/docs/recipes/github-actions.md b/docs/recipes/github-actions.md new file mode 100644 index 0000000000..a92c2470ba --- /dev/null +++ b/docs/recipes/github-actions.md @@ -0,0 +1,68 @@ +# Using semantic-release with [GitHub Actions](https://help.github.com/en/categories/automating-your-workflow-with-github-actions) + +## Environment variables + +The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured with [Secret Variables](https://help.github.com/en/articles/virtual-environments-for-github-actions#creating-and-using-secrets-encrypted-variables). + +In this example an [`NPM_TOKEN`](https://docs.npmjs.com/creating-and-viewing-authentication-tokens) is required to publish a package to the npm registry. GitHub Actions [automatically populate](https://help.github.com/en/articles/virtual-environments-for-github-actions#github_token-secret) a [`GITHUB_TOKEN`](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) environment variable which can be used in Workflows. + +## Node project configuration + +[GitHub Actions](https://github.com/features/actions) support [Workflows](https://help.github.com/en/articles/configuring-workflows), allowing to run tests on multiple Node versions and publish a release only when all test pass. + +**Note**: The publish pipeline must run on [Node version >= 8.3](../support/FAQ.md#why-does-semantic-release-require-node-version--83). + +### `.github/workflows/release.yml` configuration for Node projects + +The following is a minimal configuration for [`semantic-release`](https://github.com/semantic-release/semantic-release) with a build running on Node 12 when a new commit is pushed to a `master` branch. See [Configuring a Workflow](https://help.github.com/en/articles/configuring-a-workflow) for additional configuration options. + +```yaml +name: Release +on: + push: + branches: + - master +jobs: + release: + name: Release + runs-on: ubuntu-18.04 + steps: + - name: Checkout + uses: actions/checkout@v1 + - name: Setup Node.js + uses: actions/setup-node@v1 + with: + node-version: 12 + - name: Install dependencies + run: npm ci + - name: Release + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} + run: npx semantic-release +``` + +## Pushing `package.json` changes to a `master` branch + +To keep `package.json` updated in the `master` branch, [`@semantic-release/git`](https://github.com/semantic-release/git) plugin can be used. + +**Note**: Automatically populated `GITHUB_TOKEN` cannot be used if branch protection is enabled for the target branch. It is **not** advised to mitigate this limitation by overriding an automatically populated `GITHUB_TOKEN` variable with a [Personal Access Tokens](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line), as it poses a security risk. Since Secret Variables are available for Workflows triggered by any branch, it becomes a potential vector of attack, where a Workflow triggered from a non-protected branch can expose and use a token with elevated permissions, yielding branch protection insignificant. One can use Personal Access Tokens in trusted environments, where all developers should have the ability to perform administrative actions in the given repository and branch protection is enabled solely for convenience purposes, to remind about required reviews or CI checks. + +## Trigger semantic-release on demand + +There is a way to trigger semantic-relase on demand. Use [`repository_dispatch`](https://help.github.com/en/articles/events-that-trigger-workflows#external-events-repository_dispatch) event to have control on when to generate a release by making an HTTP request, e.g.: + +```yaml +name: Release +on: + repository_dispatch: + types: [semantic-release] +jobs: +# ... +``` + +To trigger a release, call (with a [Personal Access Tokens](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) stored in `GITHUB_TOKEN` environment variable): + +``` +$ curl -v -H "Accept: application/vnd.github.everest-preview+json" -H "Authorization: token ${GITHUB_TOKEN}" https://api.github.com/repos/[org-name-or-username]/[repository]/dispatches -d '{ "event_type": "semantic-release" }' +``` diff --git a/docs/usage/ci-configuration.md b/docs/usage/ci-configuration.md index 486fc02740..ae134af80f 100644 --- a/docs/usage/ci-configuration.md +++ b/docs/usage/ci-configuration.md @@ -6,6 +6,7 @@ The `semantic-release` command must be executed only after all the tests in the Here is a few example of the CI services that can be used to achieve this: - [Travis Build Stages](https://docs.travis-ci.com/user/build-stages) - [CircleCI Workflows](https://circleci.com/docs/2.0/workflows) +- [GitHub Actions](https://github.com/features/actions) - [Codeship Deployment Pipelines](https://documentation.codeship.com/basic/builds-and-configuration/deployment-pipelines) - [GitLab Pipelines](https://docs.gitlab.com/ee/ci/pipelines.html#introduction-to-pipelines-and-jobs) - [Codefresh Pipelines](https://codefresh.io/docs/docs/configure-ci-cd-pipeline/introduction-to-codefresh-pipelines)