Skip to content

· 10 min read · Nadeera Silva

Mobile

fastlane match password: Fix "Couldn't decrypt the repo"

Why fastlane match says "Couldn't decrypt the repo" on GitHub Actions when your passphrase is right, and how to fix MATCH_PASSWORD for Flutter iOS builds.

A hand turning a small brass key in a steel lockbox on a sunlit desk, with a blurred laptop and an amber lamp behind, standing for the passphrase that unlocks a fastlane match certificates repo

Your Flutter iOS build works on your Mac, then fails on GitHub Actions with Couldn't decrypt the repo, please make sure you enter the right password! followed by Invalid password passed via 'MATCH_PASSWORD'. This is a fastlane match password problem, and the passphrase you remember is often correct. The value that reaches match on the CI runner is what's wrong. This post shows the three error messages, the five causes behind them, and a pipeline setup that stops them.

Quick answer

The "Couldn't decrypt the repo" error means match tried to decrypt your certificates repo with a passphrase that doesn't match the one used to encrypt it. On CI the usual causes are an empty or unmapped MATCH_PASSWORD secret, a dotenv file that overrides it, a $ in the passphrase that dotenv expands, or a different fastlane version on CI than on the laptop that wrote the repo. Map the secret explicitly in the workflow's env:, remove MATCH_PASSWORD from committed .env files, pin fastlane in Gemfile.lock, and test the passphrase locally with fastlane match appstore --readonly.

What this means for your app or business

Your app's signing certificate and provisioning profiles live in an encrypted Git repo, and the passphrase is the only key to it. When CI can't decrypt that repo, nothing ships: no TestFlight builds for testers, no App Store update, no hotfix. The certificates themselves are fine, so there's no need to revoke anything or pay for a new developer account.

For a developer who knows where to look, this is usually a 30 to 60 minute fix. It turns into a lost day when someone "fixes" it by running match nuke or regenerating certificates, which can break every other app and machine that shares that repo. If your release is blocked and nobody on the team set up the pipeline, that's a good moment to get help rather than experiment.

What do the fastlane match password errors look like?

All three come from match's encryption code (openssl.rb, fastlane 2.242.0):

Message in the logWhat it meansMost likely cause on CI
Couldn't decrypt the repo, please make sure you enter the right password! + Invalid password passed via 'MATCH_PASSWORD'A passphrase was supplied but decryption failedEmpty secret, overridden or mangled value, version mismatch
Neither the MATCH_PASSWORD environment variable nor the local keychain contained a password.No passphrase at all, and CI can't promptThe secret isn't mapped into the job's env:
Couldn't decrypt the repo... then a new Passphrase for Match storage: promptLaptop only: the keychain held a wrong passphrase, match cleared it and asks againThe repo passphrase changed (match change_password)

The second message ends with Try setting the MATCH_PASSWORD environment variable. match only falls back to the macOS keychain and an interactive prompt when the variable is missing, and CI runners are non-interactive, so match stops instead of hanging.

Flowchart: the workflow maps the secret into env, fastlane loads dotenv files, match picks the passphrase, then decrypts every certificate and profile, with the failure next to each step: empty secret, overriding --env file or unquoted dollar sign, unmapped secret, and wrong passphrase or mixed fastlane versions
Each step can hand match a different passphrase from the one you typed when the repo was created.

Why does match say the password is invalid when it's correct?

1. The secret is empty, not missing

GitHub's secrets documentation says an expression that references a secret that isn't set returns an empty string. Secrets are also not passed to workflows triggered from a forked repository or by Dependabot. So a typo like secrets.MATCH_PASSWRD gives match MATCH_PASSWORD="".

In Ruby an empty string counts as "set", so match skips the keychain, tries to decrypt with an empty passphrase and fails with Invalid password passed via 'MATCH_PASSWORD'. I confirmed both halves on the box: decrypting a file encrypted by match's own MatchFileEncryption class with "" raised OpenSSL::Cipher::CipherError.

2. A dotenv file overrides the CI secret

fastlane loads dotenv files from the folder that holds your Fastfile (or its parent). The detail that matters is in the helper's source: .env and .env.default are loaded with Dotenv.load, which never replaces a variable that's already set, but .env.<name> files picked with fastlane beta --env <name> are loaded with Dotenv.overload, which does. A fastlane/.env.ci committed with someone's local MATCH_PASSWORD silently beats the GitHub secret.

3. A dollar sign in the passphrase gets expanded

The dotenv README says $VAR is substituted in unquoted or double-quoted values, and to wrap a value in single quotes if the $ is literal. My test with dotenv 3.2.0:

dotenv unquoted value: "s3cr-2026"           # MATCH_PASSWORD=s3cr$tKey-2026
dotenv single-quoted value: "s3cr$tKey-2026" # MATCH_PASSWORD='s3cr$tKey-2026'

The same applies to shell scripts that use double quotes, such as export MATCH_PASSWORD="$..." in a CI step. A copied secret with a trailing newline fails the same way.

4. CI runs a different fastlane version

