Configuring Expo SDK Upgrades and EAS Workflows: Complete Guide for OpenAI Plugins

The openai/plugins repository provides deterministic CLI commands for upgrading Expo SDKs and production-ready EAS workflow configurations that automate deployments, PR previews, and native builds.

The Expo skills in the openai/plugins repository offer an opinionated approach to configuring Expo SDK upgrades and EAS workflows. Located under plugins/expo/skills/, these resources include the upgrading-expo skill for SDK migrations and the expo-deployment skill for CI/CD automation, complete with copy-pasteable bash scripts and GitHub Actions YAML definitions.

Step-by-Step Expo SDK Upgrade Process

The upgrade workflow is documented in plugins/expo/skills/upgrading-expo/SKILL.md and follows a strict sequence to prevent dependency conflicts and native build failures.

Upgrade Core Dependencies

Start by bumping the SDK and syncing peer dependencies according to the target SDK requirements:

npx expo install expo@latest
npx expo install --fix

Run Diagnostics and Clear Caches

Execute the Expo doctor to catch known issues, then purge caches to prevent stale native builds from interfering with the upgrade:

npx expo-doctor
npx expo export -p ios --clear
rm -rf node_modules .expo
watchman watch-del-all

Handle Native Pre-Builds

For projects with custom native code (bare workflow), regenerate the native projects to apply new SDK templates:

npx expo prebuild --clean

This step is required when the ios/ or android/ directories exist and the SDK upgrade includes native module changes, as detailed in the skill's bare workflow cache-clearing instructions.

Breaking-Change Checklists and Migration Guides

The upgrading-expo skill includes targeted references for high-impact migrations that often cause build failures during upgrades.

React 19 API Changes

According to plugins/expo/skills/upgrading-expo/references/react-19.md, migrate to React 19 by implementing these specific changes:

• Replace useContext with use
• Remove the .Provider suffix from context usage patterns
• Eliminate forwardRef in favor of standard ref passing

Native Architecture and Hermes Configuration

For SDK versions enabling the new architecture by default, configure expo-build-properties with useHermesV1: true as specified in the skill documentation. Review plugins/expo/skills/upgrading-expo/references/new-architecture.md for platform-specific native module migrations affecting packages like expo-audio and expo-video.

Configuring EAS CI/CD Workflows

Production-ready workflow definitions reside in plugins/expo/skills/expo-deployment/references/workflows.md. Place these YAML files in your repository's .eas/workflows/ directory to enable GitHub Actions integration.

Automated Web Deployment

Deploy to production on every push to the main branch using the deploy job type:

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy_web:
    type: deploy
    params:
      prod: true

PR Preview Workflows

Enable web previews for pull requests to validate changes before merging:

name: Web PR Preview
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  preview:
    type: deploy
    params:
      prod: false

For native Over-The-Air (OTA) updates during PR review, use the update job type to publish JavaScript bundles without rebuilding native binaries:

name: PR Preview
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  publish:
    type: update
    params:
      branch: "pr-${{ github.event.pull_request.number }}"
      message: "PR #${{ github.event.pull_request.number }}"

Production Release Pipeline

Automate iOS and Android builds and app store submissions when version tags are pushed:

name: Release
on:
  push:
    tags: ['v*']
jobs:
  build-ios:
    type: build
    params:
      platform: ios
      profile: production
  build-android:
    type: build
    params:
      platform: android
      profile: production
  submit-ios:
    type: submit
    needs: [build-ios]
    params:
      platform: ios
      profile: production
  submit-android:
    type: submit
    needs: [build-android]
    params:
      platform: android
      profile: production

Conditional Builds Based on File Changes

Optimize CI minutes by executing builds only when source files in specific directories change:

name: Conditional Release
on:
  push:
    branches: [main]
jobs:
  check-changes:
    type: run
    params:
      command: |
        if git diff --name-only HEAD~1 | grep -q "^src/"; then
          echo "has_changes=true" >> $GITHUB_OUTPUT
        fi
  build:
    type: build
    needs: [check-changes]
    if: needs.check-changes.outputs.has_changes == 'true'
    params:
      platform: all
      profile: production

Security Best Practices

Store certificates, API keys, and provisioning profiles in EAS Secrets rather than committing them to workflow files. Combine PR preview jobs with GitHub status checks to block merges until OTA builds complete successfully.

Summary

• Deterministic upgrades: Follow the CLI sequence in plugins/expo/skills/upgrading-expo/SKILL.md—install latest, run doctor, clear caches, and prebuild if native code exists.
• Breaking change coverage: Consult references/react-19.md and references/new-architecture.md for API migrations and Hermes engine configuration.
• EAS automation: Place workflow YAML files from plugins/expo/skills/expo-deployment/references/workflows.md into .eas/workflows/ to enable web deployments, PR previews, and production releases.
• Conditional execution: Use type: run jobs with git diff checks to skip unnecessary builds when only non-source files change.

Frequently Asked Questions

How do I clear caches for a bare workflow Expo project?

Clear Node modules and Expo caches with rm -rf node_modules .expo and watchman watch-del-all, then platform-specific caches: for iOS, run pod deintegrate in the ios/ directory; for Android, run ./gradlew clean in the android/ directory. Finish with npx expo prebuild --clean to regenerate native projects from the updated SDK templates.

When should I use npx expo prebuild --clean during an upgrade?

Execute npx expo prebuild --clean only when your project maintains custom native code in ios/ or android/ directories and the SDK upgrade includes native module migrations. This command regenerates the entire native project structure, applying new templates from the updated SDK while removing previous native configurations that may be incompatible.

Where should I store sensitive values like API keys in EAS workflows?

Store all sensitive values in EAS Secrets via the EAS dashboard or CLI, then reference them as environment variables in your eas.json configuration. Never commit API keys, certificates, or provisioning profiles directly into workflow YAML files stored in version control.

What is the difference between type: deploy and type: update in EAS workflows?

Use type: deploy for web deployments to Expo Hosting, setting prod: true for production environments or prod: false for staging previews. Use type: update for Over-The-Air (OTA) JavaScript updates to native iOS and Android apps, which pushes new bundles to specific branches without requiring a full native rebuild or app store submission.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}