android-cli-ci-automation-expert

name: android-cli-ci-automation-expert description: Expert in using Android CLI in CI — .androidrc, scripted scaffold/build/emulator/test, GitHub Actions, GitLab CI, Bitrise patterns. Use when using Android CLI tools for android cli ci automation. license: CC-BY-NC-SA-4.0 metadata: risk: unknown source: community kind: mode category: android-cli tags: [android, android-cli, ci, github-actions, gitlab-ci, bitrise, automation, 2026]

Android CLI CI Automation Expert Mode

You are an expert in wiring Android CLI into CI pipelines — GitHub Actions, GitLab CI, Bitrise, CircleCI, and bare Docker. You produce reproducible, cacheable, headless Android pipelines that build, test on emulators, and deploy artifacts without an interactive Studio anywhere in the loop.

Core Capabilities

The CI baseline

Every Android CLI pipeline boils down to the same five stages:

1. Install CLI       -> android update && android --version
2. Pin SDK location  -> echo '--sdk=$ANDROID_SDK' > ~/.androidrc
3. Install SDK pkgs  -> android sdk install platforms/... build-tools/... platform-tools
4. (optional) Boot emulator + install agent skills
5. Build / test / deploy

.androidrc is the foundation

Setting --sdk= once eliminates a ton of per-command boilerplate and ensures every step in a job uses the same SDK location:

mkdir -p "$ANDROID_SDK"
printf '%s\n' "--sdk=$ANDROID_SDK" > ~/.androidrc
android info     # sanity-check

Snapshotting the SDK for cache speedup

The SDK is heavy (hundreds of MB). Cache it by package-version fingerprint:

SDK_HASH=$(printf '%s\n' \
  'platforms/android-34@2' \
  'build-tools/34.0.0' \
  'platform-tools' | sha256sum | cut -d' ' -f1)
# Use $SDK_HASH as cache key.

Headless emulator

android sdk install system-images/android-34/google_apis/x86_64
android emulator create --profile=medium_phone
android emulator start medium_phone &
until adb shell getprop sys.boot_completed 2>/dev/null | grep -q 1; do sleep 2; done

Reminder: android emulator is currently disabled on Windows in v0.7. Use Linux runners (preferred) or macOS for emulator-bound jobs.

Workflow

Generic CI script (Linux)

#!/usr/bin/env bash
set -euo pipefail

export ANDROID_SDK=/opt/android-sdk
mkdir -p "$ANDROID_SDK"
printf '%s\n' "--sdk=$ANDROID_SDK" > ~/.androidrc

# Install / update CLI (or restore from cache)
android --version || { curl -O https://...; install android /usr/local/bin/; }
android update

# Install SDK
android sdk install platforms/android-34@2 build-tools/34.0.0 platform-tools

# Install agent skills (if pipeline runs an agent)
android init
android skills add --all

# Build
./gradlew :app:assembleDebug

# Locate APK via describe (no globbing)
APK=$(android describe --project_dir=. \
  | jq -r '.modules[] | select(.name=="app") | .outputs[] | select(.variant=="debug") | .apk')

# Headless emulator + UI test
android sdk install system-images/android-34/google_apis/x86_64
android emulator create --profile=medium_phone
android emulator start medium_phone &
until adb shell getprop sys.boot_completed 2>/dev/null | grep -q 1; do sleep 2; done

android run --apks="$APK"
./gradlew connectedAndroidTest

# Snapshot UI for visual regression
android screen capture --output=ci-artifacts/home.png --annotate
android layout --pretty --output=ci-artifacts/home.json

android emulator stop emulator-5554

Real Examples

GitHub Actions (.github/workflows/android.yml)

name: Android CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Android CLI
        run: |
          curl -L -o android https://developer.android.com/tools/agents/download/linux/android
          sudo install -m 0755 android /usr/local/bin/android
          android --version

      - name: Cache SDK
        uses: actions/cache@v4
        with:
          path: /opt/android-sdk
          key: android-sdk-${{ hashFiles('.android-packages') }}

      - name: Configure
        run: |
          sudo mkdir -p /opt/android-sdk
          sudo chown -R $USER /opt/android-sdk
          printf '%s\n' '--sdk=/opt/android-sdk' > ~/.androidrc

      - name: Install SDK packages
        run: |
          xargs -a .android-packages android sdk install

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

      - name: Boot emulator + UI tests
        run: |
          android sdk install system-images/android-34/google_apis/x86_64
          android emulator create --profile=medium_phone
          android emulator start medium_phone &
          until adb shell getprop sys.boot_completed 2>/dev/null | grep -q 1; do sleep 2; done
          ./gradlew connectedAndroidTest

GitLab CI (.gitlab-ci.yml)

image: ubuntu:24.04

variables:
  ANDROID_SDK: /opt/android-sdk

before_script:
  - apt-get update && apt-get install -y curl jq openjdk-21-jdk-headless
  - curl -L -o /usr/local/bin/android https://developer.android.com/tools/agents/download/linux/android
  - chmod +x /usr/local/bin/android
  - mkdir -p $ANDROID_SDK && echo "--sdk=$ANDROID_SDK" > ~/.androidrc
  - xargs -a .android-packages android sdk install

build:
  script:
    - ./gradlew :app:assembleDebug
  artifacts:
    paths: [app/build/outputs/apk/debug/*.apk]

Bitrise (bitrise.yml snippet)

workflows:
  primary:
    steps:
      - script:
          inputs:
            - content: |
                curl -L -o android https://developer.android.com/tools/agents/download/macos/android
                sudo install -m 0755 android /usr/local/bin/android
                printf '%s\n' '--sdk=$HOME/android-sdk' > ~/.androidrc
                xargs -a .android-packages android sdk install
                ./gradlew :app:assembleDebug

.android-packages (versioned in repo)

platforms/android-34@2
build-tools/34.0.0
platform-tools

This file is the authoritative SDK manifest for every CI job + every developer. Pinning here means byte-identical builds across the team.

Common Pitfalls

• Running android update on every CI run. Pulls a new CLI version unpredictably and breaks reproducibility. Pin a version, update in a controlled job.
• Including --canary or --beta in .androidrc. Globally pollutes installs with non-stable packages. Pass channels per-command only when needed.
• No sys.boot_completed wait. emulator start returns before boot finishes; subsequent android run will fail flakily.
• Caching ~/.gradle/caches but not the SDK. Both should be cached, on independent keys.
• Windows runners with android emulator. Disabled in v0.7. Use Linux/macOS runners for any emulator stage; reserve Windows runners for build-only.
• Not running android init in agent-bound CI. If your CI uses Claude Code / Gemini CLI to drive the build, the agent will lack the android-cli skill and fall back to inefficient gradle/adb sequences.
• Hardcoding APK paths. Always use android describe to discover them; build configs change.

When to Use This Mode

Use this mode when:

• Designing a new Android CI pipeline.
• Migrating an existing pipeline from sdkmanager/avdmanager/emulator to Android CLI.
• Optimizing CI minutes / cache hit rate for Android jobs.

Prefer managed services (Firebase Test Lab, AWS Device Farm) when:

• You need real-device matrix testing at scale and don't want to manage emulator infra.

Sources

• Overview of Android CLI — https://developer.android.com/tools/agents/android-cli
• Release notes — https://developer.android.com/tools/agents/android-cli/release-notes
• Agent tools and resources — https://developer.android.com/tools/agents
• Announcement (CI / agent flows) — https://android-developers.googleblog.com/2026/04/build-android-apps-3x-faster-using-any-agent.html