GitHub Secrets Setup Guide

November 15, 2025 · View on GitHub

This guide provides step-by-step instructions for setting up GitHub secrets required for automated releases.

Prerequisites

An Apple Developer account
A Developer ID Application certificate
Access to your GitHub repository settings

Step 1: Export Your Developer Certificate

Export from Keychain Access

Open Keychain Access (Applications → Utilities → Keychain Access)
In the left sidebar, select login keychain
Select My Certificates category
Find your Developer ID Application: Your Name (TEAM_ID) certificate
Right-click the certificate → Export "Developer ID Application: Your Name"
Save as certificate.p12
Set a strong password when prompted (you'll need this for the P12_PASSWORD secret)
Save the file to a secure location

Convert to Base64

Open Terminal and run:

base64 -i ~/Downloads/certificate.p12 | pbcopy

This copies the base64-encoded certificate to your clipboard. You'll paste this into the BUILD_CERTIFICATE_BASE64 secret.

Step 2: Get Your Apple Team ID

From Developer Portal

Go to Apple Developer Account
Sign in with your Apple ID
Look for your Team ID in the membership details
- Usually a 10-character alphanumeric string (e.g., ABCD123456)
Copy this value for the APPLE_TEAM_ID secret

From Keychain (Alternative)

In Keychain Access, select your Developer ID Application certificate
Press Cmd+I to open certificate info
Look for Organizational Unit - this is your Team ID

Step 3: Create App-Specific Password

Go to Apple ID Account Page
Sign in with your Apple ID
Navigate to Security section
Under App-Specific Passwords, click Generate Password
Enter a label like "GitHub Actions MultitrackRecorder"
Click Create
Copy the generated password (format: xxxx-xxxx-xxxx-xxxx)
- ⚠️ You won't be able to see this password again!
Save this for the APPLE_APP_SPECIFIC_PASSWORD secret

Step 4: Configure GitHub Secrets

Access Repository Secrets

Go to your GitHub repository
Click Settings tab
In the left sidebar, click Secrets and variables → Actions
Click New repository secret for each secret below

Add These Secrets

Secret Name	Value	Notes
`BUILD_CERTIFICATE_BASE64`	The base64 string from Step 1	Paste from clipboard
`P12_PASSWORD`	Password you set when exporting	The password from Step 1
`KEYCHAIN_PASSWORD`	Any random secure password	Generate a random string (e.g., `openssl rand -base64 32`)
`CODE_SIGN_IDENTITY`	Full certificate name	e.g., `Developer ID Application: John Doe (ABCD123456)`
`APPLE_ID`	Your Apple ID email	The email for your Apple Developer account
`APPLE_TEAM_ID`	Your Team ID	From Step 2 (e.g., `ABCD123456`)
`APPLE_APP_SPECIFIC_PASSWORD`	App-specific password	From Step 3 (format: `xxxx-xxxx-xxxx-xxxx`)

Finding Your Code Sign Identity

If you're not sure of the exact certificate name, run this in Terminal:

security find-identity -v -p codesigning

Look for an entry like:

1) ABCD1234... "Developer ID Application: John Doe (ABCD123456)"

Copy the full name in quotes (including the Team ID in parentheses) for the CODE_SIGN_IDENTITY secret.

Step 5: Verify Setup

Test Locally First

Before pushing a tag, test the build script locally:

export CODE_SIGN_IDENTITY="Developer ID Application: Your Name (TEAM_ID)"
export APPLE_ID="your@email.com"
export APPLE_TEAM_ID="YOUR_TEAM_ID"
export APPLE_APP_SPECIFIC_PASSWORD="xxxx-xxxx-xxxx-xxxx"

./scripts/build_release.sh

If this succeeds, your GitHub Actions should work too.

Test GitHub Actions

After setting up secrets, you can test the workflow:

Go to Actions tab in your repository
Select Build and Release workflow
Click Run workflow
Select branch and click Run workflow
Watch the workflow run and check for errors

Security Best Practices

Certificate Security

✅ DO use repository secrets (not environment variables)
✅ DO limit access to your certificate files
✅ DO delete local certificate.p12 after uploading to GitHub
✅ DO use strong, unique passwords for P12 export
❌ DON'T commit certificate files to git
❌ DON'T share your app-specific password
❌ DON'T use the same password for multiple purposes

Revoking Access

If you need to revoke access:

App-Specific Password: Delete it from appleid.apple.com
Certificate: Revoke it from developer.apple.com
GitHub Secrets: Delete and recreate secrets in repository settings

Troubleshooting

"Unable to find identity" Error

Problem: GitHub Actions can't find your signing identity.

Solution:

Verify CODE_SIGN_IDENTITY matches your certificate name exactly
Check that BUILD_CERTIFICATE_BASE64 is complete (no truncation)
Ensure P12_PASSWORD is correct

"Invalid password" Error

Problem: The P12 password is incorrect.

Solution:

Re-export your certificate with a new password
Update both BUILD_CERTIFICATE_BASE64 and P12_PASSWORD secrets

Notarization Fails

Problem: Apple rejects notarization.

Solution:

Verify APPLE_ID is correct
Check that APPLE_APP_SPECIFIC_PASSWORD hasn't expired
Ensure APPLE_TEAM_ID matches your Developer account
Run locally to see detailed error messages

"Certificate has expired"

Problem: Your Developer ID certificate has expired.

Solution:

Renew certificate at developer.apple.com
Download new certificate
Re-export as P12
Update BUILD_CERTIFICATE_BASE64 and P12_PASSWORD secrets

Certificate Renewal

Developer ID certificates are valid for 5 years. When renewal is needed:

Go to Apple Developer Certificates
Renew or create new Developer ID Application certificate
Download and install in Keychain
Follow Steps 1-4 above to update GitHub secrets
Test with a new build

Additional Resources

Quick Reference Commands

# Find your code signing identity
security find-identity -v -p codesigning

# Check certificate expiration
security find-certificate -c "Developer ID Application" -p | openssl x509 -text | grep "Not After"

# Convert P12 to base64
base64 -i certificate.p12 | pbcopy

# Generate random password for KEYCHAIN_PASSWORD
openssl rand -base64 32

# Test local build
./scripts/build_release.sh

# Verify notarization
spctl -a -vvv -t install /path/to/app.app