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: Verify Depot Tools : Ensure depot_tools (which provides the cipd CLI) is available in the environment. 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 Clean Workspace : The script creates a pristine temporary working directory ( mktemp -d ) to prevent cache reuse. Cross-Platform Bundles : It leverages REPO_OS_OVERRIDE to fetch packages for linux , macosx ( amd64 and arm64 ), and windows . License Acceptance : All required Android SDK licenses are automatically accepted and packaged inside the upload directory. 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).