Deploy from GitHub
Every push to your main branch can build a new image and roll it out with a GitHub Actions workflow. No secrets are stored in GitHub: the workflow proves which repository and branch it runs for with GitHub's OIDC token, and the controller gives it a 15-minute credential that can only deploy one application.
Set it up
Run this once from your workstation, inside the repository's checkout:
$ orch github init
Trusted acme/hello to deploy hello from branch main.
Wrote .github/workflows/deploy.yml: every push to main builds ghcr.io/acme/hello and deploys it.
Commit and push it to deploy. No secrets are needed.init reads the repository from the origin remote, the application name from
orch.pkl, and the branch from the remote's default branch. It tells the
controller to trust that repository and writes a workflow like this one:
name: deploy
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
packages: write
id-token: write
concurrency:
group: deploy-hello
cancel-in-progress: false
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: TorstenDittmann/[email protected]
with:
cluster: https://203.0.113.10:9443#sha256:3f9a…
app: hello
image: ghcr.io/acme/hellocluster is the controller address and the fingerprint of its certificate
authority. It is not a secret; the fingerprint lets the workflow refuse
anything that only pretends to be your controller. id-token: write lets the
job request its OIDC token.
| Flag | Default | Purpose |
|---|---|---|
--app |
the manifest's name |
The one application the repository may deploy |
--branch |
the remote's default branch | Only runs for this branch may deploy |
--environment |
none | Only jobs that use this GitHub environment may deploy, so its required reviewers become an approval gate |
--domain |
any | Deploys may route only this domain and its subdomains, and not the public listener; repeat for more |
--image |
see below | Image repository to build and push before deploying |
-f |
orch.pkl |
Manifest to deploy, for a repository with several |
--previews |
off | Also deploy a preview of every pull request, writing preview.yml |
--repo |
the origin remote |
OWNER/REPO when the remote is not GitHub |
--force |
off | Replace existing workflows |
When a Dockerfile sits next to the manifest and the manifest's workloads all
use one image repository, the workflow builds that image from the manifest's
directory. Without one, it deploys the manifest's images as written.
The workflow builds for the architectures of the cluster's nodes. An all-arm64
cluster builds on GitHub's ubuntu-24.04-arm runner, and a cluster that mixes
amd64 and arm64 nodes builds one image for both with platforms. Rerun
orch github init --force after adding nodes of another architecture.
orch github list shows every trusted repository. orch github untrust acme/hello --app hello stops new runs at once; a credential a run already
received expires within 15 minutes. orch github trust acme/hello --app hello
trusts a repository without a local checkout and prints the workflow instead
of writing it.
The first deploy binds the trust to GitHub's IDs for the repository and its
owner. If the repository or its owner is later renamed or deleted and someone
else takes the name, their runs are refused. Run orch github trust again
when you recreate or transfer the repository yourself.
A repository may be trusted for several applications, for example in a
monorepo. Run orch github init -f apps/api/orch.pkl for each and rename the
written workflows so they do not replace each other.
The deploy action
TorstenDittmann/orch is a GitHub Action. Each run it:
- Installs the orch CLI matching the action's version, and the Pkl version that CLI needs.
- When
imageis set, builds the image, tags it with the commit, and pushes it. It signs in toghcr.iowith the job's own token; push to another registry by adding a login step before it. - Runs
orch deploy --wait, replacing the manifest's image with the build that was just pushed, by digest.
| Input | Default | Purpose |
|---|---|---|
cluster |
required | Cluster address from orch github init |
app |
none | Application to deploy, when the repository is trusted for several |
image |
none | Image repository to build and push |
context |
. |
Docker build context |
dockerfile |
Dockerfile in the context |
Dockerfile path |
platforms |
the runner's own | Image platforms, such as linux/amd64,linux/arm64 |
file |
orch.pkl |
Manifest to deploy |
version |
the action's tag, or the latest release | orch CLI version to install |
The pushed image is available to later steps as steps.<id>.outputs.image.
On a pull_request event the action deploys the pull request's
preview instead, and steps.<id>.outputs.preview-url
holds its first URL; app is then required.
The action deploys with orch deploy --image, which replaces the image of
every service and cron job in orch.pkl that uses the same repository, so the
manifest keeps a readable tag such as ghcr.io/acme/hello:latest and never
needs editing in CI. To replace a single workload in your own step, name it:
--image web=ghcr.io/acme/hello@sha256:.... See
orch deploy.
With --wait the job stays running until the rollout is ready and fails if it
fails, times out, or rolls back, so a red commit means the deployment did not
go out.
If the image is private, give the cluster read access to it once:
printf '%s' "$GHCR_READ_TOKEN" | orch registry login ghcr.io --username USER --password-stdinStatic sites
A static service needs no image input: the
action's orch deploy packs and uploads the folder itself. If the folder is
build output rather than committed files, build it in a step before the
action:
- uses: actions/checkout@v4
- run: npm ci && npm run build
- uses: TorstenDittmann/[email protected]
with:
cluster: ...What the workflow can do
The credential can deploy, roll back, and read the status and history of its one application. It cannot read secrets, open a shell in containers, change nodes, registries or other applications, or trust more repositories. Deploying does run code you choose with that application's secrets, so protect the branch the way you would protect production.
By default the application may route any domain the cluster serves. Trust
the repository with --domain example.com to keep its deploys to
example.com and its subdomains; a deploy that names another domain, or the
public listener, is refused. Run trust or init again with the same
--domain flags, since leaving them out removes the limit.
Only runs started by push, workflow_dispatch, schedule or
repository_dispatch can deploy the application itself, and pull_request
runs only their own preview. The controller refuses
pull_request_target, workflow_run and other events that run on the
trusted branch but may build code from a pull request.
The controller needs outbound HTTPS to token.actions.githubusercontent.com
to fetch GitHub's signing keys, and GitHub-hosted runners must reach the
controller port. A cluster that runners cannot reach can deploy from a
self-hosted runner, with an SSH target from
inside its network, or by pulling new images itself with
autoUpdate while the workflow only
pushes the image.
Preview deployments
Add --previews and every pull request gets its own copy of the application:
$ orch github init --previews
Trusted acme/hello to deploy hello from branch main.
Wrote .github/workflows/deploy.yml: every push to main builds ghcr.io/acme/hello and deploys it.
Wrote .github/workflows/preview.yml: every pull request into main deploys hello-pr-N on pr-N. subdomains,
comments the URL on the pull request, and removes it when the pull request closes.
Previews get the secrets set for hello-preview: orch secret set hello-preview NAME --from-stdinpreview.yml runs the same action on pull_request events. For pull request
12 it builds the image and runs orch deploy --preview 12, which deploys:
- the application as
hello-pr-12, next tohello, never replacing it; - every domain with a
pr-12.prefix, sohello.example.combecomespr-12.hello.example.com(a wildcard*.example.combecomes*.pr-12.example.com); - one replica of each service, without autoscaling, volume and database
backups, notifications,
autoUpdate, the public HTTP listener, or public and node ports, which belong to production.
The action then comments the URL on the pull request, editing the same
comment on every push, and runs orch remove hello-pr-12 when the pull
request is merged or closed. Point a wildcard DNS record such as
*.hello.example.com at your ingress nodes so new previews need no DNS
changes; each preview gets its own certificate like any other domain.
Preview runs get a credential for their own preview only: pull request 12 can
deploy and remove hello-pr-12 and nothing else, and only when it targets the
trusted branch. It cannot touch hello, other pull requests' previews, or the
--environment gate production uses. GitHub gives no OIDC token to pull
requests from forks, so the workflow skips them. Combine --previews with
--domain to keep previews on your own domains.
Previews never see production secrets. Set the secrets they need once on
hello-preview; each deploy copies them into the preview, and databases in
the manifest get fresh passwords per preview as usual:
printf '%s' "$STRIPE_TEST_KEY" | orch secret set hello-preview stripe-api-key --from-stdinRemoving a preview stops its workloads. Its volumes stay on their node like those of any removed application.
What history shows
Deployments started from GitHub Actions record the repository, commit, branch,
actor and a link to the run. They appear in orch app history, in the TUI's
deployment details, and in the dashboard:
$ orch app history hello
7 rev_9c1… 2026-10-18T21:30:12Z SUCCEEDED current active
from acme/hello@3f9a2c1d4e5b (main) by octocat https://github.com/acme/hello/actions/runs/42
service web ghcr.io/acme/hello@sha256:…Rolling back with orch rollback works the same as for any other deployment.
Deploy with an SSH key
Without a reachable controller port, a workflow can also use an
SSH target. Store a deploy key that is allowed in the
controller's authorized_keys as ORCH_SSH_KEY and the output of
ssh-keyscan HOST as ORCH_KNOWN_HOSTS, then replace the last step with:
- name: Deploy
env:
ORCH_SSH_KEY: ${{ secrets.ORCH_SSH_KEY }}
ORCH_KNOWN_HOSTS: ${{ secrets.ORCH_KNOWN_HOSTS }}
run: |
mkdir -p ~/.ssh
printf '%s\n' "$ORCH_KNOWN_HOSTS" > ~/.ssh/known_hosts
eval "$(ssh-agent -s)"
printf '%s\n' "$ORCH_SSH_KEY" | ssh-add -
orch target add production ssh://[email protected]
orch deploy --wait --image "ghcr.io/acme/hello@${{ steps.build.outputs.digest }}"That key gives full administrator access, so prefer orch github trust
whenever runners can reach the controller.