This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

了解如何在 EAS 工作流中设置和使用预打包的作业。

预封装作业是现成可用的工作流作业，可帮助你自动执行常见任务，例如构建、提交和测试应用。它们提供了一种标准化的方法来处理这些操作，而无需从头编写自定义作业配置。本指南介绍了可用的预封装作业以及如何在工作流中使用它们。

🌐 Pre-packaged jobs are ready-to-use workflow jobs that help you automate common tasks like building, submitting, and testing your app. They provide a standardized way to handle these operations without having to write custom job configurations from scratch. This guide covers the available pre-packaged jobs and how to use them in your workflows.

构建

🌐 Build

将你的项目构建成 Android 或 iOS 应用。

🌐 Build your project into an Android or iOS app.

构建作业可以自定义，以便在构建过程中执行自定义命令。有关更多信息，请参见自定义构建。

🌐 Build jobs can be customized so that you can execute custom commands during the build process. See Custom builds for more information.

语法

🌐 Syntax

jobs:
  build_app:
    type: build
    runs_on: string # optional - see https://expo.nodejs.cn/build-reference/infrastructure/ for available options
    params:
      platform: android | ios # required
      profile: string # optional - default: production
      message: string # optional
      refresh_ad_hoc_provisioning_profile: boolean # optional

参数

🌐 Parameters

你可以将以下参数传递到 params 列表中：

🌐 You can pass the following parameters into the params list:

环境变量

🌐 Environment variables

如果在构建过程中需要某些环境变量，你可以将它们包含在你的 eas.json 中，针对你指定的构建 profile。这些变量将从 EAS 环境变量 中获取。

🌐 If you need certain environment variables during the build process, you can include them in your eas.json, for your specified build profile. They will be pulled from EAS environment variables.

输出

🌐 Outputs

你可以在后续作业中引用以下输出：

🌐 You can reference the following outputs in subsequent jobs:

示例

🌐 Examples

以下是一些使用构建作业的实际示例：

🌐 Here are some practical examples of using the build job:

name: Build iOS app

on:
  push:
    branches: ['main']

jobs:
  build_ios:
    name: Build iOS
    type: build
    params:
      platform: ios
      profile: production

name: Build for all platforms

on:
  push:
    branches: ['main']

jobs:
  build_android:
    name: Build Android
    type: build
    params:
      platform: android
      profile: production

  build_ios:
    name: Build iOS
    type: build
    params:
      platform: ios
      profile: production

name: Build with environment variables

on:
  push:
    branches: ['main']

jobs:
  build_android:
    name: Build Android
    type: build
    env:
      APP_ENV: production
      API_URL: https://api.example.com
    params:
      platform: android
      profile: production

name: Build with different profiles

on:
  push:
    branches: ['main']

jobs:
  build_android_development:
    name: Build Android Development
    type: build
    params:
      platform: android
      profile: development

  build_android_production:
    name: Build Android Production
    type: build
    params:
      platform: android
      profile: production

name: Build iOS internal

on:
  push:
    branches: ['main']

jobs:
  build_ios:
    name: Build iOS Internal
    type: build
    params:
      platform: ios
      profile: preview
      refresh_ad_hoc_provisioning_profile: true

部署

🌐 Deploy

使用 EAS Hosting 部署你的应用。

🌐 Deploy your application using EAS Hosting.

语法

🌐 Syntax

jobs:
  deploy_web:
    type: deploy
    params:
      alias: string # optional
      prod: boolean # optional

参数

🌐 Parameters

你可以将以下参数传递到 params 列表中：

🌐 You can pass the following parameters into the params list:

输出

🌐 Outputs

你可以在后续作业中引用以下输出：

🌐 You can reference the following outputs in subsequent jobs:

示例

🌐 Examples

以下是一些使用部署任务的实际示例：

🌐 Here are some practical examples of using the deploy job:

name: Basic Deployment

jobs:
  deploy:
    name: Deploy to Production
    type: deploy
    params:
      prod: true

name: Deploy

on:
  push:
    branches: ['*']

jobs:
  deploy:
    name: Deploy
    type: deploy
    params:
      prod: ${{ github.ref_name == 'main' }}

name: Deployment with Alias

jobs:
  deploy:
    name: Deploy with Alias
    type: deploy
    params:
      alias: my-custom-alias
      prod: true

指纹

🌐 Fingerprint

计算项目的指纹。

🌐 Calculates a fingerprint of your project.

注意： 此工作类型仅支持 CNG 工作流程。如果你提交了 android 或 ios 目录，指纹工作将无法运行。

注意： 为确保指纹与你的构建匹配，请使用与构建配置相同的 environment 设置。对于环境变量，我们建议使用 EAS 环境变量，而不是 env 字段，以获得更好的一致性。

语法

🌐 Syntax

jobs:
  fingerprint:
    type: fingerprint
    environment: production | preview | development # optional, defaults to production
    env: # optional list of environment variables
      ENV_VAR_NAME: value

环境变量

🌐 Environment variables

你可以将一列环境变量传递给 env 参数。这些环境变量将从 EAS 环境变量 中提取。传递的 environment 参数将用于环境变量的环境，这在相同的环境变量在不同环境中定义时非常有用。

🌐 You can pass a list of environment variables into the env parameter. These environment variables will be pulled from EAS environment variables. The passed environment parameter will be used for the environment variable's environment, which is useful when the same environment variable is defined across different environments.

参数

🌐 Parameters

你可以将以下参数传递到 params 列表中：

🌐 You can pass the following parameters into the params list:

输出

🌐 Outputs

你可以在后续作业中引用以下输出：

🌐 You can reference the following outputs in subsequent jobs:

示例

🌐 Examples

以下是一些使用指纹作业的实际示例：

