How to Configure EAS Builds for Expo Apps: Complete Setup Guide

Configure EAS builds for Expo apps by defining profiles in eas.json, creating declarative workflows under .eas/workflows/, and storing credentials as EAS Secrets to automate production releases and PR previews.

To configure EAS builds for Expo apps, you need three core components: the eas.json configuration file, YAML workflow definitions in .eas/workflows/, and securely managed EAS Secrets. The openai/plugins repository provides reference implementations showing how to structure these files for production-grade CI/CD pipelines, automated versioning, and multi-platform submissions.

Initialize Your EAS Project

Install EAS CLI and Authenticate

Begin by installing the global CLI and authenticating with your Expo account:

npm install -g eas-cli
eas login

Run eas init to generate the eas.json configuration file in your project root. According to the expo-deployment skill in plugins/exmo/skills/expo-deployment/SKILL.md (lines 82-115), this command creates default production and development build profiles with recommended settings for version management and resource allocation.

Generate eas.json

The initialization process creates the foundation for your build pipeline. The generated file includes critical settings like appVersionSource: "remote" for automatic version incrementing and iOS resource class specifications.

Configure Build Profiles in eas.json

The eas.json file declares build environments, global CLI settings, and submission credentials. Structure your configuration with distinct profiles for production releases and development iterations.

Production Builds

Define production profiles with automatic versioning and appropriately sized build machines:

{
  "cli": {
    "version": ">= 16.0.1",
    "appVersionSource": "remote"
  },
  "build": {
    "production": {
      "autoIncrement": true,
      "ios": {
        "resourceClass": "m-medium"
      }
    }
  }
}

• autoIncrement tells EAS to bump the version automatically on each successful build.
• resourceClass selects the build machine size (e.g., m-medium for medium-sized macOS instances).

Development Builds

Configure development clients for internal distribution:

{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal"
    }
  }
}

Submit Configuration

Store App Store and Play Store credentials in the submit block. As documented in plugins/expo/skills/expo-deployment/SKILL.md, include your Apple ID, App Store Connect App ID, and Google service account paths:

{
  "submit": {
    "production": {
      "ios": {
        "appleId": "[email protected]",
        "ascAppId": "1234567890"
      },
      "android": {
        "serviceAccountKeyPath": "./google-service-account.json",
        "track": "internal"
      }
    }
  }
}

Automate with EAS Workflows

EAS workflows are declarative YAML files stored under .eas/workflows/ that orchestrate builds, submissions, and updates based on Git events.

Workflow Structure and Syntax

The expo-cicd-workflows skill in plugins/expo/skills/expo-cicd-workflows/SKILL.md (lines 45-51 and 70-77) defines the top-level schema: name, on, jobs, defaults, and concurrency. Supported job types include build, submit, update, deploy, and run.

Production Release Pipeline

Create a workflow that triggers on version tags and sequences builds before submission. This example from plugins/expo/skills/expo-deployment/references/workflows.md (lines 64-101) demonstrates the dependency chain:

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

The on.push.tags rule executes only when tags matching v* are pushed. The needs array ensures submission jobs wait for successful builds, preventing failed uploads to App Store Connect or Google Play Console.

PR Previews and OTA Updates

Publish over-the-air (OTA) updates for every pull request to enable reviewer testing without full native builds. As shown in plugins/expo/skills/expo-deployment/references/workflows.md (lines 45-62):

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 }}"

This workflow publishes updates to a temporary EAS branch, generating preview URLs for stakeholders.

Secure Your Build Pipeline

Managing EAS Secrets

Never hard-code sensitive values in workflow YAML. Store Apple credentials, API keys, and service account JSON as EAS Secrets via the dashboard, then reference them using the ${{ secrets.MY_SECRET }} syntax. The reference guide in plugins/expo/skills/expo-deployment/references/workflows.md (lines 99-101) explicitly warns against committing sensitive values to source control.

Workflow Validation

Validate workflow files against the official schema before committing. The expo-cicd-workflows skill recommends using the bundled validator script (scripts/validate.js) to catch syntax errors (lines 78-85). The schema URL is https://api.expo.dev/v2/workflows/schema.

Summary

• Initialize your project with eas init to generate eas.json with remote version sources and resource classes.
• Configure distinct production and development build profiles, enabling autoIncrement for version management.
• Automate releases using .eas/workflows/*.yml files that trigger on Git tags, with needs dependencies ensuring build-then-submit sequences.
• Secure credentials as EAS Secrets and reference them via ${{ secrets.NAME }} syntax rather than hard-coding.
• Validate workflow files against the EAS schema to prevent CI failures.

Frequently Asked Questions

What is the difference between EAS Build and EAS Update?

EAS Build compiles native binaries for iOS and Android in the cloud, producing .ipa and .aab files for store submission. EAS Update publishes JavaScript bundles and assets to the Expo CDN for over-the-air (OTA) delivery to existing app installations without requiring a new native build. Use EAS Build for native code changes and EAS Update for JavaScript-only modifications.

How do I trigger builds only on version tags?

Configure the on trigger in your workflow YAML to listen for specific tag patterns. Use on.push.tags: ['v*'] to execute the workflow only when tags starting with "v" (e.g., v1.0.0) are pushed to the repository. This pattern ensures production builds align with semantic versioning releases rather than every commit.

Where should I store sensitive credentials for EAS submissions?

Store sensitive credentials—including Apple ID passwords, App Store Connect API keys, and Google Play service account JSON files—as EAS Secrets in the EAS dashboard. Reference these secrets in your workflow files using the ${{ secrets.SECRET_NAME }} interpolation syntax. Never commit credentials to eas.json or workflow YAML files in your repository.

Can I use EAS Workflows with self-hosted runners?

The openai/plugins reference implementations focus on cloud-hosted EAS Build infrastructure. While EAS Build primarily uses Expo's managed build servers, you can configure EAS Build to run on custom infrastructure using the --local flag for debugging. However, the declarative .eas/workflows/ syntax documented in plugins/expo/skills/expo-cicd-workflows/SKILL.md is designed for Expo's cloud execution environment.

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