updating-android-sdk

name	updating-android-sdk
description	Upgrades Flutter's Android SDK dependency to a new Android API version (or preview/canary release) in packages.txt, verifies CIPD tag uniqueness, and packages/uploads the binaries using create_cipd_packages.sh across macOS, Linux, and Windows. Use whenever a user wants to pick up a new version of Android or upload Android SDK packages to CIPD.

Updating Flutter Android SDK and CIPD Packages

This skill guides the agent step-by-step through configuring new Android SDK components in packages.txt, verifying tag uniqueness, and running the repository's automation script to upload cross-platform archives to Chrome Infrastructure Package Deployment (CIPD).

Prerequisites & Permission Verification

Before modifying packages or triggering CIPD uploads, verify that the local environment and credentials are configured correctly:

1. Verify Depot Tools: Ensure depot_tools (which provides the cipd CLI) is available in the environment.
2. Verify CIPD Writer Permissions: The operation requires write access to the flutter/android/sdk/all/ CIPD prefix. Verify access before proceeding:

   cipd acl-check flutter/android/sdk/all/ -writer
   

   If access is denied, request the user apply for the flutter-cipd-writers role and authenticate via cipd auth-login.

---

Step 1: Configure Target SDK Packages (packages.txt)

The script create_cipd_packages.sh reads target SDK components and versions from packages.txt.

• Location: src/flutter/tools/android_sdk/packages.txt
• Format: <package_name>:<subdirectory_to_upload> (delimited by : for multi-directory uploads)

Querying Official Package Identifiers

Always query the local or remote Android SDK repository to confirm exact package identifiers:

sdkmanager --list --include_obsolete

[!IMPORTANT] Canary / Preview vs. Stable API Levels When adopting a pre-release or Canary Android version (such as Android 37 / Cinnamon Bun), sdkmanager often publishes platform components under a .0 suffix (e.g., platforms;android-37.0). Do not assume or enforce an integer API level string (platforms;android-37) if sdkmanager explicitly requires platforms;android-37.0. Using an incorrect package string will cause subsequent downloads to fail.

Example packages.txt Update

To add Android 37 platform and build-tools:

platforms;android-37.0,platforms;android-36,platforms;android-35,platforms;android-34:platforms
cmdline-tools;latest:cmdline-tools
build-tools;37.0.0,build-tools;36.1.0,build-tools;36.0.0,build-tools;35.0.0:build-tools
platform-tools:platform-tools
tools:tools
cmake;3.22.1:cmake
ndk;28.2.13676358:ndk

---

Step 2: Verify Tag Uniqueness & Run Upload Script

[!NOTE] Standardizing CIPD Version Tags Use clean version descriptors (e.g., 37v1, 37v2). Do not append legacy speculative suffixes such as unmodified now that create_cipd_packages.sh is the standardized upload pipeline.

CIPD tags and refs are immutable. Before executing the script, verify that your proposed version tag (e.g., 37v1) has not already been registered:

cipd describe flutter/android/sdk/all/mac-arm64 -version version:<VERSION_TAG>

• If the tag is unused: The command returns exit code 1 with Error: no such tag.. You may proceed.
• If the tag exists: The command outputs the existing Package: and Instance ID:. You must choose a new, unique version tag.

Once uniqueness is confirmed, execute the script:

cd src/flutter/tools/android_sdk
./create_cipd_packages.sh <VERSION_TAG> <PATH_TO_LOCAL_SDK>

Script Execution Mechanics

1. Clean Workspace: The script creates a pristine temporary working directory (mktemp -d) to prevent cache reuse.
2. Cross-Platform Bundles: It leverages REPO_OS_OVERRIDE to fetch packages for linux, macosx (amd64 and arm64), and windows.
3. License Acceptance: All required Android SDK licenses are automatically accepted and packaged inside the upload directory.
4. CIPD Creation: It calls cipd create to copy and tag packages under flutter/android/sdk/all/<cipd_name>.

---

Step 3: Verify CIPD Upload & Tagging

Verify that the packages were successfully registered across all architecture targets before rolling Engine dependencies:

# macOS Apple Silicon (arm64)
cipd describe flutter/android/sdk/all/mac-arm64 -version version:<VERSION_TAG>

# macOS Intel (amd64)
cipd describe flutter/android/sdk/all/mac-amd64 -version version:<VERSION_TAG>

# Linux (amd64)
cipd describe flutter/android/sdk/all/linux-amd64 -version version:<VERSION_TAG>

# Windows (amd64)
cipd describe flutter/android/sdk/all/windows-amd64 -version version:<VERSION_TAG>

Ensure the output displays a valid Instance ID and confirms the requested tag is bound to the ref.

---

Troubleshooting & Failure Mitigation

If any operation fails during package selection, authorization, or script execution, apply these precise remedies:

1. Permission Denied (cipd acl-check or cipd create fails)

• Symptom: cipd acl-check reports no roles, or uploading aborts with authorization errors.
• Mitigation: Direct the user to apply for the flutter-cipd-writers role (via MDB/Grants 8h/flutter-cipd-writers). Once granted, run cipd auth-login to refresh local access credentials before retrying.

2. Package Resolution Failure (sdkmanager aborts during download)

• Symptom: create_cipd_packages.sh exits with Warning: Failed to find package '<package_name>'.
• Mitigation: Do not guess or enforce strict integer rules (e.g., platforms;android-37). Run sdkmanager --list --include_obsolete to inspect published remote tags, and correct the exact package string in packages.txt (such as keeping .0 preview suffixes like platforms;android-37.0).

3. Interrupted Uploads & Tag Deprecation

• Symptom: A network interruption halts a multi-platform upload partway, or an incorrect package bundle was uploaded.
• Mitigation: CIPD uploads are final and cannot be overwritten. If a tag was partially uploaded or needs deprecation, direct the user to the internal LuCI Playbook guide for removing tags (Removing Duplicated CIPD Tags). When retrying an upload after a failure, you must select a new, unique version tag (e.g., bumping v1 to v2).

4. Missing Command-Line Tools

• Symptom: The script outputs SDK directory does not contain cmdline-tools.
• Mitigation: Ensure the path provided points to a valid Android SDK root containing cmdline-tools/latest/bin/sdkmanager (typically ~/Library/Android/sdk on macOS).