🌐 Here are some practical examples of using the fingerprint job:

name: Basic Fingerprint

jobs:
  fingerprint:
    name: Calculate Fingerprint
    type: fingerprint
    environment: production

name: Fingerprint with Environment Variables

jobs:
  fingerprint:
    name: Calculate Fingerprint
    type: fingerprint
    environment: production
    # Resulting environment will be a union of the "production" environment and the inline environment variables.
    # `env` variables override environment variables of the same name from the "production" environment.
    env:
      APP_VARIANT: staging
      API_URL: https://api.staging.example.com

获取构建

🌐 Get Build

从 EAS 检索与提供的参数匹配的现有构建。

🌐 Retrieve an existing build from EAS that matches the provided parameters.

语法

🌐 Syntax

jobs:
  get_build:
    type: get-build
    params:
      platform: ios | android # optional
      profile: string # optional
      distribution: store | internal | simulator # optional
      channel: string # optional
      app_identifier: string # optional
      app_build_version: string # optional
      app_version: string # optional
      git_commit_hash: string # optional
      fingerprint_hash: string # optional
      sdk_version: string # optional
      runtime_version: string # optional
      simulator: boolean # optional
      wait_for_in_progress: boolean # optional

参数

🌐 Parameters

你可以将以下参数传递到 params 列表中：

🌐 You can pass the following parameters into the params list:

如果将 wait_for_in_progress 设置为 true，作业仍然会优先立即继续成功的构建，但它也会查找正在进行的构建。如果没有找到成功的构建，作业将等待正在进行的构建完成后再继续。如果匹配的构建成功，作业将被标记为成功，并返回成功的构建。如果匹配的构建失败，作业将被标记为成功，其输出将为空——就好像该构建未被匹配一样。

🌐 If wait_for_in_progress is set to true, the job will still prioritize continuing immediately with a successful build, but it will also look for in-progress builds. If no successful build is found, the job will wait for an in-progress build to complete before continuing. If the matched build succeeds, the job will be marked as successful and will return the successful build. If the matched build fails, the job will be marked as successful and its outputs will be empty — as if the build has not been matched.

输出

🌐 Outputs

你可以在后续作业中引用以下输出：

🌐 You can reference the following outputs in subsequent jobs:

示例

🌐 Examples

以下是使用 get-build 任务的一些实际示例：

🌐 Here are some practical examples of using the get-build job:

name: Get Production Build

jobs:
  get_build:
    name: Get Latest Production Build
    type: get-build
    params:
      platform: ios
      profile: production
      distribution: store
      channel: production

name: Get Build by Version

jobs:
  get_build:
    name: Get Specific Version Build
    type: get-build
    params:
      platform: android
      app_identifier: com.example.app
      app_version: 1.0.0
      app_build_version: 42

name: Get Simulator Build

jobs:
  get_build:
    name: Get Simulator Build
    type: get-build
    params:
      platform: ios
      simulator: true
      profile: development
      wait_for_in_progress: true

提交

🌐 Submit

使用 EAS Submit 将 Android 或 iOS 版本提交到应用商店。

🌐 Submit an Android or iOS build to the app store using EAS Submit.

语法

🌐 Syntax

jobs:
  submit_to_store:
    type: submit
    runs_on: string # optional - see https://expo.nodejs.cn/build-reference/infrastructure/ for available options
    params:
      build_id: string # required
      profile: string # optional - default: production
    hooks:
      before_submit: step[] # optional - steps to run before the submission starts.
      after_submit: step[] # optional - steps to run after the submission completes.

参数

🌐 Parameters

你可以将以下参数传递到 params 列表中：

🌐 You can pass the following parameters into the params list:

输出

🌐 Outputs

你可以在后续作业中引用以下输出：

🌐 You can reference the following outputs in subsequent jobs:

钩子

🌐 Hooks

提交作业支持以下钩子：

🌐 The following hooks are supported for the Submit job:

• before_submit：提交开始前要进行的步骤。
• after_submit：提交完成后的操作步骤。

有关通用 hooks 语法，请参见 jobs.<job_id>.hooks。

示例

🌐 Examples

以下是一些使用提交作业的实际示例：

🌐 Here are some practical examples of using the submit job:

name: Submit iOS Build

jobs:
  build_ios:
    name: Build iOS
    type: build
    params:
      platform: ios
      profile: production

  submit:
    name: Submit to App Store
    type: submit
    needs: [build_ios]
    params:
      build_id: ${{ needs.build_ios.outputs.build_id }}
      profile: production

name: Submit Android Build

jobs:
  build_android:
    name: Build Android
    type: build
    params:
      platform: android
      profile: production

  submit:
    name: Submit to Play Store
    type: submit
    needs: [build_android]
    params:
      build_id: ${{ needs.build_android.outputs.build_id }}
      profile: production

TestFlight

将 iOS 构建分发到 TestFlight 的内部和外部测试组。这是 iOS 提交作业的替代方案，当你需要更高级的 TestFlight 功能时使用。如果你需要控制测试组、更新日志或测试版应用审核提交，请使用 testflight 作业而不是提交。

🌐 Distribute iOS builds to TestFlight internal and external testing groups. This is an alternative to the iOS submit job for when you need more advanced TestFlight features. If you need to control test groups, changelog, or Beta App Review submission, use the testflight job instead of submit.

该工作支持两种方法：上传构建并提交到 TestFlight（build_id），或提交已上传的构建（asc_build_id）。在两种情况下，你都可以将构建添加到群组，设置“测试内容”备注，并提交进行 Beta 应用审查。请仅提供 build_id 或 asc_build_id 中的一项。

