CI/CD 與構建工具

sslTrus 遠端程式碼簽章服務可以整合到 CI/CD、應用程式建置與安裝包製作流程中，在編譯或打包完成後自動對發布產物執行程式碼簽章。

當前支援的典型整合情境包括：

GitHub Actions
Electron Builder
Advanced Installer

根據建置工具的能力，可以直接使用 sslTrus GitHub Action、呼叫 SignTool CLI，或透過建置工具提供的自訂簽章介面完成整合。

GitHub Actions

sslTrus 提供官方 GitHub Action：

ssltrus-official/code-sign-action

可以直接在 GitHub Actions Workflow 中對建置產物執行遠端程式碼簽署。

Action 會呼叫 sslTrus 遠端程式碼簽署服務完成簽署，並直接更新指定檔案，適用於 Linux、macOS 和 Windows Runner。

準備 GitHub Secrets

建議將遠端程式碼簽署憑證儲存到 GitHub Actions Secrets：

SSLTRUS_ACCESS_KEY
SSLTRUS_ACCESS_SECRET
SSLTRUS_CERT_CODE

不要將 Access Secret 直接寫入 Workflow 檔案。

基礎配置

- name: Sign files
  uses: ssltrus-official/code-sign-action@v1
  with:
    access-key: ${{ secrets.SSLTRUS_ACCESS_KEY }}
    access-secret: ${{ secrets.SSLTRUS_ACCESS_SECRET }}
    cert-code: ${{ secrets.SSLTRUS_CERT_CODE }}
    files: build/app.exe

簽署成功後，build/app.exe 會被簽署後的檔案直接取代。

簽署多個檔案

files 支援使用多行設定多個檔案：

- name: Sign files
  uses: ssltrus-official/code-sign-action@v1
  with:
    access-key: ${{ secrets.SSLTRUS_ACCESS_KEY }}
    access-secret: ${{ secrets.SSLTRUS_ACCESS_SECRET }}
    cert-code: ${{ secrets.SSLTRUS_CERT_CODE }}
    files: |
      build/app.exe
      build/library.dll
      build/installer.msi

也可以使用逗號分隔檔案路徑。

重複的檔案路徑只會處理一次。

完整設定

- name: Sign files
  uses: ssltrus-official/code-sign-action@v1
  with:
    access-key: ${{ secrets.SSLTRUS_ACCESS_KEY }}
    access-secret: ${{ secrets.SSLTRUS_ACCESS_SECRET }}
    cert-code: ${{ secrets.SSLTRUS_CERT_CODE }}
    files: |
      build/app.exe
      build/library.dll
      build/installer.msi
    dry-run: false
    timestamp-rfc3161: http://timestamp.acs.microsoft.com
    description: Example Application
    description-url: https://example.com

主要參數：

參數	必填	預設值	說明
`access-key`	是	-	sslTrus Access Key
`access-secret`	是	-	sslTrus Access Secret
`cert-code`	是	-	程式碼簽署憑證編號
`files`	是	-	需要簽署的檔案路徑
`nicsrs`	否	`false`	是否使用 NICSRS 服務
`dry-run`	否	`false`	使用本機測試憑證執行測試簽署
`timestamp-rfc3161`	否	`auto`	RFC 3161 時間戳伺服器
`description`	否	-	寫入 Authenticode 簽章的程式描述
`description-url`	否	-	寫入 Authenticode 簽章的程式 URL

完整 Workflow 範例

下面是在 Windows Runner 中編譯、簽章並上傳建置產物的範例：

name: Build and Sign

on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  build:
    runs-on: windows-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v7

      - name: Build
        run: |
          # 在这里执行实际构建命令

      - name: Sign files
        uses: ssltrus-official/code-sign-action@v1
        with:
          access-key: ${{ secrets.SSLTRUS_ACCESS_KEY }}
          access-secret: ${{ secrets.SSLTRUS_ACCESS_SECRET }}
          cert-code: ${{ secrets.SSLTRUS_CERT_CODE }}
          files: |
            build/app.exe
            build/library.dll
          timestamp-rfc3161: http://timestamp.acs.microsoft.com

      - name: Upload signed files
        uses: actions/upload-artifact@v7
        with:
          name: signed-files
          path: |
            build/app.exe
            build/library.dll

建議將簽署步驟放在：

編譯 → 打包 → 程式碼簽署 → 發佈

流程中的發佈步驟之前。

多平台 Runner

GitHub Action 可以在不同 Runner 中調用：

strategy:
  matrix:
    os:
      - ubuntu-latest
      - macos-latest
      - windows-latest

runs-on: ${{ matrix.os }}

因此，即使建置工作執行於 Linux 或 macOS，也可以使用相同 Action 完成受支援檔案的遠端簽署。

Dry Run

如果需要驗證 Workflow 和檔案處理邏輯，可以啟用：

dry-run: true

此模式使用本機測試憑證，不呼叫遠端程式碼簽署服務。

例如：

