Deploy from 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
Section titled “Prerequisites”- A GitHub App on the instance. A superadmin creates it during setup, or by following 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
Section titled “Create the app”- Open a project.
- Select New app.
- In Start from scratch, select GitHub repo.
- In Repository, select the repository.
- In Branch, select the branch.
- In Name, enter a name for the app.
- In Build with, confirm the build method. Orchard selects Dockerfile if the repository has one. Otherwise, it selects the framework it detects.
- (Optional) Expand Build and output settings to change the Dockerfile path or build stage.
- Under Environment variables, review the variables that Orchard detected.
- Under Networking, confirm the port.
- Select a reach. For the options, refer to Reach.
- Select Deploy.
Orchard opens the build progress page.
orchard deploy create --github owner/repo#main --name web --port 3000 --waitFor the build flags, refer to the CLI reference.
Detected settings
Section titled “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 file, the form shows a summary of what the file provisions.
Auto-deploy
Section titled “Auto-deploy”Auto-deploy builds and rolls out the app when you push to the selected branch.
Turn on auto-deploy
Section titled “Turn on auto-deploy”- Open the app.
- Go to Settings > Deploy behavior.
- In Auto-deploy, enter the branch in Branch.
- 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.
orchard deploy auto-deploy enable <id> --branch mainLimit builds to certain paths
Section titled “Limit builds to certain paths”Watch paths limit which pushes start a build. With an empty list, every push builds.
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.
- Go to Settings > Deploy behavior.
- In Watch paths, enter the globs.
- Select Save.
orchard deploy auto-deploy enable <id> --branch main --path 'apps/api/**' --path '!**/*.md'To clear the list, pass --path "".
Troubleshoot auto-deploy
Section titled “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:
orchard deploy auto-deploy status <id>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
Section titled “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 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
Section titled “Build arguments”Orchard passes the app’s variables to the build as Dockerfile build arguments.
- Orchard adds the
ARGdeclarations above your ownENVlines. AnENVline in the repository takes priority over a build argument of the same name. - The arguments also reach stages that build
FROMthe stage where they are declared.
DHI_USERNAME, DHI_TOKEN, and DOCKER_AUTH_CONFIG are not build arguments. They authenticate base image pulls.
Trigger a deploy from outside GitHub
Section titled “Trigger a deploy from outside GitHub”To start a deploy from a CI pipeline or another system, use a webhook token.
Related resources
Section titled “Related resources”- Builds - Learn how Orchard builds images, where builds run, and how to fix common build errors.
- Deploy from GitLab, Gitea, and others - Deploy from a Git host other than GitHub.
- Roll back an app - Return an app to an earlier release.
- Deploy from your terminal - Build and deploy a local folder without a Git repository.
orchard githubreference - Every flag of theorchard githubcommands.