🌐 The job supports two approaches: upload a build and submit it to TestFlight (build_id), or submit an already uploaded build (asc_build_id). In both cases, you can add the build to groups, set "What to Test" notes, and submit for Beta App Review. Provide exactly one of build_id or asc_build_id.

共享参数

🌐 Shared parameters

这两种方法在 params 中接受以下参数：

🌐 Both approaches accept the following parameters in params:

上传构建并提交到 TestFlight

🌐 Upload build and submit to TestFlight

在单一工作流程任务中上传 EAS iOS 构建并提交到 TestFlight。

🌐 Upload an EAS iOS build and submit it to TestFlight in a single workflow job.

语法

🌐 Syntax

jobs:
  testflight_distribution:
    type: testflight
    runs_on: string # optional - see https://expo.nodejs.cn/build-reference/infrastructure/ for available options
    params:
      build_id: string # required
      profile: string # optional - default: production
      internal_groups: string[] # optional
      external_groups: string[] # optional
      changelog: string # optional
      submit_beta_review: boolean # optional
      wait_processing_timeout_seconds: number # optional - default: 1800 (30 minutes)

参数

🌐 Parameters

你可以将以下参数传递到 params 列表中：

🌐 You can pass the following parameters into the params list:

你也可以传递任何 共享参数。

🌐 You can also pass any of the shared parameters.

输出

🌐 Outputs

你可以在后续作业中引用以下输出：

🌐 You can reference the following outputs in subsequent jobs:

示例

🌐 Examples

以下是一些使用 TestFlight 任务的实际示例：

🌐 Here are some practical examples of using the TestFlight job:

name: TestFlight Distribution

jobs:
  build_ios:
    name: Build iOS
    type: build
    params:
      platform: ios
      profile: production

  testflight:
    name: Distribute to TestFlight
    type: testflight
    needs: [build_ios]
    params:
      build_id: ${{ needs.build_ios.outputs.build_id }}
      internal_groups: ['QA Team']
      external_groups: ['Public Beta']
      changelog: |
        What's new in this release:
        - New features
        - Bug fixes

name: TestFlight with Changelog

jobs:
  testflight:
    name: Upload with Changelog
    type: testflight
    params:
      build_id: ${{ needs.build_ios.outputs.build_id }}
      changelog: "${{ github.commit_message || 'Bug fixes' }}"
      # github.commit_message only available in push & schedule events.

提交已上传的构建

🌐 Submit an already uploaded build

将已在 App Store Connect 中的构建提交到 TestFlight 群组，设置“测试内容”备注，并提交进行测试版应用审核。测试版应用审核提交是可选的。设置 submit_beta_review: false 可以在不重新提交审核的情况下更新现有构建的更新日志或群组。

🌐 Submit a build that is already in App Store Connect to TestFlight groups, set "What to Test" notes, and submit for Beta App Review. Beta App Review submission is optional. Set submit_beta_review: false to update the changelog or groups on an existing build without re-submitting it for review.

语法

🌐 Syntax

jobs:
  testflight_distribution:
    type: testflight
    params:
      asc_build_id: string # required
      internal_groups: string[]
      external_groups: string[]
      changelog: string
      submit_beta_review: boolean

参数

🌐 Parameters

你也可以传递任何 共享参数。

🌐 You can also pass any of the shared parameters.

输出

🌐 Outputs

示例

🌐 Examples

name: Distribute to TestFlight after ASC upload

on:
  app_store_connect:
    build_upload:
      states:
        - complete

jobs:
  distribute_to_testflight:
    name: Distribute to TestFlight
    type: testflight
    params:
      asc_build_id: ${{ app_store_connect.build_upload.build.id }}
      internal_groups:
        - QA Team
      external_groups:
        - Public Beta
      changelog: Build from CI
      submit_beta_review: true

name: Update TestFlight changelog

on:
  workflow_dispatch:
    inputs:
      asc_build_id:
        type: string
        required: true
        description: The App Store Connect build ID to update.
      changelog:
        type: string
        required: true
        description: The new "What to Test" notes.

jobs:
  update_changelog:
    name: Update changelog
    type: testflight
    params:
      asc_build_id: ${{ inputs.asc_build_id }}
      changelog: ${{ inputs.changelog }}
      submit_beta_review: false

更新

🌐 Update

使用 EAS Update 发布更新。

🌐 Publish an update using EAS Update.

语法

🌐 Syntax

jobs:
  publish_update:
    type: update
    environment: production | preview | development # optional, defaults to production
    env: # optional list of environment variables
      ENV_VAR_NAME: value
    runs_on: string # optional - see https://expo.nodejs.cn/build-reference/infrastructure/ for available options
    params:
      message: string # optional
      platform: string # optional - android | ios | all, defaults to all
      branch: string # optional
      channel: string # optional - cannot be used with branch
      rollout_percentage: number # optional - 0 to 100, defaults to 100
      private_key_path: string # optional
      upload_sentry_sourcemaps: boolean # optional - defaults to "try uploading, but don't fail the job if it fails"

环境变量

🌐 Environment variables

你可以将一列环境变量传递给 env 参数。这些环境变量将从 EAS 环境变量 中提取。传递的 environment 参数将用于环境变量的环境，这在相同的环境变量在不同环境中定义时非常有用。

🌐 You can pass a list of environment variables into the env parameter. These environment variables will be pulled from EAS environment variables. The passed environment parameter will be used for the environment variable's environment, which is useful when the same environment variable is defined across different environments.

参数

🌐 Parameters

你可以将以下参数传递到 params 列表中：

🌐 You can pass the following parameters into the params list:

输出

🌐 Outputs

你可以在后续作业中引用以下输出：

🌐 You can reference the following outputs in subsequent jobs:

示例

🌐 Examples

以下是一些使用更新作业的实际示例：

🌐 Here are some practical examples of using the update job:

