跳至主要内容

[Deploy] Semantic Release 筆記

keywords: deploy, publish, release, CLI, CI​

Introduction @ semantic-release gitbooks

# 在 local 執行 dry-run
$ NPM_TOKEN=<your_npm_token> GH_TOKEN=<your_github_token> npx semantic-release --no-ci --dry-run

注意事項​

  • sematic-release 的設定檔 .releaserc 副檔名雖然可以是 js，但裡面還是得要使用 JSON 語法（Configuration File）。
  • 在 Travis CI 上執行 semantic-release 時有可能會發生「Can not find modules」的錯誤，解決方式可參考下面「[在 Travis CI 上使用出現 Cannot find module 的問題](#在 Travis CI 上使用出現 Cannot find module 的問題)」。

概念​

目的：透過 semantic-release 可以自動化整個套件發佈的工作流程，包含決定 next version 的版號、產生 release notes 和發佈套件。semantic-release 使用 commit 的內容來決定專案版本變更的類型，並且自動產生語易化版號，產生 changelog 和發佈。

撰寫 commit：預設著情況下 semantic-release 使用 Angular Commit Message Conventions 來決定版號的變更，有需要的話，亦可透過 @semantic-release/commit-analyzer 和 @semantic-release/release-notes-generator 的 preset 或 config 選項來調整。

格式化 commit 的工具：也可以使用像是 commitizen 或 commitlint 這類的工具來幫助開發者強制寫出合法有效的 commit messages。

CI：semantic-release 是用來 CI 環境中，每次成功打包後執行。對於每一個透過 git push 或 merge PR 到 release branch（例如，master, next, beta）的 commit，CI 都會觸發打包和執行 semantic-release 指令以產生新的 release。

步驟：在執行 semantic-release 的指令後，會執行這些步驟。

Getting Started​

要使用 semantic-release 的話，需要依序完成下列步驟（這些流程多可以透過 semantic-release cli 解決）：

  1. 安裝：在專案中安裝 semantic-release
  2. 設定 CI 服務：設定 CI 服務（例如，Travis CI, Github Action）來執行 semantic-release
  3. 設定 CI 權限：在 CI 服務中設定 Github 和套件管理工具的權限
  4. 建立設定檔：設定 semantic-release 的外掛和選項。

Plugin​

Plugins @ semantic-release

預設就有的外掛包含：

"@semantic-release/commit-analyzer"
"@semantic-release/github"
"@semantic-release/npm"
"@semantic-release/release-notes-generator"

自動產生 CHANGE_LOG 檔案​

若有需要自動產生 CHANGE_LOG 檔案：

$ npm install @semantic-release/git @semantic-release/changelog -D

設定檔如下：

// .releaserc.json

{
  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
    [
      '@semantic-release/changelog',
      {
        changelogFile: 'docs/CHANGELOG.md',
      },
    ],
    '@semantic-release/npm,
    [
      '@semantic-release/git',
      {
        // 寫在 assets 裡的內容可以在 CI 後被 commit 到 git repository 內
        // 預設是 ['CHANGELOG.md', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json']
        assets: ['docs/CHANGELOG.md'],
      },
    ],
  ],
};

semantic-release CLI​

semantic-release cli @ github

這個工具會自動產生 Github 和 NPM 上的 Token，如果使用的是 Travis CI 則會並自動設定到 Travis CI 上：

$ cd your-module
$ npx semantic-release-cli setup

搭配 Github Action 使用​

可參考在 eslint-config-pjchender @ github 的設定

備註

最近（2021-07）在使用 semantic-release 是，執行 npx semantic-release-cli setup 的時候，Travis CI 一直驗證不過，於是改用 Github Action。

執行步驟​

  1. 安裝 semantic release
$ npx semantic-release-cli setup
# > 輸入 npm 的帳號密碼
# > 選擇 CI 的方式為 Github Action
  1. 到 npm Settings 中的 Access Tokens 產生一組 Token，並設定在 Github Repo 的 Environment 中，這裡把環境名稱（environment name）取做 release，npm 的 token 的環境變數（environment variable）則取做 NPM_TOKEN：

Create Environment for Github Action

  1. 建立 Github Action 的 Workflow 檔（可以參考官方提供的 設定檔範例）
    • 記得要使用 environment: release 指定要套用的環境名稱
# .github/workflows/release.yml

name: Release

# push 到 main 分支時，會促發此 workflow
on:
  push:
    branches:
      - main
jobs:
  release:
    name: Release
    environment: release # 這裡要記得指定套用的環境，才能取得變數
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - name: Setup Node.js
        uses: actions/setup-node@v1
        with:
          node-version: 14
      - name: Install dependencies
        run: npm ci
      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release
  1. 建立 .releaserc.json，這是給 semantic-release 用的設定檔：
    • "branches": ["main"]：指定 release branch 名稱，需與 Github Action 的 branches 對應
    • message：修改 commit message 的內容，避免內容太長（如果有使用 commitlint 的話才需要加）
{
  "branches": ["main"],    // 指定 release branch 名稱
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    [
      "@semantic-release/git",
      {
        "message": "chore(release): ${nextRelease.version} [skip ci]"
      }
    ]
  ]
}
  1. 推上 Github 對應的 branch 即可。

其他​

authentication 建立給 semantic-release 用的 Github Token​

使用 semantic-release 時需要建立帶有對應權限的 github personal token 和 npm token 給它

在 Travis CI 上使用出現 Cannot find module 的問題​

How to automatically pull changelog and git modules when issuing npx semantic-release? @ Github Issues

在 Travis CI 使用時若出現類似的錯誤訊息時：

Cannot find module '@semantic-release/changelog'
Cannot find module '@semantic-release/git'

可以修改 .travis.yaml 的檔案，將 script 的地方改成：

script: npx -p @semantic-release/changelog -p @semantic-release/git -p semantic-release semantic-release

參考設定檔​

.releaserc​

// .releaserc.json
{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    [
      "@semantic-release/npm",
      {
        "npmPublish": false, // 要不要發佈到 npm
        "tarballDir": "dist"
      }
    ],
    "@semantic-release/git"
  ]
}

Travis​

# .travis.yaml
language: node_js

node_js:
  - 12

jobs:
  include:
    # Define the release stage that runs semantic-release
    - stage: release
      node_js: lts/*
      script: npm run build
      deploy:
        provider: script
        script: npx -p @semantic-release/changelog -p @semantic-release/git -p semantic-release semantic-release
        skip_cleanup: true # 💡加上這句