fastlane 2.220.0 (April 2024) changed how match encrypts files. In issue #21973 teams reported that files written by 2.220.0 couldn't be read by 2.219.0 on CI, per file, so the error appears only after someone re-encrypts a profile. A maintainer later wrote that the match repo and the pipeline needed matching Ruby and fastlane versions at the time, and that this was resolved in later releases. Pinning one version for everyone still removes the whole class of problem. If an old machine must stay on an old fastlane, match has a force_legacy_encryption option that writes the older format.

5. Someone changed the passphrase

fastlane match change_password re-encrypts every file with a new passphrase. The docs say you'll be asked for it on all your machines on the next run, but CI never asks, so the old secret keeps failing until you update it.

How do I fix the fastlane match password error on GitHub Actions?

Step 1: Test the passphrase locally

On a Mac with access to the certificates repo, run match in readonly mode with the passphrase in the environment. Single quotes stop your shell from expanding anything:

cd ios
MATCH_PASSWORD='your-passphrase' bundle exec fastlane match appstore --readonly

If this prints Successfully decrypted certificates repo, the passphrase is right and the problem is how CI receives it. If it fails here too, find the passphrase in your password manager before touching anything else. match also ships a match_file decrypt helper for testing a single file.

Step 2: Map the secrets explicitly and check them early

Store the passphrase under Settings, Secrets and variables, Actions, as MATCH_PASSWORD. Then map it in the job, and run a cheap check before the slow Flutter build:

name: iOS TestFlight

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  ios:
    runs-on: macos-26
    timeout-minutes: 45
    env:
      # Map every secret explicitly. A secret that doesn't exist becomes "".
      MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}
      MATCH_GIT_BASIC_AUTHORIZATION: ${{ secrets.MATCH_GIT_BASIC_AUTHORIZATION }}
      ASC_KEY_ID: ${{ secrets.ASC_KEY_ID }}
      ASC_ISSUER_ID: ${{ secrets.ASC_ISSUER_ID }}
      ASC_KEY_P8_BASE64: ${{ secrets.ASC_KEY_P8_BASE64 }}
    steps:
      - uses: actions/checkout@v7

      - name: Check match secrets before the slow steps
        run: bash scripts/check-match-secrets.sh

      - uses: subosito/flutter-action@v2
        with:
          channel: stable
          flutter-version: 3.50.0
          cache: true

      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: "3.3"
          bundler-cache: true          # installs the fastlane version pinned in ios/Gemfile.lock
          working-directory: ios

      - run: flutter pub get
      - run: flutter build ios --release --no-codesign

      - name: Sign and upload with fastlane
        working-directory: ios
        run: bundle exec fastlane beta

MATCH_GIT_BASIC_AUTHORIZATION is the base64 of username:personal_access_token, as the match docs describe for Git storage on GitHub (git 2.31 or later). The check script never prints the passphrase, only its length:

#!/usr/bin/env bash
# Fails fast when MATCH_PASSWORD can't be right. Never prints the value.
set -euo pipefail

pw="${MATCH_PASSWORD-}"
status=0

if [ -z "${MATCH_PASSWORD+x}" ]; then
  echo "::error::MATCH_PASSWORD is not set. Map it in the job's env: block."
  status=1
elif [ -z "$pw" ]; then
  echo "::error::MATCH_PASSWORD is empty. The secret is missing, misnamed, or this run came from a fork or Dependabot."
  status=1
fi

case "$pw" in
  *$'\n'* | *$'\r'*) echo "::error::MATCH_PASSWORD contains a line break."; status=1 ;;
esac

case "$pw" in
  " "* | *" ") echo "::warning::MATCH_PASSWORD starts or ends with a space. Is that really part of the passphrase?" ;;
esac

# A --env file is loaded with Dotenv.overload and replaces the CI secret.
if grep -qs '^[[:space:]]*\(export[[:space:]]\+\)\?MATCH_PASSWORD=' ios/fastlane/.env* ios/.env* 2>/dev/null; then
  echo "::warning::A dotenv file in ios/ or ios/fastlane/ sets MATCH_PASSWORD. Remove it from the repo."
fi

if [ -f ios/Gemfile.lock ]; then
  echo "fastlane pinned in Gemfile.lock: $(grep -E '^    fastlane \(' ios/Gemfile.lock | head -n1 | tr -d ' ')"
else
  echo "::warning::ios/Gemfile.lock not found. Pin fastlane so CI and laptops use the same version."
fi

echo "MATCH_PASSWORD length: ${#pw}"
exit "$status"

I ran it against an unset variable, an empty one, one with a line break and a committed .env.ci: the first three exit with code 1 and a clear ::error:: annotation, the last one warns.

Step 3: Use setup_ci and readonly in the Fastfile

`setup_ci` creates a temporary keychain with an empty password, sets it as the default and switches match to readonly. Off CI it skips itself. The match docs also recommend readonly on CI, so the runner never creates certificates:

default_platform(:ios)