name: Update Production

on:
  push:
    branches: ['main']

jobs:
  update_production:
    name: Update Production Channel
    type: update
    params:
      channel: production

name: Platform-specific Updates

on:
  push:
    branches: ['main']

jobs:
  update_android:
    name: Update Android
    type: update
    params:
      platform: android
      channel: production

  update_ios:
    name: Update iOS
    type: update
    params:
      platform: ios
      channel: production

name: Branch-based Updates

on:
  push:
    branches: ['main', 'staging']

jobs:
  update_branch:
    name: Update Branch
    type: update
    params:
      branch: ${{ github.ref_name }}
      message: 'Update for branch: ${{ github.ref_name }}'

删除分支

🌐 Branch delete

删除当前项目中的 EAS 更新 分支。与 eas branch:delete 相同。在 branch_name 中传递 EAS 更新分支名称。

🌐 Delete an EAS Update branch in the current project. The same as eas branch:delete. Pass the EAS Update branch name in branch_name.

语法

🌐 Syntax

jobs:
  delete_branch:
    type: branch-delete
    params:
      branch_name: string # required
      fail_on_missing: boolean # optional, default: false

参数

🌐 Parameters

你可以将以下参数传递到 params 列表中：

🌐 You can pass the following parameters into the params list:

输出

🌐 Outputs

你可以在后续作业中引用以下输出：

🌐 You can reference the following outputs in subsequent jobs:

示例

🌐 Examples

请参见 清理更新分支示例 了解一个使用 on.ref_delete 和 branch-delete 任务的工作流程。

🌐 See Clean up update branches example for a workflow that uses on.ref_delete with the branch-delete job.

大师

🌐 Maestro

在 Android 模拟器或 iOS 模拟器构建上运行 Maestro 测试。

🌐 Run Maestro tests on an Android Emulator or iOS Simulator build.

重要 Maestro 测试处于 alpha 阶段。

语法

🌐 Syntax

jobs:
  run_maestro_tests:
    type: maestro
    environment: production | preview | development # optional - defaults to preview
    image: string # optional - see https://expo.nodejs.cn/build-reference/infrastructure/ for a list of available images.
    params:
      build_id: string # required
      flow_path: string | string[] # required
      shards: number # optional - defaults to 1
      retries: number # optional - defaults to 0
      retry_failed_only: boolean # optional - defaults to true
      record_screen: boolean # optional - defaults to false
      include_tags: string | string[] # optional
      exclude_tags: string | string[] # optional
      maestro_version: string # optional - defaults to latest
      android_system_image_package: string # optional
      device_identifier: string | { android?: string, ios?: string } # optional
      output_format: string # optional - defaults to junit
    hooks:
      before_maestro_tests: step[] # optional - steps to run before the tests start.
      after_maestro_tests: step[] # optional - steps to run after the tests complete.

参数

🌐 Parameters

你可以将以下参数传递到 params 列表中：

🌐 You can pass the following parameters into the params list:

钩子

🌐 Hooks

Maestro 作业支持以下钩子：

🌐 The following hooks are supported for the Maestro job:

• before_maestro_tests：在测试开始前要执行的步骤。
• after_maestro_tests：测试完成后的运行步骤。

有关通用 hooks 语法，请参见 jobs.<job_id>.hooks。

示例

🌐 Examples

以下是一些使用 Maestro 任务的实际示例：

🌐 Here are some practical examples of using the Maestro job:

name: Basic Maestro Test

jobs:
  test:
    name: Run Maestro Tests
    type: maestro
    environment: preview
    params:
      build_id: ${{ needs.build_ios_simulator.outputs.build_id }}
      flow_path: ./maestro/flows

name: Sharded Maestro Test

jobs:
  test:
    name: Run Sharded Maestro Tests
    type: maestro
    environment: preview
    runs_on: linux-large-nested-virtualization
    params:
      build_id: ${{ needs.build_android_emulator.outputs.build_id }}
      flow_path: ./maestro/flows
      shards: 3
      retries: 2

name: Basic Maestro Test

jobs:
  test:
    name: Run Maestro Tests
    type: maestro
    env:
      MAESTRO_APP_ID: 'com.yourhost.yourapp'
    params:
      build_id: ${{ needs.build_ios_simulator.outputs.build_id }}

name: Maestro Hooks

jobs:
  test:
    name: Run Maestro Tests
    type: maestro
    environment: preview
    params:
      build_id: ${{ needs.build_ios_simulator.outputs.build_id }}
      flow_path: ./maestro_tests
    hooks:
      before_maestro_tests:
        - name: Generate Maestro flows
          run: npx tsx scripts/generate-maestro-tests.ts

name: Pixel E2E Test

jobs:
  test:
    name: Run Maestro Tests
    type: maestro
    runs_on: linux-large-nested-virtualization
    params:
      build_id: ${{ needs.build_android_emulator.outputs.build_id }}
      device_identifier: 'pixel_6'
      record_screen: true
      android_system_image_package: 'system-images;android-35;default;x86_64'

appId: com.myapp
---
- launchApp
- startRecording: ${MAESTRO_TESTS_DIR}/my_recording
- takeScreenshot: ${MAESTRO_TESTS_DIR}/my_screenshot
- tapOn: 'Login Button'
- takeScreenshot: ${MAESTRO_TESTS_DIR}/after_login_screenshot
- stopRecording

name: Maestro Artifact Reporting

jobs:
  test:
    name: Run Maestro Tests
    type: maestro
    environment: preview
    env:
      SLACK_WEBHOOK_URL: ${{ env.SLACK_WEBHOOK_URL }}
    params:
      build_id: ${{ needs.build_ios_simulator.outputs.build_id }}
      flow_path: ./maestro/flows
      record_screen: true
    hooks:
      after_maestro_tests:
        - name: Report Maestro artifacts
          run: npx tsx scripts/report-maestro-artifacts.ts "$MAESTRO_TESTS_DIR"

