Matcha mobile CI artifacts

Use this when Matcha should run saved Android or iOS mobile scenarios against the fresh build from a pull request.

Matcha resolves GitHub Actions artifacts from the repository bound in QA settings and only uses artifacts from the current PR head commit. The artifact download URL, tokens, and archive contents stay internal; user-facing surfaces show safe metadata such as artifact name, workflow run, commit SHA, file name, size, and digest.

Configure Matcha first

In Coldtea settings, open QA → GitHub PR testing → Fresh mobile build QA.

Set:

The mobile platforms to run.
The scenario group mapping for each target branch.
The build wait timeout and retry interval.
One exact artifact name or one constrained one-star glob per line.

Keep the artifact names narrow. Matcha rejects regex-like patterns, path segments, broad globs, unsupported extensions, and ambiguous multiple matches.

Artifact names

Upload one matching artifact per platform per workflow run. The default settings recognize either default name, but uploading both defaults in the same run is ambiguous unless you narrow the setting to one name.

Platform	Default artifact names	Artifact contents
Android	`matcha-android-apk` or `matcha-android-build`	One Android `.apk` file. Extra manifest text files are OK.
iOS Simulator	`matcha-ios-simulator-app` or `matcha-ios-simulator-build`	One archive file, `.zip` or `.tar.gz`, containing an iOS Simulator `.app` bundle. Extra manifest text files are OK.

Custom names can omit a file extension like the defaults do. If a custom Android artifact name includes a terminal extension, use .apk or .zip; if a custom iOS artifact name includes one, use .zip or .tar.gz. The artifact name is not a path.

Android GitHub Actions example

This example uploads the default Android artifact and includes a small SHA manifest for human provenance. Matcha still validates the GitHub workflow run head SHA before using the artifact.

name: Android PR build

on:
  pull_request:
    branches: [main]

jobs:
  android:
    runs-on: ubuntu-latest
    env:
      MATCHA_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ env.MATCHA_HEAD_SHA }}

      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: "17"

      - name: Build debug APK
        run: ./gradlew :app:assembleDebug

      - name: Prepare Matcha artifact
        run: |
          mkdir -p build/matcha
          cp app/build/outputs/apk/debug/app-debug.apk \
            "build/matcha/app-debug-${MATCHA_HEAD_SHA}.apk"
          printf '%s\n' "${MATCHA_HEAD_SHA}" > build/matcha/head-sha.txt

      - name: Upload Matcha Android artifact
        uses: actions/upload-artifact@v4
        with:
          name: matcha-android-apk
          path: |
            build/matcha/app-debug-${{ env.MATCHA_HEAD_SHA }}.apk
            build/matcha/head-sha.txt
          if-no-files-found: error
          retention-days: 7

The uploaded artifact must contain exactly one APK. Do not upload .aab, .xapk, multiple APK variants, or a broad build directory for this workflow.

iOS Simulator GitHub Actions example

Matcha uses iOS Simulator builds only. Build with the iphonesimulator SDK and upload a .zip or .tar.gz that contains the .app bundle. Do not export or upload an .ipa.

name: iOS Simulator PR build

on:
  pull_request:
    branches: [main]

jobs:
  ios-simulator:
    runs-on: macos-latest
    env:
      MATCHA_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
      SCHEME: MyApp
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ env.MATCHA_HEAD_SHA }}

      - name: Build Simulator app
        run: |
          xcodebuild \
            -scheme "${SCHEME}" \
            -configuration Debug \
            -sdk iphonesimulator \
            -destination 'generic/platform=iOS Simulator' \
            -derivedDataPath build/DerivedData \
            CODE_SIGNING_ALLOWED=NO \
            build

      - name: Package Simulator .app for Matcha
        run: |
          mkdir -p build/matcha
          APP_PATH="$(find build/DerivedData/Build/Products/Debug-iphonesimulator \
            -maxdepth 1 -type d -name '*.app' | head -n 1)"
          test -n "${APP_PATH}"
          ditto -c -k --keepParent "${APP_PATH}" build/matcha/Matcha.app.zip
          printf '%s\n' "${MATCHA_HEAD_SHA}" > build/matcha/head-sha.txt

      - name: Upload Matcha iOS Simulator artifact
        uses: actions/upload-artifact@v4
        with:
          name: matcha-ios-simulator-app
          path: |
            build/matcha/Matcha.app.zip
            build/matcha/head-sha.txt
          if-no-files-found: error
          retention-days: 7

A .tar.gz package is also supported:

tar -czf build/matcha/Matcha.app.tar.gz \
  -C "$(dirname "${APP_PATH}")" \
  "$(basename "${APP_PATH}")"

The archive must contain one Simulator .app bundle. Matcha rejects .ipa, disguised .ipa.zip / .ipa.tar.gz, missing .app bundles, and artifacts containing multiple app archives. Device builds from the iphoneos SDK are unsupported and out of scope; rebuild with iphonesimulator before uploading.

Troubleshooting

State or symptom	What it means	What to check
Stale SHA (`stale_sha`)	The matching artifact belongs to an older PR commit and will not be used.	Rerun CI after the latest push. Make sure checkout/build steps use the PR head SHA and the workflow is running for the current PR head.
Missing artifact (`artifact_not_found`)	No artifact matched the configured name before the wait timeout.	Check `upload-artifact` `name`, platform enablement, branch/group mapping, workflow success, and whether the artifact name is too broad or narrowed to the wrong value.
Expired artifact (`github_artifact_expired`)	GitHub no longer allows Matcha to download the Actions artifact.	Rerun the workflow or increase `retention-days` enough for Matcha's wait window and review workflow.
Permission denied (`access_denied`)	Matcha cannot access the repo or artifact through the GitHub installation and TeaHouse/project binding.	Confirm the right TeaHouse, repo binding, GitHub App installation, repository access, and Actions artifact permissions.
Provider registration failed (`provider_registration_failed`)	Matcha resolved the source artifact but could not register the build with the mobile provider.	Confirm the artifact validates locally, provider credentials are enabled, and provider quota/rate/concurrency limits are not exhausted. Retry while the retained source artifact is still available.
Retention or source unavailable (`provider_build_expired`, `source_artifact_unavailable`, or `github_artifact_expired`)	The provider build, retained source artifact, or original GitHub artifact is no longer available.	Use the available rerun option: same provider build, retained source artifact, or latest matching PR artifact. If none are available, rerun CI to publish a new artifact.
Rerun unavailable (`artifact_not_found`, `source_artifact_unavailable`, or `provider_cleanup_required`)	The requested rerun mode depends on a provider build or source artifact that expired or was cleaned up.	Pick a different rerun mode if shown, or rerun the GitHub Actions workflow for the current commit.

If the setup state is unclear, start with the GitHub workflow run for the current PR head SHA, then compare the uploaded artifact name and contents against the settings in Coldtea.