- name: Test signing
  uses: ssltrus-official/code-sign-action@v1
  with:
    access-key: dummy
    access-secret: dummy
    cert-code: dummy
    files: build/app.exe
    dry-run: true

dry-run 仍會修改目標檔案，因此不要將其理解為完全不修改檔案的預覽模式。

Electron Builder

Electron Builder 可以透過自訂簽章函式呼叫 sslTrus SignTool CLI，從而在 Electron 應用程式建置過程中自動完成 Windows 可執行檔與安裝套件簽章。

典型流程：

Electron Builder
      ↓
customSign
      ↓
SignTool CLI
      ↓
sslTrus 远程代码签名服务
      ↓
云端 HSM

前提條件

開始前需要：

已有可用的 sslTrus 遠端程式碼簽章服務。
已取得 Access Key 和 Access Secret。
已取得程式碼簽章憑證編號。
Electron 專案使用 electron-builder 建置。
建置環境能夠執行 sslTrus SignTool CLI，可從 sslTrus 用戶端發佈頁下載。

設定憑證

可以透過環境變數將憑證傳遞給建置指令碼：

Linux 和 macOS：

export SIGNTOOL_ACCESS_KEY="YOUR_ACCESS_KEY"
export SIGNTOOL_ACCESS_SECRET="YOUR_ACCESS_SECRET"
export SIGNTOOL_CERT_CODE="YOUR_CERT_CODE"

Windows PowerShell：

$env:SIGNTOOL_ACCESS_KEY = "YOUR_ACCESS_KEY"
$env:SIGNTOOL_ACCESS_SECRET = "YOUR_ACCESS_SECRET"
$env:SIGNTOOL_CERT_CODE = "YOUR_CERT_CODE"

這些變數由 Electron 自訂簽署腳本讀取，再傳遞給 SignTool CLI。

設定 Electron Builder

在：

electron-builder.mjs

或者專案實際使用的 Electron Builder 設定檔中，為 Windows 設定自訂簽章函式：

export default {
  win: {
    target: [
      {
        target: 'nsis',
        arch: ['x64'],
      },
    ],
    sign: customSign,
    signingHashAlgorithms: ['sha256'],
  },
};

其中 win.sign 是 Electron Builder 官方提供的自訂簽章入口，詳細說明請參閱 Electron Builder Windows 程式碼簽章文件。

customSign

負責呼叫 sslTrus SignTool CLI。

自訂簽章函式

範例：

import { execFileSync } from 'node:child_process';

async function customSign(configuration) {
  const {
    SIGNTOOL_ACCESS_KEY,
    SIGNTOOL_ACCESS_SECRET,
    SIGNTOOL_CERT_CODE,
  } = process.env;

  if (
    !SIGNTOOL_ACCESS_KEY ||
    !SIGNTOOL_ACCESS_SECRET ||
    !SIGNTOOL_CERT_CODE
  ) {
    throw new Error('Missing sslTrus signing credentials');
  }

  execFileSync(
    './signtool',
    [
      'sign',
      '--access-key',
      SIGNTOOL_ACCESS_KEY,
      '--access-secret',
      SIGNTOOL_ACCESS_SECRET,
      '--cert-code',
      SIGNTOOL_CERT_CODE,
      '--file',
      configuration.path,
      '--override=true',
      '--sha1=false',
      '--sha2=true',
      '--timestamp-rfc3161=http://timestamp.acs.microsoft.com',
    ],
    {
      stdio: 'inherit',
    },
  );
}

建議使用參數陣列呼叫子處理程序，而不是拼接完整 Shell 指令，以減少路徑跳脫和特殊字元處理問題。

Electron Builder 會依照 signingHashAlgorithms 中的每個雜湊演算法分別呼叫一次簽章函式。上面的範例只啟用 SHA-256，因此每個檔案呼叫一次。

執行建置

設定完成後，正常執行 Electron Builder：

npx electron-builder build \
  --config electron-builder.mjs \
  --win \
  --x64

Electron Builder 在需要對檔案執行簽署時，會自動呼叫 customSign。

一次 Electron 建置可能簽署多個檔案，例如：

MyApp.exe
helper.dll
update.exe
uninstall.exe
MyApp Setup.exe

因此，不應簡單理解為「一次 Electron 打包只產生一次簽章」。

實際簽章次數取決於建置過程中有多少檔案執行了遠端簽章。

Advanced Installer

Advanced Installer 是基於 Windows Installer 技術的安裝包製作工具。

可以透過 Advanced Installer 的自訂簽章工具功能呼叫 sslTrus SignTool CLI，使 MSI、EXE、CAB 等建置產物在打包過程中自動完成遠端程式碼簽章。

前提條件

需要準備：

sslTrus SignTool CLI，可從 sslTrus 用戶端發佈頁下載。
Access Key。
Access Secret。
憑證編號。
已設定完成的 Advanced Installer 專案。

設定自訂簽章工具

開啟 Advanced Installer 專案的：

Digital Signature

配置頁面。

啟用程式碼簽署後，將簽署工具選擇為：

Custom

簽名工具路徑設定為 sslTrus SignTool CLI 可執行檔。