platform :ios do
  before_all do
    # On CI: temporary keychain with an empty password + match readonly.
    # Off CI it prints "Not running on CI, skipping CI setup".
    setup_ci
  end

  desc "Install signing files and upload a build to TestFlight"
  lane :beta do
    api_key = app_store_connect_api_key(
      key_id: ENV["ASC_KEY_ID"],
      issuer_id: ENV["ASC_ISSUER_ID"],
      key_content: ENV["ASC_KEY_P8_BASE64"],
      is_key_content_base64: true
    )

    # MATCH_PASSWORD and MATCH_GIT_BASIC_AUTHORIZATION come from the environment.
    match(
      type: "appstore",
      readonly: true,
      api_key: api_key
    )

    build_app(
      workspace: "Runner.xcworkspace",
      scheme: "Runner",
      export_method: "app-store"
    )

    upload_to_testflight(
      api_key: api_key,
      skip_waiting_for_build_processing: true
    )
  end
end

Step 4: Pin fastlane for everyone

Commit ios/Gemfile with gem "fastlane" and the generated ios/Gemfile.lock, then run bundle exec fastlane on laptops and on CI. ruby/setup-ruby with bundler-cache: true installs exactly the locked version. When you upgrade fastlane, upgrade the lock file in one pull request so every machine moves together.

How do I verify the fix?

  • The check step prints MATCH_PASSWORD length: with the length you expect and fastlane pinned in Gemfile.lock: fastlane(2.242.0) or your pinned version.
  • The fastlane log shows Creating temporary keychain, Enabling match readonly mode and Successfully decrypted certificates repo.
  • build_app finishes and the build appears in App Store Connect under TestFlight.

How do I stop it happening again?

  • Keep the passphrase in a team password manager, next to the repo URL. One owner, written down.
  • Never commit MATCH_PASSWORD to any .env file. Add fastlane/.env* to .gitignore if your team uses them for local values.
  • Avoid $, quotes and backslashes in the passphrase if anyone will put it in a dotenv file or shell script.
  • After match change_password, update the CI secret in the same hour.
  • Pin fastlane in Gemfile.lock and upgrade it deliberately.

If signing fails later, at the Xcode step rather than at decryption, my guide to the GitHub Actions "No signing certificate" error covers the keychain side, and teams on Codemagic can compare with the Codemagic "No matching profiles found" fix. For the Android half of the same pipeline, see the Google Play "caller does not have permission" error.

Frequently asked questions

What does Couldn't decrypt the repo mean in fastlane match?

match tried to decrypt the certificates and profiles in your match storage with a passphrase that doesn't match the one used to encrypt them. On CI that usually means the MATCH_PASSWORD value is empty, overridden or altered, not that you forgot the passphrase.

Where does fastlane match get the password from?

match reads the MATCH_PASSWORD environment variable first. If it isn't set, it looks in the macOS keychain, and on an interactive machine it then prompts for the passphrase. CI runners can't prompt, so match stops with an error instead.

Why does an unset GitHub secret cause Invalid password passed via MATCH_PASSWORD?

GitHub returns an empty string for a secret that isn't set, and Ruby treats an empty string as a set value. match then tries to decrypt with an empty passphrase and reports the password as invalid.

Can a .env file override my MATCH_PASSWORD secret?

Yes, if it is loaded with the --env option. fastlane loads .env and .env.default without replacing existing variables, but .env.<name> files chosen with --env replace them, so a committed value wins over the CI secret.

Do different fastlane versions affect match decryption?

They can. fastlane 2.220.0 changed match's encryption format, and teams reported that older versions on CI couldn't read files re-encrypted by 2.220.0. Pin fastlane in Gemfile.lock and run bundle exec fastlane everywhere.

How do I change the fastlane match password?

Run fastlane match change_password, which re-encrypts every file with the new passphrase. Then update the MATCH_PASSWORD secret in every CI system that uses the repo, because CI won't prompt for it.

Should I run match nuke to fix a decrypt error?

No. match nuke revokes certificates and deletes provisioning profiles in your Apple developer account, which breaks other machines and apps. A decrypt error is a passphrase problem, so fix the passphrase instead.

Should fastlane match run in readonly mode on CI?

Yes. The match docs recommend readonly on CI so the runner never creates new certificates or profiles, and setup_ci turns readonly on automatically along with a temporary keychain.

Sources

  1. match (sync_code_signing) documentation (fastlane)
  2. setup_ci documentation (fastlane)
  3. match encryption source: openssl.rb (fastlane on GitHub)
  4. fastlane dotenv helper source (fastlane on GitHub)
  5. fastlane releases (2.242.0) (fastlane on GitHub, 2026-11-16)
  6. Environment variables and dotenv in fastlane (fastlane)
  7. Using secrets in GitHub Actions (GitHub Docs)
  8. dotenv README: variable substitution (bkeepers/dotenv)
  9. match behaves differently in v2.220.0: wrong final block length (issue #21973) (fastlane on GitHub, 2024-04-15)
  10. Couldn't decrypt the repo, please make sure you enter the right password! (issue #20716) (fastlane on GitHub, 2022-09-29)
SharePost on XLinkedIn

Comments

Share a question or note about this article.

Loading comments…

fastlane match password error: Couldn't decrypt the repo | Nadeera Silva