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

Исходный код и информация о версиях приведены в ssltrus-official/code-sign-action. В текущей стабильной конфигурации используется тег основной версии @v1.

Можно непосредственно в рабочем процессе GitHub Actions выполнить удалённое подписание собранных артефактов.

Action вызывает службу удалённого подписания кода sslTrus, выполняет подписание и напрямую обновляет указанные файлы; поддерживаются runner на Linux, macOS и Windows.

Подготовка секретов GitHub

Рекомендуется сохранить учётные данные для удалённого подписания кода в 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-secret	Да	-	Секрет доступа sslTrus
cert-code	Да	-	Номер сертификата для подписи кода
files	Да	-	Путь к файлу, который требуется подписать
nicsrs	Нет	false	Использовать ли службу NICSRS
dry-run	Нет	false	Выполнить тестовую подпись с помощью локального тестового сертификата
timestamp-rfc3161	Нет	auto	Сервер отметок времени RFC 3161; передайте пустое значение, чтобы отключить отметку времени
description	Нет	-	Записать описание программы в подпись Authenticode
description-url	Нет	-	Записать URL программы в подпись Authenticode

Полный пример Workflow

Ниже приведён пример компиляции, подписания и загрузки артефактов сборки в Runner на Windows:

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 через пользовательскую функцию подписи, чтобы автоматически подписывать исполняемые файлы Windows и установочные пакеты в процессе сборки Electron-приложения.

Типичный процесс:

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

Предварительные условия

Перед началом необходимо:

• Уже иметь доступную услугу удалённого подписания кода sslTrus.
• Получить Access Key и Access Secret.
• Получить номер сертификата подписания кода.
• Проект Electron собирается с помощью electron-builder.
• Сборочное окружение может выполнять CLI sslTrus SignTool, который можно загрузить со страницы выпусков клиента 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 должен управляться как секрет и не должен:

• Передаваться в 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.