例如：

C:\Tools\sslTrus\signtool.exe

自訂參數需要呼叫：

sign

子命令，並向用戶端傳入：

Access Key
Access Secret
Cert Code
SHA-2 簽章設定
時間戳伺服器
檔案路徑

建議優先透過安全方式提供 Access Key 和 Access Secret，避免將長期有效的 Access Secret 明文儲存到可公開取得的專案檔案中。

SignTool 參數範例

對應的簽章邏輯類似：

signtool.exe sign ^
  --access-key="YOUR_ACCESS_KEY" ^
  --access-secret="YOUR_ACCESS_SECRET" ^
  --cert-code="YOUR_CERT_CODE" ^
  --nest=true ^
  --sha1=false ^
  --sha2=true ^
  --timestamp-rfc3161=http://timestamp.acs.microsoft.com ^
  --desc="Example Application" ^
  --override=true ^
  --file "app.exe"

在 Advanced Installer 中，實際檔案路徑應由其自訂簽章工具機制傳入，不要固定為範例中的 app.exe。

建置設定

如果使用 Advanced Installer 自動簽署安裝套件內部檔案，需要同時檢查建置與壓縮方式。

根據專案實際設定，某些 CAB 封存方式可能會影響自訂簽章流程，應確認最終需要簽署的檔案能夠在對應階段被呼叫。

設定完成後，可以在 Advanced Installer 的數位簽章頁面檢查：

Files configured for signing

從而確認哪些檔案將在建置過程中執行簽署。

簽署次數

Advanced Installer 可能在一次安裝包建置過程中對多個檔案分別執行簽署。

例如：

檔案	簽署
`app.exe`	1 次
`helper.dll`	1 次
`uninstall.exe`	1 次
`installer.msi`	1 次
合計	4 次

因此：

一次构建 ≠ 一次签名

應根據實際完成遠端簽署的檔案或簽署動作數量計算。

簽署次數

CI/CD 與建置工具通常會自動處理多個產物，因此簽署次數需要特別留意。

基本原則：

签名次数 = 实际成功完成的签名动作数量

例如：

app.exe        → 1 次
library.dll    → 1 次
installer.msi  → 1 次

如果三個檔案都成功簽署：

合计 = 3 次

Electron Builder 和 Advanced Installer 等建置工具還可能自動產生並簽署：

主程式。
DLL。
更新程式。
解除安裝程式。
MSI。
EXE 安裝套件。
其他輔助可執行檔。

因此，應根據建置記錄和實際簽署產物確認簽署次數，而不是按照 Pipeline 或 Build 的執行次數估算。

更多規則請參閱參考資料。

時間戳記

正式發佈的軟體通常建議新增可信時間戳記。

GitHub Actions、Electron Builder 和 Advanced Installer 整合均可以使用 RFC 3161 時間戳記，例如：

http://timestamp.acs.microsoft.com

時間戳不屬於新的程式碼簽署操作，不單獨增加程式碼簽署次數。

不同 TSA 的通訊協定支援與使用限制請參閱參考資料。

憑證安全

自動化環境中應特別保護：

Access Key
Access Secret
Cert Code

其中 Access Secret 應作為 Secret 管理，不應：

提交到 Git 倉庫。
明文寫入公開 Workflow。
輸出到建置日誌。
寫入公開 Docker 映像。
透過不安全的方式傳遞給第三方建置系統。

GitHub Actions 建議使用：

GitHub Actions Secrets

其他 CI/CD 系統則應使用其對應的 Secret、Credential 或 Variable 管理機制。

如何選擇

場景	推薦方式
GitHub Actions Workflow	GitHub Actions
Electron 應用構建	Electron Builder
MSI / EXE 安裝包製作	Advanced Installer
一般 Shell / PowerShell 自動化	SignTool CLI
Windows 軟體原生支援 KSP	Windows Provider
自行開發簽署流程	API 整合

如果構建系統能夠直接呼叫命令列程式，可以使用 SignTool CLI；如果工具已經提供標準的 Windows KSP/CSP 介面，則優先使用對應的 Windows Provider 整合方式。

GitHub Actions​

準備 GitHub Secrets​

基礎配置​

簽署多個檔案​

完整設定​

完整 Workflow 範例​

多平台 Runner​

Dry Run​

Electron Builder​

前提條件​

設定憑證​

設定 Electron Builder​

自訂簽章函式​

執行建置​

Advanced Installer​

前提條件​

設定自訂簽章工具​

SignTool 參數範例​

建置設定​

簽署次數​

簽署次數​

時間戳記​

憑證安全​

如何選擇​

GitHub Actions

準備 GitHub Secrets

基礎配置

簽署多個檔案

完整設定

完整 Workflow 範例

多平台 Runner

Dry Run

Electron Builder

前提條件

設定憑證

設定 Electron Builder

自訂簽章函式

執行建置

Advanced Installer

前提條件

設定自訂簽章工具

SignTool 參數範例

建置設定

簽署次數

簽署次數

時間戳記

憑證安全

如何選擇