# Deploy from GitHub > Connect a repository, deploy on every push, wait for CI, and deploy only what changed. For agents: [llms.txt](https://ployz.dev/llms.txt) indexes the Ployz docs as Markdown. Connect a GitHub repository to a service and Ployz builds and deploys it each time you push to its Git branch. [How builds work](https://ployz.dev/docs/builds/overview) covers what happens in between. ## Add a service from a repository 1. Go to **Projects**, click **New project** and choose **GitHub repository**. (To add it to a project you already have, click **Create** on that project's canvas instead.) The first time, click **Connect GitHub**, pick the account or organization, choose the repositories Ployz may use, and install the Ployz GitHub App. GitHub sends you back to **Organization → GitHub**, which lists the account. It says "Repositories appear in a moment" until Ployz has listed them. If the app is already installed on that account, for another Ployz organization, click **Use existing** instead. 2. Search for the repository, or paste its URL, and pick it. 3. Before you deploy, set what your app needs to start: - To make it public, open **Settings → Networking** and click [**Generate Domain**](https://ployz.dev/docs/services/domains#generate-a-domain). Enter its port in **Port** if your app doesn't listen on `PORT`. - If it needs [variables](https://ployz.dev/docs/services/variables) or a [database](https://ployz.dev/docs/services/databases) to start, add them now. - For one app of a monorepo, set its [root directory](#deploy-a-monorepo) under **Source**. 4. Click **Deploy** in the bottom bar. ![The GitHub Repository picker before GitHub is connected, with a public repository's URL typed](https://raw.githubusercontent.com/getployz/ployz/main/docs/user/images/service-source-github.png) The service is named after the repository and follows its default Git branch. The GitHub App reads your code, pull requests and checks, and can't push code. The repository list groups repositories by GitHub account. To give Ployz more repositories later, choose **Add from GitHub** below the repository list. GitHub opens in a new window, and the new repositories appear in the list when you come back. ## Deploy a public repository without the app In the repository list, type `owner/repo` or paste the repository's URL, choose **Deploy owner/repo**, then deploy. Without the app, Ployz never hears about pushes: no deploy on push, no **Wait for CI**, and no [builds on GitHub Actions](https://ployz.dev/docs/builds/where-builds-run#build-on-github-actions). Install the app on the repository to get them. Until then, shipping a new commit is CLI-only for now, because the dashboard's **Deploy** needs a staged change: ```sh # Builds and deploys the newest commit on the service's Git branch ployz deploy ``` **Auto-deploy** and **Wait for CI** keep their values on such a service, so they work as soon as the app is installed. Until then, the dashboard shows a line under **Auto-deploy**, and `ployz get` and `ployz set` print the same note: ```text $ ployz set web.waitForCi=true Applied web.waitForCi in shop/production. Pushes reach Ployz only once the GitHub App is installed on owner/repo. ``` ## Choose the Git branch 1. Open the service and go to **Settings → Source**. 2. Next to **Branch**, click the pencil and pick a Git branch. For a public repository, type its name. 3. Deploy the change. ![A service's Source settings: repository, Branch, Root directory, Auto-deploy and Wait for CI](https://raw.githubusercontent.com/getployz/ployz/main/docs/user/images/service-settings-source.png) Each environment has its own settings, so production can follow `main` while staging follows `develop`. See [Environments and branches](https://ployz.dev/docs/environments/environments). ### Protected environments In a [Protected environment](https://ployz.dev/docs/environments/environments#protect-an-environment), only an owner or admin can connect a repository or change the branch. Merging into that branch still deploys: Ployz doesn't decide who can merge. Use [GitHub branch protection](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) on the branch to require reviews before a merge. The **Ployz · ready to merge** check on a pull request into that branch adds a line like **Merging deploys to production, a Protected Environment.** The line is informational: it never changes whether the check passes. ## Deploy on push **Auto-deploy** is on for every new service. Each push to the service's Git branch deploys it, in every environment that follows that Git branch. Turn **Auto-deploy** off under **Settings → Source** to deploy only when you choose. It applies at once, with no deploy. A push deploys like **Deploy**: it ships every change you [saved](https://ployz.dev/docs/deploy/deployments#deploy-your-changes) in the environment, and staged changes you haven't saved stay behind. The services that follow its repository and Git branch, have **Auto-deploy** on and match their [watch paths](#deploy-only-when-certain-files-change) build the new commit. Every other service keeps the commit it last built, and one with nothing new to ship keeps running as it is. A volume deletion you confirmed when you saved goes out with the push without asking again. If the data changed since, the push keeps it and your next deploy asks; see [Confirm a deploy that deletes data](https://ployz.dev/docs/deploy/deployments#confirm-a-deploy-that-deletes-data). ### Deploy on push to servers that enforce device approval Servers with [device enforcement](https://ployz.dev/docs/servers/manage-servers#require-a-devices-signature-for-restarts-and-joins) on deploy a push only under an automatic deploy rule you approve with your passkey or an approved device. A browser session can't approve one: the rule stands for every future push, so each approval is its own passkey prompt. In the dashboard, open the environment's **Settings** and turn on **Deploy every push** under **Automatic deploys**. The dialog shows the repository and branch, the builder, the servers and each service's settings. **Approve with passkey** asks your passkey once. The rule covers every service that builds from GitHub. If they build from different branches, it keeps the services on the branch the rule already covers. From the CLI, approve it for the services that build from one branch: ```bash ployz github rule approve web worker ``` It prints what you approve, then signs it with your device key: ```text Approving automatic deploys for production: repository acme/web on main workflow .github/workflows/ployz-build.yml, on push and on rebuilds you approve builder getployz/build/.github/workflows/build.yml@39e1f488e492c0641e520777e481e8f5b266985b servers 2 in the cluster web builds Dockerfile Dockerfile, context ., platforms linux/amd64, with the Actions cache, build args LOG_LEVEL=info, build secrets DATABASE_URL variables DATABASE_URL (sealed), LOG_LEVEL=info command ["node server.js"] Approved. Every push to main now deploys web, worker with these settings. ``` It lists every setting the rule pins that isn't Ployz's default, including the start command and how GitHub builds each service, so read them before you rely on it. A value with anything but letters, digits and `-_./:@+` shows in double quotes, with line breaks and other control characters escaped, so `X="a, Y=b"` is one build arg and `X=a, Y=b` is two. To pin your own fork of the builder, add `--builder /build/.github/workflows/build.yml@` and `--builder-sha `. From then on every push to that branch deploys with no prompt, force pushes included. GitHub Actions builds it with Ployz's pinned builder, and each server checks that the image is the one built for the branch's current head, under these settings. The repository needs Ployz's rule workflow as `.github/workflows/ployz-build.yml` on the rule's branch. **Organization → Builds** offers it for each repository a rule builds from: **Add workflow** and **Update workflow** show the file and open GitHub to commit it. It builds on every push to a branch, and on a dispatch with a `commit` for a [rollback that builds again](https://ployz.dev/docs/deploy/history-and-rollback#roll-back-on-servers-that-enforce-device-approval). Commit it exactly as Ployz gives it: ```yaml name: Ployz build on: push: branches: ['**'] workflow_dispatch: inputs: cloud: { required: false, type: string } commit: { required: false, type: string } permissions: contents: read id-token: write jobs: build: if: github.event_name != 'push' || vars.PLOYZ_BRANCH == '' || github.ref_name == vars.PLOYZ_BRANCH uses: getployz/build/.github/workflows/build.yml@39e1f488e492c0641e520777e481e8f5b266985b with: cloud: ${{ inputs.cloud || vars.PLOYZ_CLOUD || 'https://ployz.dev' }} commit: ${{ inputs.commit }} ``` Nothing in it names your branch or your Ployz Cloud, so commit it unchanged: hosted Ployz Cloud dispatches a rebuild only with this exact file, and **Builds** reads any other as **Uses an older workflow**. Each server checks that a push was to the rule's branch. To skip pushes to other branches, set the repository variable `PLOYZ_BRANCH` to the rule's branch, such as `main`, as the dialog names it, in the repository's **Settings → Secrets and variables → Actions → Variables**. Leave it unset if the repository also has a [preview rule](https://ployz.dev/docs/environments/preview-environments). A self-hosted Ployz Cloud sets `PLOYZ_CLOUD` there to its own address, such as `https://ployz.example.com`. A repository with this file builds on GitHub only under its rules: a deploy of another environment from it builds on your servers. - **A saved change waits for you.** After you save a change to a service the rule covers, its settings or how it builds, or add a service that builds from the rule's branch, pushes don't deploy it until you approve the rule again. Settings shows **Pushes to main are on hold** with what changed; **Review and approve** names each changed setting and asks your passkey once. From the CLI, `ployz github rule approve web` names what changed, as `changed web since the last approval`. A push that changes only the code deploys as before, and so does a new replica count. - **A new server waits too.** The rule names the servers it was approved for. Approve it again after you [add a server](https://ployz.dev/docs/servers/add-a-server). - **Stop it** by turning off **Deploy every push**, or with `ployz github rule end`. Pushes no longer deploy on those servers. - **Roll back from your device.** A rule deploys only the branch's head. To ship an older commit, redeploy it with `ployz deployment redeploy`; see [Roll back on servers that enforce device approval](https://ployz.dev/docs/deploy/history-and-rollback#roll-back-on-servers-that-enforce-device-approval). A rule approved before Ployz 0.4 runs only on push. Approve it again before a rollback that needs a rebuild. - **Someone who can push to the branch can deploy.** Ployz Cloud can't swap the commit, the image or the settings, but its GitHub App can push a commit to the branch itself. Add a branch ruleset on GitHub that blocks direct pushes to the branch. ## Wait for CI Turn on **Wait for CI** under **Settings → Source** to hold a push's deploy until its GitHub checks pass, from GitHub Actions or any other app that reports checks. It applies at once. A held push shows in **Runs** and in `ployz deployment ls` as a deployment that reads **Waiting for CI**, named by its commit rather than a number. It deploys as that same deployment once every check passes, and takes the next deployment number then, so deployments stay numbered in the order they ran, whichever branch passed CI first. Cancel it there to drop the push. Nothing was frozen for it, so it can't be redeployed: push again instead. - If a check fails, the deployment reads **CI failed** and the commit doesn't deploy. Re-run the check on GitHub and the commit deploys once it passes, or push a fix. - A newer push replaces a commit that's still waiting, and so does a deploy you start yourself. A replaced commit leaves the list; one you cancelled stays, so you can see you dropped it. - If no checks run for a commit, it waits until your next push. CI that reports commit statuses instead of checks counts as no checks. ## Deploy only when certain files change **Watch paths** limit auto-deploys to pushes that change files you list. Under **Settings → Source → Watch paths**, type a pattern and click **Add**. Patterns work like `.gitignore` and start at the root of the repository, whatever the service's root directory is. They apply at once. | Pattern | Matches | | --- | --- | | `apps/web/**` | everything under `apps/web` | | `*.md` | Markdown files in any folder | | `/README.md` | only the README at the root | | `!**/*.md` | leaves out Markdown files an earlier pattern matched | Without watch paths, any change deploys. A force push, the first push Ployz sees on a Git branch, or a push that changes 300 files or more deploys every service on the Git branch, whatever their watch paths. ## Deploy a monorepo Add one service per app from the same repository, and give each its own root directory and watch paths before you deploy it. For a repository with `apps/web` and `apps/worker`: | Service | Root directory | Watch paths | | --- | --- | --- | | `web` | `/apps/web` | `apps/web/**` | | `worker` | `/apps/worker` | `apps/worker/**` | To set the root directory, open **Settings → Source**, click **Root directory** and enter the folder, starting with `/`. The build sees nothing outside that folder, and a Dockerfile path is relative to it. If an app imports code from elsewhere in the repository, like a shared package in a pnpm or npm workspace, leave the root directory at `/`. Set a [build command](https://ployz.dev/docs/builds/railpack-and-dockerfiles#change-the-build-and-start-commands) and [**Start command**](https://ployz.dev/docs/services/settings#start-command) for that app instead, such as `pnpm --filter web build`, and add the shared folder to its watch paths. ## Who owns the connection A GitHub installation belongs to the organization it is connected to, not to the person who installed it. Everyone in the organization can pick its repositories, and it stays connected when that person leaves. **Organization → GitHub** lists each connected account with its repositories, who connected it, and when. Only an owner or admin can connect or disconnect one; members see the list. One installation can be connected to more than one organization. To connect one you already installed, click **Use existing** in the repository picker or in **Organization → GitHub** of the other organization. Ployz connects only GitHub accounts you own: your own user account, or a GitHub organization where you are an owner. Collaborating on one of its repositories is not enough. When you own several new ones, Ployz asks which to connect. To stop an organization from using an account, click **Disconnect** on its row, or run `ployz github ls` and then `ployz github disconnect `. Builds that organization has in flight on GitHub through that account stop, and their deploys fail with "GitHub account `` was disconnected". Other organizations connected to the same installation keep it, and the app stays installed on GitHub. To uninstall it, use **Uninstall on GitHub** after you disconnect. Suspending the app on GitHub hides its repositories from every organization until you unsuspend it; the connections stay. Uninstalling the app on GitHub removes it from every organization at once. Either way, builds in flight through it stop within seconds, and their deploys fail with "GitHub account `` was suspended" or "was disconnected". ## Read a repository from the CLI To see what's in a repository before you deploy it, list its files and read one. Both work on any repository the Ployz GitHub App can read, and on public repositories. ```sh # Every file on the default branch ployz github tree acme/web # Only files under apps/web, on the dev branch ployz github tree acme/web apps/web --ref dev # Only files whose path matches a glob ployz github tree acme/web --match '**/Dockerfile' # The text of one file ployz github cat acme/web apps/web/package.json ``` `--match` matches the whole path from the top of the repository, so `*.toml` finds only files at the top, and `**/*.toml` finds them in every folder. Quote the glob so your shell doesn't expand it. A listing stops at 500 files. When it's cut short, name a folder or a narrower `--match` to see the rest. A folder or file the repository doesn't have fails with `No path` and exit code 1. `github cat` says `No file` for a missing file, also with exit code 1. `github cat` prints text files up to 64 KiB. For a larger file or a binary one, it says so instead of printing it. Pass `--ref` to read a branch, tag or commit other than the default. ## Good to know - **Every deploy ships the newest commit.** Clicking **Deploy** to apply a setting also picks up whatever is on the service's Git branch now. - **Servers that enforce device approval deploy a push only under a rule.** Without one, the deployment fails at its build and nothing changes. See [Deploy on push to servers that enforce device approval](#deploy-on-push-to-servers-that-enforce-device-approval). - **Changing a variable rebuilds your app.** See [How builds work](https://ployz.dev/docs/builds/overview#good-to-know). - **Only the service's Git branch deploys.** Pull requests can get their own [preview environments](https://ployz.dev/docs/environments/preview-environments) instead. - **Merging a pull request brings its preview's setting changes.** Its code deploys like any push, and the changes its [preview](https://ployz.dev/docs/environments/preview-environments) made land in production as one saved change, **Merged #146**, that deploys with the merge. The pull request's **Ployz · ready to merge** check lists those changes first. It's informational: green, or neutral when something needs a look, and never failing. Next: [give your app its variables](https://ployz.dev/docs/services/variables).