Maestro 云

🌐 Maestro Cloud

在 Maestro Cloud 上运行 Maestro 测试。

🌐 Run Maestro tests on Maestro Cloud.

重要 这需要一个 Maestro Cloud 账户和 Cloud 计划订阅。请访问 Maestro 文档 了解更多信息。

语法

🌐 Syntax

jobs:
  run_maestro_tests:
    type: maestro-cloud
    environment: production | preview | development # optional - defaults to preview
    image: string # optional- see https://expo.nodejs.cn/build-reference/infrastructure/ for a list of available images.
    params:
      build_id: string # required - ID of the build to test.
      maestro_project_id: string # required - Maestro Cloud project ID. Example: `proj_01jw6hxgmdffrbye9fqn0pyzm0`.
      flows: string # required - Path to the Maestro flow file or directory containing the flows to run. Corresponds to `--flows` param to `maestro cloud`.
      maestro_api_key: string # optional - defaults to `$MAESTRO_CLOUD_API_KEY`
      include_tags: string | string[] # optional - tags to include in the tests. Will be passed to Maestro as `--include-tags`.
      exclude_tags: string | string[] # optional - tags to exclude from the tests. Will be passed to Maestro as `--exclude-tags`.
      maestro_version: string # optional - version of Maestro to use for the tests. If not provided, the latest version will be used.
      maestro_config: string # optional - path to the Maestro `config.yaml` file to use for the tests. Will be passed to Maestro as `--config`.
      device_locale: string # optional - device locale to use for the tests. Will be passed to Maestro as `--device-locale`.
      device_model: string # optional - model of the device to use for the tests. Will be passed to Maestro as `--device-model`. Run `maestro list-cloud-devices` for a list of supported values.
      device_os: string # optional - OS of the device to use for the tests. Will be passed to Maestro as `--device-os`. Run `maestro list-cloud-devices` for a list of supported values.
      name: string # optional - name for the Maestro Cloud upload. Corresponds to `--name` param to `maestro cloud`.
      branch: string # optional - override for the branch the Maestro Cloud upload originated from. By default, if the workflow run has been triggered from GitHub, the branch of the workflow run will be used. Corresponds to `--branch` param to `maestro cloud`.
      async: boolean # optional - run the Maestro Cloud tests asynchronously. If true, the status of the job will only denote whether the upload was successful, _not_ whether the tests succeeded. Corresponds to `--async` param to `maestro cloud`.
    hooks:
      before_maestro_cloud: step[] # optional - steps to run before the Maestro Cloud upload.
      after_maestro_cloud: step[] # optional - steps to run after the Maestro Cloud upload.

参数

🌐 Parameters

你可以将以下参数传递到 params 列表中：

🌐 You can pass the following parameters into the params list:

重要 你需要在作业环境中设置 maestro_api_key 参数或 MAESTRO_CLOUD_API_KEY 环境变量。请访问 Maestro Cloud 的“设置”来生成 API 密钥，然后到 环境变量 将其添加到你的项目中。

钩子

🌐 Hooks

Maestro Cloud 作业支持以下钩子：

🌐 The following hooks are supported for the Maestro Cloud job:

• before_maestro_cloud：在 Maestro Cloud 上传之前要执行的步骤。
• after_maestro_cloud：在 Maestro Cloud 上传后要执行的步骤。

有关通用 hooks 语法，请参见 jobs.<job_id>.hooks。

输出

🌐 Outputs

你可以在后续作业中引用以下输出：

🌐 You can reference the following outputs in subsequent jobs:

注意： 使用 async: true 模式时，只有 maestro_cloud_url 输出可以保证有效。其他输出（流程计数和流程名称）可能无效或为空，因为任务不会等待上传完成，并且流程尚未执行。

你还可以使用 jobs.<job_id>.outputs 为此作业定义其他输出。

示例

🌐 Examples

以下是一些使用Maestro Cloud作业的实际示例：

🌐 Here are some practical examples of using the Maestro Cloud job:

name: Basic Maestro Test

jobs:
  test:
    name: Run Maestro Tests
    type: maestro-cloud
    environment: preview
    params:
      build_id: ${{ needs.build_ios_simulator.outputs.build_id }}
      maestro_project_id: proj_01jw6hxgmdffrbye9fqn0pyzm0
      flows: ./maestro/flows

name: Basic Maestro Test

jobs:
  test:
    name: Run Maestro Tests
    type: maestro-cloud
    env:
      MAESTRO_APP_ID: 'com.yourhost.yourapp'
    params:
      build_id: ${{ needs.build_ios_simulator.outputs.build_id }}
      maestro_project_id: proj_01jw6hxgmdffrbye9fqn0pyzm0
      flows: ./maestro/flows

name: Maestro Cloud with Notification

jobs:
  maestro_test:
    name: Run Maestro Cloud Tests
    type: maestro-cloud
    environment: preview
    params:
      build_id: ${{ needs.build.outputs.build_id }}
      maestro_project_id: proj_xyz
      flows: ./maestro/flows

  notify:
    name: Send Test Results
    after: [maestro_test]
    type: slack
    environment: production
    params:
      webhook_url: ${{ env.SLACK_WEBHOOK_URL }} # make sure to set it up in the right environment (see "environment: ..." above)
      message: 'Tests complete: ${{ after.maestro_test.outputs.successful_flows_count }}/${{ after.maestro_test.outputs.total_flows_count }} passed'

Slack

使用 Slack webhook URL 向 Slack 通道发送消息。

🌐 Send a message to a Slack channel using a Slack webhook URL.

