# Deploy from GitHub > Deploy an app from a GitHub repository in Orchard and turn on auto-deploy so that each push builds and rolls out a new version. Source: https://docs.orchard.hackclub.com/deploy/github/ Connect a GitHub repository and Orchard builds it into a running app, using the repository's Dockerfile or the framework it detects. Turn on auto-deploy so that each push to a branch builds and rolls out a new version, and add watch paths so that pushes which do not touch the app skip the build. ## Prerequisites - A GitHub App on the instance. A superadmin creates it during setup, or by following [Connect a GitHub App](/operate/finishing-setup/#connect-a-github-app). - A GitHub account linked to Orchard. Go to **Account settings** > **Connections**, and in **GitHub**, select **Connect**. - The GitHub App installed on the account that owns the repository. Go to **Account settings** > **Connections**, and in **Repository access**, select **Add account**. You can deploy a public repository without these items. In the repository search field, paste `owner/repo`. Auto-deploy still needs the GitHub App and write access to the repository. If the repository later becomes private, builds stop until someone with access to it links it again. Orchard lists only the repositories your own GitHub account granted to the GitHub App. Two people in the same project can see different lists. ## Create the app **Dashboard** 1. Open a project. 2. Select **New app**. 3. In **Start from scratch**, select **GitHub repo**. 4. In **Repository**, select the repository. 5. In **Branch**, select the branch. 6. In **Name**, enter a name for the app. 7. In **Build with**, confirm the build method. Orchard selects **Dockerfile** if the repository has one. Otherwise, it selects the framework it detects. 8. (Optional) Expand **Build and output settings** to change the Dockerfile path or build stage. 9. Under **Environment variables**, review the variables that Orchard detected. 10. Under **Networking**, confirm the port. 11. Select a reach. For the options, refer to [Reach](/deploy/networking/#reach). 12. Select **Deploy**. Orchard opens the build progress page. **CLI** ```sh orchard deploy create --github owner/repo#main --name web --port 3000 --wait ``` For the build flags, refer to the [CLI reference](/reference/cli/). ## Detected settings Orchard reads the repository and fills in the form. | Field | Detected from | | ------------------------- | ---------------------------------------------------------------- | | **Build with** | A `Dockerfile`, or framework detection when no Dockerfile exists | | **Dockerfile** | The file Orchard found | | **Stage** | The stages in the Dockerfile. The default is **Final stage**. | | **Port** | `EXPOSE`, or the default port of the framework | | **Environment variables** | `ENV` lines in the image | In a monorepo, turn on **Build from the repository root** if the Dockerfile copies files from outside its own directory. If the repository contains a [`score.yaml`](/deploy/score/) file, the form shows a summary of what the file provisions. ## Auto-deploy Auto-deploy builds and rolls out the app when you push to the selected branch. ### Turn on auto-deploy **Dashboard** 1. Open the app. 2. Go to **Settings** > **Deploy behavior**. 3. In **Auto-deploy**, enter the branch in **Branch**. 4. Turn on **Deploy on push**. If the GitHub App is not installed on the repository, the page shows **Install GitHub App** instead of the switch. Select it and add the repository. **CLI** ```sh orchard deploy auto-deploy enable --branch main ``` ### Limit builds to certain paths Watch paths limit which pushes start a build. With an empty list, every push builds. ```text apps/api/** packages/shared/** package.json !**/*.md ``` - Enter one glob per line. Orchard matches each glob against every file the push changed. - `**` crosses directories. `*` stays inside one segment. `{a,b}` matches either value. - A bare directory, such as `apps/api`, covers everything under it. - A line that starts with `!` excludes matches. An exclude takes priority over an include. - A list of only excludes watches everything else. If Orchard cannot tell what a push changed, it builds. **Dashboard** 1. Go to **Settings** > **Deploy behavior**. 2. In **Watch paths**, enter the globs. 3. Select **Save**. **CLI** ```sh orchard deploy auto-deploy enable --branch main --path 'apps/api/**' --path '!**/*.md' ``` To clear the list, pass `--path ""`. ### Troubleshoot auto-deploy **Symptom:** Auto-deploy is on, but pushes do not build. **Cause:** The GitHub App cannot see the repository, or the app is not bound to the GitHub App installation. A GitHub App installed with **Only select repositories** does not include repositories created after the install. **Fix:** Add the repository in the GitHub App settings on GitHub. Then open **Settings** > **Deploy behavior**. If the page shows **Auto-deploy is on but not connected**, select **Reconnect**. **Verify:** ```sh orchard deploy auto-deploy status ``` `enabled` is the setting you chose. `deliverable` shows whether a push can reach the app. When `deliverable` is false, the output gives the reason. ## Private submodules Orchard clones submodules when it builds. A private submodule works when all of the following are true: - It is in the same GitHub account or organization as the app's repository. - The [GitHub App](#prerequisites) can see it. - The person who linked the repository to the app can see it on GitHub, with their GitHub account connected to Orchard. Otherwise, the build stops at the clone step with an authentication error. To fix this, give that person access to the submodule, or have someone with access link the repository again. Anyone who can push to the repository can add a submodule. It can read any repository that the person who linked it can see, so limit who can push to repositories that deploy on Orchard. ## Build arguments Orchard passes the app's [variables](/run/environments/) to the build as Dockerfile build arguments. - Orchard adds the `ARG` declarations above your own `ENV` lines. An `ENV` line in the repository takes priority over a build argument of the same name. - The arguments also reach stages that build `FROM` the stage where they are declared. `DHI_USERNAME`, `DHI_TOKEN`, and `DOCKER_AUTH_CONFIG` are not build arguments. They [authenticate base image pulls](/deploy/builds/#error-401-unauthorized-when-pulling-a-base-image). ## Trigger a deploy from outside GitHub To start a deploy from a CI pipeline or another system, use a [webhook token](/run/webhooks/). ## Related resources - [Builds](/deploy/builds/) - Learn how Orchard builds images, where builds run, and how to fix common build errors. - [Deploy from GitLab, Gitea, and others](/deploy/git-providers/) - Deploy from a Git host other than GitHub. - [Roll back an app](/deploy/rollbacks/) - Return an app to an earlier release. - [Deploy from your terminal](/deploy/deploy-from-terminal/) - Build and deploy a local folder without a Git repository. - [`orchard github` reference](/reference/cli/#github) - Every flag of the `orchard github` commands.