Skip to content
Install

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.

  • 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.

  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.
  12. Select Deploy.

Orchard opens the build progress page.

Orchard reads the repository and fills in the form.

FieldDetected from
Build withA Dockerfile, or framework detection when no Dockerfile exists
DockerfileThe file Orchard found
StageThe stages in the Dockerfile. The default is Final stage.
PortEXPOSE, or the default port of the framework
Environment variablesENV 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 builds and rolls out the app when you push to the selected branch.

  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.

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.

  1. Go to Settings > Deploy behavior.
  2. In Watch paths, enter the globs.
  3. Select Save.

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.

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.

Orchard passes the app’s variables 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.

To start a deploy from a CI pipeline or another system, use a webhook token.