语法

🌐 Syntax

jobs:
  send_slack_notification:
    type: slack
    params:
      webhook_url: string # required
      message: string # required if payload is not provided
      payload: object # required if message is not provided

参数

🌐 Parameters

你可以将以下参数传递到 params 列表中：

🌐 You can pass the following parameters into the params list:

示例

🌐 Examples

以下是一些使用 Slack 职位的实际示例：

🌐 Here are some practical examples of using the Slack job:

name: Build Notification

jobs:
  build_ios:
    name: Build iOS
    type: build
    params:
      platform: ios
      profile: production

  notify_build:
    name: Notify Build Status
    needs: [build_ios]
    type: slack
    environment: production
    params:
      webhook_url: ${{ env.SLACK_WEBHOOK_URL }}
      message: 'Build completed for app ${{ needs.build_ios.outputs.app_identifier }} (version ${{ needs.build_ios.outputs.app_version }})'

name: Rich Build Notification

jobs:
  build_android:
    name: Build Android
    type: build
    params:
      platform: android
      profile: production

  notify_build:
    name: Notify Build Status
    needs: [build_android]
    type: slack
    environment: production
    params:
      webhook_url: ${{ env.SLACK_WEBHOOK_URL }}
      payload:
        blocks:
          - type: header
            text:
              type: plain_text
              text: 'Build Completed'
          - type: section
            fields:
              - type: mrkdwn
                text: "*App:*\n${{ needs.build_android.outputs.app_identifier }}"
              - type: mrkdwn
                text: "*Version:*\n${{ needs.build_android.outputs.app_version }}"
          - type: section
            fields:
              - type: mrkdwn
                text: "*Build ID:*\n${{ needs.build_android.outputs.build_id }}"
              - type: mrkdwn
                text: "*Platform:*\n${{ needs.build_android.outputs.platform }}"
          - type: section
            text:
              type: mrkdwn
              text: 'Distribution: ${{ needs.build_android.outputs.distribution }}'

GitHub 评论

🌐 GitHub Comment

自动将工作流已完成的构建、更新和部署报告发布到 GitHub 拉取请求中。它特别适用于对 PR 构建提供即时反馈、通过二维码分享测试构建以便轻松在设备上测试、显示 EAS Hosting 部署预览以及自动化部署通知。你还可以通过提供 payload 参数来覆盖评论内容。

🌐 Automatically post reports of your workflow's completed builds, updates, and deployments to GitHub pull requests. It's particularly useful for providing instant feedback on PR builds, sharing test builds with QR codes for easy device testing, displaying EAS Hosting deployment previews, and automating deployment notifications. You can also override the comment contents by providing the payload parameter.

语法

🌐 Syntax

jobs:
  github_comment:
    type: github-comment
    params:
      message: string # optional - custom message to include in the report
      build_ids: string[] # optional - specific build IDs to include, defaults to all related to the running workflow
      update_group_ids: string[] # optional - specific update group IDs to include, defaults to all related to the workflow
      deployment_ids: string[] # optional - specific deployment IDs to include, defaults to all related to the workflow

  # instead of using message and the builds, updates, and deployments table, you can also override the comment contents with `payload`
  custom_github_comment:
    type: github-comment
    params:
      payload: string # optional - raw markdown/HTML content for fully custom comment

参数

🌐 Parameters

该工作以两种互斥的模式运行：

🌐 The job operates in two mutually exclusive modes:

模式1：自动模式（可覆盖）

🌐 Mode 1: Auto-with-overrides mode

默认行为是自动发现构建和更新，如果需要，你可以指定以下任意参数：

🌐 Default behavior is auto discovery builds and updates, you can specify any of these parameters if you want to:

自动发现行为：当未指定（未定义）build_ids、update_group_ids 或 deployment_ids 时，作业会自动从当前工作流中发现所有相关的构建、更新和部署。要明确排除构建、更新或部署，请传递一个空数组 []。

模式 2：有效载荷模式

🌐 Mode 2: Payload mode

使用有效载荷模式时，你不能指定任何其他参数。

🌐 When using payload mode, you cannot specify any other parameters.

输出

🌐 Outputs

你可以在后续作业中引用以下输出：

🌐 You can reference the following outputs in subsequent jobs:

示例

🌐 Examples

以下是展示 GitHub 评论作业两种模式的实际示例：

🌐 Here are practical examples demonstrating both modes of the GitHub Comment job:

自动覆盖模式示例

🌐 Auto-with-overrides mode examples

name: PR Auto Comment

on:
  pull_request: {}

jobs:
  # ...

  comment_on_pr:
    name: Post Results to PR
    after: [build_ios, build_android, publish_update, deploy]
    type: github-comment
    # No params needed - auto-discovers all builds, updates, and deployments

name: PR Custom Message

on:
  pull_request: {}

jobs:
  # ...

  comment_on_pr:
    name: Post Build to PR
    after: [build_ios, build_android, publish_update, deploy]
    type: github-comment
    params:
      message: '🎉 Preview builds are ready! Please test these changes before approving the PR.'
      # build_ids, update_group_ids, and deployment_ids are undefined, so auto-discovery is enabled

name: PR Preview

on:
  pull_request: {}

jobs:
  deploy:
    type: deploy
    name: Deploy PR Preview

  comment:
    needs: [deploy]
    type: github-comment

name: PR Specific Builds

on:
  pull_request: {}

jobs:
  # ...

  comment_update:
    name: Post Update to PR
    after: [build_ios, build_android, publish_update]
    type: github-comment
    params:
      message: 'Testing builds ready for QA review'
      build_ids:
        - ${{ after.build_ios.outputs.build_id }}
        - ${{ after.build_android.outputs.build_id }}
      update_group_ids:
        - ${{ after.publish_update.outputs.first_update_group_id }}

