Skip to main content
macOS and Windows code signing is supported by electron-builder. If the configuration values are provided correctly, signing will be executed automatically during the build process.
Code signing is required for macOS applications to work with auto-update.

​
Environment Variables

Code signing is configured using environment variables:
Environment VariableDescription
CSC_LINKThe HTTPS link, base64-encoded data, file:// link, or local path to certificate (*.p12 or *.pfx file). Supports ~/ shorthand for home directory.
CSC_KEY_PASSWORDThe password to decrypt the certificate given in CSC_LINK.
CSC_NAMEmacOS only - Name of certificate to retrieve from login.keychain. Useful on development machines with multiple identities (not needed on CI).
CSC_IDENTITY_AUTO_DISCOVERYtrue or false. Defaults to true — on macOS development machines, a valid and appropriate identity from your keychain will be automatically used.
CSC_KEYCHAINThe keychain name. Used if CSC_LINK is not specified. Defaults to system default keychain.

​
Additional Environment Variables

# For wrapping app to installer (pkg)
CSC_INSTALLER_LINK=<path-to-installer-certificate>
CSC_INSTALLER_KEY_PASSWORD=<installer-certificate-password>
If you are wrapping your app into a macOS installer (pkg), you need to have an INSTALLER ID identity in your keychain or provide CSC_INSTALLER_LINK and CSC_INSTALLER_KEY_PASSWORD.
If you are building Windows apps on macOS and need different certificates, use WIN_CSC_LINK and WIN_CSC_KEY_PASSWORD instead of the generic CSC_* variables.

​
CI Server Configuration

To sign your app on CI servers (Travis, AppVeyor, GitHub Actions, etc.), you need to set CSC_LINK and CSC_KEY_PASSWORD:
1

Export your certificate

Export your certificate to a .p12 file.
Avoid using special bash characters in the password, as values are not escaped when builds are executed. If you must use special characters, escape them properly:
printf "%q\n" "<password>"
2

Encode the certificate

Encode the certificate file to base64:
base64 -i yourFile.p12 -o envValue.txt
Alternatively, upload the *.p12 file to a cloud storage service (e.g., Google Drive) and use a direct link generator to get a download link.
3

Set environment variables

Set CSC_LINK and CSC_KEY_PASSWORD in your CI project settings:
Recommended: Set variables in CI project settings, not in config files (.travis.yml, appveyor.yml, etc.) to keep credentials secure.In AppVeyor, click the lock icon to “Toggle variable encryption”.

​
Windows Certificate Length Limitation

Windows cannot handle environment variable values longer than 8192 characters. If the base64 representation of your certificate exceeds this limit:
  1. Re-export the certificate without including all certificates in the certification path
  2. The Certificate Manager export wizard ticks this option by default, but the intermediate certificates are not necessary
  3. This will prevent the encoded value from being truncated

​
CI Configuration Examples

​
GitHub Actions

.github/workflows/build.yml
name: Build and Sign

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [macos-latest, windows-latest]
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build and sign
        env:
          CSC_LINK: ${{ secrets.CSC_LINK }}
          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
        run: npm run build

​
Travis CI

.travis.yml
language: node_js
node_js:
  - 18

os:
  - osx
  - windows

script:
  - npm run build

env:
  global:
    - secure: "encrypted-csc-link"
    - secure: "encrypted-csc-password"

​
AppVeyor

appveyor.yml
environment:
  CSC_LINK:
    secure: <encrypted-value>
  CSC_KEY_PASSWORD:
    secure: <encrypted-value>

install:
  - npm ci

build_script:
  - npm run build

​
Where to Buy Code Signing Certificates

​
Windows

For Windows code signing, you need an Authenticode certificate:

​
macOS

For macOS code signing, you need an Apple digital certificate:
Important: Gatekeeper only recognizes Apple-issued certificates. You must obtain your certificate from Apple through the Apple Developer Program.
  1. Join the Apple Developer Program ($99/year)
  2. Create a Developer ID Application certificate in your Apple Developer account
  3. Download and install the certificate in your Keychain Access

​
Certificate Types

macOS:
  • Developer ID Application: For distributing outside the Mac App Store
  • Mac App Distribution: For distributing through the Mac App Store
  • Developer ID Installer: For creating signed installers (pkg files)
Windows:
  • Code Signing Certificate: For signing executables and installers
  • EV Code Signing Certificate: Extended Validation certificate (no SmartScreen warnings)

​
Alternative Code Signing Methods

Code signing via electron-builder configuration is not the only approach. Some developers prefer GUI tools:

​
Third-Party Tools

Comprehensive discussion of third-party signing tools is beyond the scope of this documentation. Refer to the tool’s documentation for usage instructions.

​
macOS Notarization

Starting with macOS 10.15 (Catalina), apps must be notarized by Apple to run without warnings:
package.json
{
  "build": {
    "mac": {
      "hardenedRuntime": true,
      "gatekeeperAssess": false,
      "entitlements": "build/entitlements.mac.plist",
      "entitlementsInherit": "build/entitlements.mac.plist"
    },
    "afterSign": "scripts/notarize.js"
  }
}
Environment Variables for Notarization:
  • APPLE_ID: Your Apple ID email
  • APPLE_APP_SPECIFIC_PASSWORD: App-specific password from Apple ID
  • APPLE_TEAM_ID: Your Apple Team ID

​
Troubleshooting

​
Verify Certificate Installation (macOS)

security find-identity -v -p codesigning
This command lists all code signing identities in your keychain.

​
Verify Signature (macOS)

codesign -dv --verbose=4 /path/to/YourApp.app

​
Verify Signature (Windows)

Get-AuthenticodeSignature -FilePath "path\to\YourApp.exe"

​
Common Issues

macOS:
  • “No identity found”: Certificate not installed in keychain or CSC_NAME doesn’t match
  • “User interaction is not allowed”: Keychain is locked on CI; use CSC_LINK with base64-encoded certificate
  • “Notarization failed”: Check that APPLE_ID credentials are correct and app meets notarization requirements
Windows:
  • “Certificate not found”: CSC_LINK path is incorrect or certificate is malformed
  • “Invalid password”: CSC_KEY_PASSWORD is incorrect
  • “Unsupported algorithm”: Certificate uses an unsupported signature algorithm; obtain a new certificate

​
Security Best Practices

  • Never commit certificates or passwords to version control
  • Use CI environment variables with encryption enabled
  • Rotate certificates before expiration
  • Use separate certificates for development and production
  • Limit access to certificate files and environment variables
  • For macOS, consider using app-specific passwords instead of your main Apple ID password

Build docs developers (and LLMs) love

Get started for freeTalk to us