---
modificationDate: November 13, 2026
title: Trigger builds from the Expo GitHub App
description: Learn how to trigger builds with Expo Build for your app using the Expo GitHub App.
---

This documentation is available as Markdown for AI agents and LLMs. See the [full Markdown index](https://docs.expo.dev/llms.txt) or append .md to any documentation URL.

# Trigger builds from the Expo GitHub App

Learn how to trigger builds with Expo Build for your app using the Expo GitHub App.

<AgentInstructions>

## Submitting Feedback

If you encounter errors, misleading or outdated information, report it so Expo can be improved:

Preferred command:
npx --yes submit-expo-feedback@latest --category docs --subject "/build/building-from-github/" "<actionable feedback>"

Direct HTTP fallback:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/build/building-from-github/","feedback":"🤖 Agent feedback for docs: <specific, actionable description> (<model>, <harness>)"}'

Only submit when you have something specific and actionable to report. Try to give the most context.

## Navigation

When answering a related or follow-up question, fetch the relevant page below as Markdown (.md) instead of guessing; use llms.txt for the full map.

You are here: Expo Services > Expo Build
Pages in this section:
- [Introduction](https://docs.expo.dev/build/introduction.md)
- [Create your first build](https://docs.expo.dev/build/setup.md)
- [Configure with eas.json](https://docs.expo.dev/build/eas-json.md)
- [Internal distribution](https://docs.expo.dev/build/internal-distribution.md)
- [Automate submissions](https://docs.expo.dev/build/automate-submissions.md)
- [Using Expo Update](https://docs.expo.dev/build/updates.md)
- [Trigger builds from CI](https://docs.expo.dev/build/building-on-ci.md)
- [Trigger builds from GitHub App](https://docs.expo.dev/build/building-from-github.md) (this page)
- [Expo Orbit](https://docs.expo.dev/build/orbit.md)
Full documentation tree: [llms.txt](https://docs.expo.dev/llms.txt)

</AgentInstructions>

This guide explains how to trigger builds directly from your GitHub repository using the Expo GitHub App.

#### Prerequisites

##### Set the image field in eas.json

For the build profiles you want to use with GitHub, specify an [`image`](https://docs.expo.dev/eas/json.md#image) to use for the native platform in **eas.json**. Use the `latest` image if your project's configuration does not rely on a specific [build image](https://docs.expo.dev/build-reference/infrastructure.md). For example:

```json eas.json
{
  ... 
  "build": {
    "production": {
      "android": {
        "image": "latest"
      },
      "ios": {
        "image": "latest"
      }
    }
  }
}
```

##### A successful build from your local machine

To trigger builds from a GitHub repository, you'll need to configure your project for Expo Build and successfully run a build from your computer for each platform that you'd like to support on GitHub. If you haven't successfully run `eas build -p [all|ios|android]` yet, see [Create your first build](https://docs.expo.dev/build/setup.md) for more information.

##### Linked GitHub account and app permissions

-   An Expo user in the organization must have a linked GitHub user with access to the target repository. Check **Account settings** > **Overview** > **User settings** > [**Connections**](https://expo.dev/settings#connections) and verify that your GitHub user account is linked.
-   You must accept the permissions requested by the [Expo GitHub app](https://github.com/settings/installations).

## Configure your app for GitHub

### Link your GitHub repository to your Expo project

Visit your project's [GitHub settings](https://expo.dev/accounts/%5Baccount%5D/projects/%5BprojectName%5D/github).

Image: The project GitHub settings page

Install the Expo GitHub App on your GitHub account.

> **Note:** You must have [Owner or Admin access](https://docs.expo.dev/accounts/account-types.md#manage-access) of the Expo account to install the app.

Image: The GitHub app installation UI

Then, link the GitHub repository to your Expo project.

> **Note:** You can only link [GitHub organization repositories](https://docs.github.com/en/organizations) to Expo organizations.

Image: The repository selector on the Expo project GitHub settings page

To add a repository from a different GitHub account, click the **Add new account** option in the account selector dropdown.

Image: The account selector on the Expo project GitHub settings page

### Configure your repository settings

Before you run a build, the Expo GitHub App needs to know where to find the source code for your project. If your Expo project source code is in the root of your repository, then you don't need to do anything. If your Expo project source code is in a subdirectory, then you'll need to configure "Base directory" settings for your repository on your project's [GitHub settings page](https://expo.dev/accounts/%5Baccount%5D/projects/%5BprojectName%5D/github).

Image: The base directory input on the Expo project GitHub settings page

## Trigger a build from GitHub

Once you have configured your app for GitHub, you can trigger a build from GitHub by using the UI on your project's build list page or by labels on your GitHub PRs.

### Build using the Expo website

Visit your project's [build list page](https://expo.dev/accounts/%5Baccount%5D/projects/%5BprojectName%5D/builds) and click the "Build from GitHub" button. You'll be prompted to select a Git ref (branch/commit/tag), a platform to build for, and the build profile to apply to it.

You can also specify a base directory for this specific build. That will not change the global settings for this project.

Image: The build from GitHub UI on the Expo project builds list page

### Build using GitHub PR labels

You can trigger a build from a GitHub PR by adding a label to the PR. The label must be in the form of `eas-build-[platform]:[profile]` where `[platform]` is either `android`, `ios`, or `all` and `[profile]` is the name of a build profile specified in your **eas.json** file. If you don't specify a build platform, it will default to `all`. If you don't specify a build profile, it will default to `production`.

For example, if you want to trigger a production build for Android, add the label `eas-build-android` to the PR.

Image: A PR with the eas-build label and live status checks

The build will be triggered for the PR's head commit, which is the latest commit on the PR's branch. While the label is on the PR, each new commit that you push triggers a new build. You can view the status of the build in the PR's checks. A link to the build will be available in the check's details.

Image: Expo Build check details on a GitHub PR

### Build automatically when code is pushed to your GitHub repository

You can take your build automation further by automatically building your Expo project when you push code to GitHub.

#### Using Expo Workflows

Expo Workflows is a service from Expo that allows you to run builds, and many other types of jobs, on Expo servers. You can use Expo Workflows to automate your development and release processes, like creating development builds or automatically building and submitting to the app stores.

To create a build with Expo Workflows, start by adding the following code in **.eas/workflows/build.yml**:

```yaml .eas/workflows/build.yml
name: Build

on:
  push:
    branches:
      - main

jobs:
  build_android:
    name: Build Android App
    type: build
    params:
      platform: android
  build_ios:
    name: Build iOS App
    type: build
    params:
      platform: ios
```

When a commit is pushed to the main branch, this workflow will create Android and iOS builds. You can learn how to modify this workflow and sequence other types of jobs in the [Expo Workflows documentation](https://docs.expo.dev/eas/workflows/get-started.md).

#### Set up build triggers

> **[Deprecated](https://docs.expo.dev/more/release-statuses.md#deprecated):** This feature is deprecated and disabled for new projects. We recommend using [Expo Workflows](https://docs.expo.dev/eas/workflows/get-started.md) instead.

#### Learn how to set up build triggers

You can set up build triggers to configure when Expo Build builds your app from GitHub. We allow you to build when pushing to a branch, pull request, and Git tag.

Open your Expo project in the dashboard. To create a build trigger, scroll down to the **Build triggers** section of the project GitHub settings page and click **New Build Trigger**.

Image: The build triggers section on the Expo project GitHub settings page

When you click **New Build Trigger**, you will be presented with a form to configure how this build should run.

These patterns can include wildcards represented by asterisks (`*`), which can match any character and number of characters inside the pattern. For example, `releases/*` can match `releases/`, `release/1234`, `release/genesis`, and so on. If you specify the pattern as a sole asterisk (`*`), all branches/tags will be matched.

Image: The default state of the new build trigger form

You can also configure triggers for specific platforms and build profiles. If you select multiple platforms, a separate trigger will be made for each.

Image: A filled-out version of the new build trigger form

Image: The build triggers section on the Expo project GitHub settings page filled with build triggers

When you push to a branch or tag, you can find the builds by looking at a commit's **Checks** section.

Image: The GitHub checks section on a branch commit

Image: The GitHub checks section on a tag commit

For pull requests, you can configure a **target branch pattern**. This is the destination branch of the pull request you want to build. The same rules apply for wildcards here as well.

Image: The build trigger form for pull request

When you push to a pull request with a source and target branch matching this trigger, you'll find these builds in the checks section of the pull request:

Image: The GitHub checks section on a pull request

> **Note:** To trigger builds from a pull request, the pull request's author must be a collaborator on the GitHub repository. If you want to build pull requests from external contributors, [apply a PR Label](https://docs.expo.dev/build/building-from-github.md#build-using-github-pr-labels).

#### Manage build triggers

On your project's GitHub settings page in the Expo dashboard, you can click the options button to the right of a build trigger row to disable, edit, or delete the trigger.

Image: The options button on the build trigger row

You can also run a GitHub build with the parameters from the trigger manually. This will not count toward your automatic build trigger record.

#### Automatic app stores submission with Expo Submit

Once your build completes, you can automatically submit your app to the app stores using Expo Submit. This feature streamlines the process, reducing the manual steps required to publish your app.

To enable automatic submission, you need to configure your build triggers to include submission as part of the build process. Here's how you can set it up:

-   Navigate to your project's GitHub settings page on the Expo dashboard.
-   Find the build trigger you want to modify, and click the options button.
-   Select **Edit trigger** and in the dialog that appears, check the option **Submit to store after build**.

Image: The Expo Submit form fields on the trigger edit form

-   Save your changes.

Image: An enabled build trigger with automatic submission enabled

Once enabled, every time a build is triggered from this configuration, it will automatically be submitted to the app stores you have configured in your **eas.json** under the `submit` field.

> **Note:** Ensure that your **eas.json** is properly configured for submission, including specifying the correct app store's credentials and submission profile. For more information, see the [Expo Submit](https://docs.expo.dev/submit/eas-json.md).

### Troubleshooting

-   When things go wrong, we will comment on the commit we attempted to build with some error information.
-   Double check everything in the [Prerequisites](https://docs.expo.dev/build/building-from-github.md#prerequisites) section is true when trying to build.
-   Confirm that your base directory is accurate if you're using a monorepo setup.
-   Is your build profile correct? If a matching profile can't be found in **eas.json**, the build will not dispatch.