name: PR Updates Only

on:
  pull_request: {}

jobs:
  # ...

  comment_updates_only:
    name: Post Updates Only
    after: [publish_update]
    type: github-comment
    params:
      message: 'New update available for testing!'
      build_ids: [] # Empty array excludes all builds
      deployment_ids: [] # Empty array excludes all deployments
      # update_group_ids undefined = auto-discover updates

有效载荷模式示例

🌐 Payload mode examples

name: Custom PR Comment

on:
  pull_request: {}

jobs:
  # ...

  custom_comment:
    name: Post Custom Comment
    needs: [build_ios]
    type: github-comment
    params:
      # Payload mode: complete control over content
      # Cannot use message, build_ids, or update_group_ids with payload
      payload: |
        ## 🚀 Build Status Update

        ### iOS Build Completed
        - **Build ID**: `${{ needs.build_ios.outputs.build_id }}`
        - **Version**: ${{ needs.build_ios.outputs.app_version }}
        - **Build Number**: ${{ needs.build_ios.outputs.app_build_version }}

        ### Next Steps
        1. Download the build from [EAS Dashboard](https://expo.dev/accounts/[account]/projects/[project]/builds/${{ needs.build_ios.outputs.build_id }})
        2. Test on physical device
        3. Approve for TestFlight distribution

        ---
        *This comment was automatically generated by EAS Workflows*

name: Conditional PR Comment

on:
  pull_request: {}

jobs:
  build_android:
    name: Build Android
    type: build
    params:
      platform: android
      profile: preview

  comment_success:
    name: Post Success Comment
    needs: [build_android]
    if: ${{ needs.build_android.status == 'success' }}
    type: github-comment
    params:
      message: '✅ Android build succeeded! Ready for testing.'
      build_ids: # provided only for instructional purposes, you could as well omit this here
        - ${{ needs.build_android.outputs.build_id }}

  comment_failure:
    name: Post Failure Comment
    after: [build_android]
    if: ${{ after.build_android.status == 'failure' }}
    type: github-comment
    params:
      payload: |
        ❌ **Android build failed**

        Please check the [workflow logs](https://expo.dev/accounts/[account]/projects/[project]/workflows) for details.

苹果设备注册请求

🌐 Apple device registration request

暂停工作流运行，直到 iOS 设备注册特定的 Apple 团队 并且团队成员在 expo.dev 上批准该注册。使用此任务在 EAS 工作流中自动注册设备以进行 内部分发。

🌐 Pause a workflow run until an iOS device enrolls for a specific Apple Team and a team member approves that enrollment on expo.dev. Use this job to automate registering a device for internal distribution inside EAS Workflows.

当工作流到达此作业时，该作业和运行将进入 action-required 并保持暂停状态，直到流程完成：

🌐 When the workflow reaches this job, the job and the run enter action-required and stay paused until the flow completes:

1. 工作流运行页面显示用于注册设备的二维码和注册链接。
2. 在 iPhone 或 iPad 上，设备会下载配置描述文件并通过“设置”进行安装。每次只有一个配置文件可用，如果在八分钟内未安装，它将被移除。
3. 安装后，会收集唯一设备标识符 (UDID) 和元数据。
4. 在工作流运行页面上，团队成员可以批准或拒绝注册。批准会将作业标记为成功，并将输出（UDID、型号等）暴露给下游作业。拒绝会导致作业失败，并阻止使用 needs 的作业。

如果 UDID 已经在你的账户上注册，该任务仍然需要等待注册和批准后才能继续。

🌐 If the UDID is already registered on your account, the job still waits for enrollment and approval before continuing.

语法

🌐 Syntax

jobs:
  register_device:
    type: apple-device-registration-request
    params:
      apple_team_identifier: string # optional

参数

🌐 Parameters

你可以将以下参数传递到 params 列表中：

🌐 You can pass the following parameters into the params list:

输出

🌐 Outputs

在团队成员批准已注册设备后，你可以在后续作业中参考以下输出内容：

🌐 After a team member approves the enrolled device, you can reference the following outputs in subsequent jobs:

如果团队成员拒绝加入，则作业失败且不会设置输出。使用 needs 的下游作业将不会运行。

🌐 If a team member rejects the enrollment, the job fails and does not set outputs. Downstream jobs that use needs will not run.

示例

🌐 Examples

以下是使用 Apple 设备注册请求任务的一些实际示例：

🌐 Here are some practical examples of using the Apple device registration request job:

name: Register iOS device and notify Slack

jobs:
  register_device:
    type: apple-device-registration-request
    params:
      apple_team_identifier: XX33YYZ44Z
  notify_slack:
    needs: [register_device]
    type: slack
    environment: production
    params:
      webhook_url: ${{ env.SLACK_WEBHOOK_URL }}
      message: 'Registered device ${{ needs.register_device.outputs.identifier }} (${{ needs.register_device.outputs.model }})'

name: Register device and build iOS internal

jobs:
  register_device:
    type: apple-device-registration-request
    params:
      apple_team_identifier: ABCDE12345
  build_ios:
    needs: [register_device]
    type: build
    params:
      platform: ios
      profile: preview
      refresh_ad_hoc_provisioning_profile: true

需要批准

🌐 Require Approval

在继续工作流程之前，需要用户的批准。用户可以批准或拒绝，这将对应任务的成功或失败。

🌐 Require approval from a user before continuing with the workflow. A user can approve or reject which translates to success or failure of the job.

语法

🌐 Syntax

jobs:
  require_approval:
    type: require-approval

参数

🌐 Parameters

这个任务不需要任何参数。

🌐 This job doesn't take any parameters.

示例

🌐 Examples

以下是使用“需要批准”任务的一些实际示例：

🌐 Here are some practical examples of using the Require Approval job:

jobs:
  web_preview:
    name: Deploy Web Preview
    type: deploy

  require_approval:
    name: Deploy Web to Production?
    needs: [web_preview]
    type: require-approval

  web_production:
    name: Deploy Web Production
    needs: [require_approval]
    type: deploy
    params:
      prod: true

jobs:
  show_story_intro:
    name: Dragon and Knight Story Intro
    type: doc
    params:
      md: |
        # The Dragon and the Knight

        Once upon a time, in a land far away, a brave knight set out to face a mighty dragon.

        The dragon roared, breathing fire across the valley, but the knight stood firm, shield raised high.

        Now, the fate of their encounter is in your hands...

  require_approval:
    name: Should the knight and dragon become friends?
    needs: [show_story_intro]
    type: require-approval

  happy_ending:
    name: Friendship Ending
    needs: [require_approval]
    type: doc
    params:
      md: |
        ## A New Friendship

        The knight lowered his sword, and the dragon ceased its fire. They realized they both longed for peace. From that day on, they became the best of friends, protecting the kingdom together.

  epic_battle:
    name: Epic Battle Ending
    after: [require_approval]
    if: ${{ failure() }}
    type: doc
    params:
      md: |
        ## The Epic Battle

        The knight charged forward, and the dragon unleashed a mighty roar. Their battle shook the mountains and echoed through the ages. In the end, both were remembered as fierce and noble adversaries.

文档

🌐 Doc

在工作流日志中显示 Markdown 部分。

🌐 Displays a Markdown section in the workflow logs.

语法

🌐 Syntax

jobs:
  show_whats_next:
    type: doc
    params:
      md: string

参数

🌐 Parameters

你可以将以下参数传递到 params 列表中：

🌐 You can pass the following parameters into the params list:

示例

🌐 Examples

以下是一些使用文档工作的实际例子：

🌐 Here are some practical examples of using the Doc job:

jobs:
  build_ios:
    name: Build iOS
    type: build
    params:
      platform: ios
      profile: production

  submit:
    name: Submit to App Store
    type: submit
    needs: [build_ios]
    params:
      build_id: ${{ needs.build_ios.outputs.build_id }}
      profile: production

  next_steps:
    name: Next Steps
    needs: [submit]
    type: doc
    params:
      md: |
        # To do next

        Your app has just been sent to [App Store Connect](https://appstoreconnect.apple.com/apps).

        1. Download the app from TestFlight.
        2. Test the app a bunch.
        3. Submit the app for review.

重新打包

🌐 Repack

从现有构建中重新打包应用。此任务会重新打包应用的元数据和 JavaScript 包，而无需执行完整的原生重建，这对于创建与特定指纹兼容的更快速构建非常有用。

🌐 Repackages an app from an existing build. This job repackages the app's metadata and JavaScript bundle without performing a full native rebuild, which is useful for creating a faster build compatible with a specific fingerprint.

语法

🌐 Syntax

jobs:
  repack:
    type: repack
    runs_on: string # optional - see https://expo.nodejs.cn/build-reference/infrastructure/ for available options
    params:
      build_id: string # required
      profile: string # optional
      embed_bundle_assets: boolean # optional
      message: string # optional
      repack_version: string # optional

注意： 如果构建可能仍在进行中，请使用 get-build 和 wait_for_in_progress: true，然后将其 build_id 传递给 repack。

常见问题

🌐 Common questions

参数

🌐 Parameters

你可以将以下参数传递到 params 列表中：

🌐 You can pass the following parameters into the params list:

示例

🌐 Examples

以下是使用指纹与重打包任务的一些实际示例：

🌐 Here are some practical examples of using the Fingerprint with Repack jobs:

name: continuous-deploy-fingerprint

jobs:
  fingerprint:
    id: fingerprint
    type: fingerprint
    environment: production

  android_get_build:
    needs: [fingerprint]
    id: android_get_build
    type: get-build
    params:
      fingerprint_hash: ${{ needs.fingerprint.outputs.android_fingerprint_hash }}
      platform: android

  android_repack:
    needs: [android_get_build]
    id: android_repack
    if: ${{ needs.android_get_build.outputs.build_id }}
    type: repack
    params:
      build_id: ${{ needs.android_get_build.outputs.build_id }}

  android_build:
    needs: [android_get_build]
    id: android_build
    if: ${{ !needs.android_get_build.outputs.build_id }}
    type: build
    params:
      platform: android
      profile: preview-simulator

  android_maestro:
    after: [android_repack, android_build]
    id: android_maestro
    type: maestro
    image: latest
    params:
      build_id: ${{ needs.android_repack.outputs.build_id || needs.android_build.outputs.build_id }}
      flow_path: ['maestro.yaml']

  ios_get_build:
    needs: [fingerprint]
    id: ios_get_build
    type: get-build
    params:
      fingerprint_hash: ${{ needs.fingerprint.outputs.ios_fingerprint_hash }}
      platform: ios

  ios_repack:
    needs: [ios_get_build]
    id: ios_repack
    if: ${{ needs.ios_get_build.outputs.build_id }}
    type: repack
    params:
      build_id: ${{ needs.ios_get_build.outputs.build_id }}

  ios_build:
    needs: [ios_get_build]
    id: ios_build
    if: ${{ !needs.ios_get_build.outputs.build_id }}
    type: build
    params:
      platform: ios
      profile: preview-simulator

  ios_maestro:
    after: [ios_repack, ios_build]
    id: ios_maestro
    type: maestro
    image: latest
    params:
      build_id: ${{ needs.ios_repack.outputs.build_id || needs.ios_build.outputs.build_id }}
      flow_path: ['maestro.yaml']