Contents
Distribute

GitHub CI/CD

Automate cross-platform builds, signing, and releases with GitHub Actions.

Overview 

Every new MōBrowser project includes a release workflow that automatically:

  1. Detects when you push a version tag (e.g., v1.0.0)
  2. Builds your application for macOS, Windows, and Linux
  3. Signs the binaries and installers with your configured credentials
  4. Creates a GitHub Release with the signed artifacts

Projects scaffolded with npm create mobrowser-app get .github/workflows/release.yml by default. The workflow runs only when you push a version tag, so it stays out of the way until you need it.

Adding the workflow to an existing project 

To add a github workflow to an existing project, run:

npm run add github-actions

Note: Projects created with an earlier version of create-mobrowser-app may not have the add script in package.json. In such projects, run npm run mobrowser add github-actions instead.

The command:

  • Creates .github/workflows/release.yml.
  • Points the macOS signing fields of mobrowser.conf.json (codesignIdentity, teamID, appleID, and password) at the credentials the workflow reads from repository secrets.

Fields you have already filled in are left untouched, so it is safe to run the command again.

Once the workflow is in place, set up your credentials and create a release.

Creating a release 

To trigger a release, push a version tag to your repository:

  1. Update the version in mobrowser.conf.json:
{
  "version": "1.0.0"
}
  1. Commit your changes:
git add .
git commit -m "Release v1.0.0"
  1. Create and push a tag:
git tag v1.0.0
git push origin main
git push origin v1.0.0

The workflow is triggered automatically when it detects a tag matching the pattern v* (e.g., v1.0.0).

Setting up credentials 

To enable signing in your workflow, you need to configure credentials for each platform.

Important: Without setting these signing credentials, the generated installers and binaries inside these installers will not be signed. This means users will see security warnings when running your application, and it may not be permitted to run on their systems.

Creating an environment 

Create a production environment to manage and control access to all signing credentials:

  1. Go to your repository on GitHub
  2. Navigate to Settings → Environments
  3. Click New environment and name it production

After creating the environment, you can add platform-specific environment secrets to it in the steps below.

macOS signing credentials 

Add the following secrets to the production environment for signing on macOS:

Secret NameDescription
MAC_CERTIFICATEBase64-encoded Developer ID Application certificate (.p12)
MAC_CERTIFICATE_PWDPassword used to export the .p12 certificate from Keychain Access
MAC_KEYCHAIN_PWDPassword for the temporary CI keychain created during the build
MAC_CODESIGN_IDENTITYSigning identity string, e.g. Developer ID Application: Company Name (TEAMID)
MAC_TEAM_IDApple Developer Team ID (10-character string from developer.apple.com)
MAC_APPLE_IDYour Apple Developer account email
MAC_APPLE_PASSWORDApp-specific password generated at appleid.apple.com for notarization

Windows signing credentials 

For cloud-based signing on Windows using Azure Artifact Signing, add the following secrets to the production environment:

Secret NameDescription
AZURE_CLIENT_IDService Principal client ID
AZURE_TENANT_IDAzure Active Directory tenant ID of the service principal
AZURE_SUBSCRIPTION_IDAzure subscription ID
AZURE_SIGNING_ENDPOINTAzure signing endpoint (e.g., https://eus.codesigning.azure.net/)
AZURE_SIGNING_ACCOUNT_NAMEName of your Artifact Signing account
AZURE_SIGNING_PROFILE_NAMEName of your certificate profile

See Azure Artifact Signing Setup for detailed instructions on acquiring these credentials.

The production environment allows you to securely authenticate GitHub Actions with Azure. Instead of storing long-lived secrets in your repository, GitHub uses OpenID Connect to exchange a short-lived token with Azure. An environment-based approach can be triggered by any event (including version tags).

Monitoring the release 

To view the workflow status:

  1. Go to your repository on GitHub
  2. Click the Actions tab
  3. Select the workflow run to view logs and status

If a job fails:

  • Check the job logs for error messages
  • Verify all required secrets are set correctly
  • Ensure signing credentials haven’t expired
  • Check that your code builds successfully locally first
On this page