Solving macOS Runner PKCS#12 Import Failures in GitHub Actions: Boosting Your Software Project KPI

Unraveling PKCS#12 Import Failures on GitHub Actions macOS Runners

CI/CD pipeline failures, especially those involving critical signing assets, can be a significant roadblock to developer productivity and have a direct impact on crucial software project kpi like delivery velocity and build success rates. A recent GitHub Community discussion highlighted a persistent issue where GitHub Actions macOS runners failed to import valid Apple PKCS#12 (.p12) certificates, reporting a cryptic `MAC verification failed during PKCS12 import (wrong password?)` error.

The user, GONEXA-AO, reported that their Apple Distribution `.p12` certificate worked flawlessly when tested locally on Windows using Java's `keytool`, successfully opening with the correct password and containing a valid private key and certificate chain. Despite re-entering GitHub Actions secrets for the certificate and password (`GIOS_IOS_CERTIFICATE_BASE64`, `GIOS_IOS_CERTIFICATE_PASSWORD`), the macOS runner consistently failed at the 'Prepare Apple signing assets' step. This scenario is frustrating because the error message suggests a wrong password, which often isn't the case.

Beyond the 'Wrong Password' – Common Causes and Solutions

As clarified by community expert mohittguptaa, the `MAC verification failed` error on macOS runners, especially when the `.p12` works elsewhere, typically points to one of two underlying issues:

1. Modern PKCS#12 Encryption Incompatibility with macOS `security`

Modern tools like Java's `keytool` (version 9+) and OpenSSL 3 export PKCS#12 files using stronger, more modern encryption defaults (e.g., AES-256 for content encryption and PBKDF2 / SHA-256 for MAC). However, the macOS `security import` utility, which GitHub Actions runners use, often struggles with these newer formats and reliably handles only the legacy format (3DES for encryption and SHA-1 for MAC). It reports this incompatibility as a MAC/password failure.

Solution: Re-export the certificate in legacy format.

• Using OpenSSL 3 (on any machine):

  openssl pkcs12 -in original.p12 -nodes -out tmp.pem # asks for current password
  openssl pkcs12 -export -legacy -in tmp.pem -out legacy.p12 # set the password again
  rm tmp.pem # contains the private key: delete it
  base64 -i legacy.p12 | tr -d '
  ' > legacy.p12.b64 # paste this into the secret

• Using Keychain Access (on a Mac): Right-click the certificate, choose 'Export', and save it as a `.p12` file. This method typically produces a compatible file.

2. Base64 Secret Corruption

A subtle issue like a stray newline, space, or other character introduced during the base64 encoding or when pasting the secret into GitHub can corrupt the certificate file when decoded. This leads to an invalid `.p12` that fails with the same 'MAC verification failed' error.

Solution: Verify the decoded certificate bytes.

Add a temporary diagnostic step to your GitHub Actions workflow. This step is safe as it only prints a hash and the certificate's info without exposing sensitive data:

- name: Check certificate bytes
  run: |
    echo "$CERT_B64" | base64 --decode > cert.p12
    shasum -a 256 cert.p12
    openssl pkcs12 -in cert.p12 -info -noout -passin env:CERT_PW 2>&1 | head -5
  env:
    CERT_B64: ${{ secrets.GIOS_IOS_CERTIFICATE_BASE64 }}
    CERT_PW: ${{ secrets.GIOS_IOS_CERTIFICATE_PASSWORD }}

Compare the SHA-256 hash printed in the workflow logs with the hash of your original `.p12` file (e.g., `certutil -hashfile original.p12 SHA256` on Windows). If they differ, recreate your base64 secret, ensuring it's a single, continuous line without extra characters. If the hashes match and the `openssl` output shows `PBES2`/`AES-256`, you're likely facing cause #1.

Additional Tip: Quoting Passwords

Always ensure that passwords passed to `security import` are properly quoted (e.g., `security import cert.p12 -k "$KEYCHAIN" -P "$CERT_PW" -T /usr/bin/codesign`). Unquoted passwords containing special characters like `$`, `!`, or spaces can be mangled by the shell, leading to incorrect password submission.

By understanding and addressing these common pitfalls, development teams can significantly improve the reliability of their GitHub Actions macOS CI/CD pipelines, directly boosting a crucial software project kpi: successful and efficient build processes. This ensures smoother releases and empowers developers to focus on delivering value rather than troubleshooting certificate imports.