Skip to content

Where builds run

Ployz builds your app on your own servers, or on GitHub Actions in your app's repository. Your organization's build order says which one a build tries first. If it can't take the build, the next one does.

Out of the box, builds run on your servers. Add one workflow file to a repository and its builds move to GitHub Actions, which takes the load off your servers.

Every server runs builds unless you turn it off.

  1. Go to Servers and open a server.
  2. Under Builds, turn Run builds here on or off.
  3. Set Builds at once to how many builds it may run together.

A server's page: Run builds here and Builds at once

Ployz prefers the server that built the service last, because its cache makes builds faster. A build that has started on a server stays there: if it fails, the deploy fails. If your servers mix x86 and ARM, see When your servers mix x86 and ARM.

Builds run on GitHub's runners, in the service's repository, and count towards that repository's Actions minutes. Each repository needs one workflow file; you don't add any secrets. The GitHub Actions section appears once a service builds from a repository through the Ployz GitHub App.

  1. Go to Organization → Builds.
  2. Under GitHub Actions, click Add workflow ↗ next to the repository. GitHub opens the file, already filled in.
  3. Commit it to the repository's default branch, even if your service deploys another Git branch.

The repository shows Waiting for commit, then a check mark. If it shows Installation lacks permission, approve Actions: Read and write for the Ployz GitHub App in GitHub.

A repository that shows Uses an older workflow has a different file, such as one that calls getployz/build@v1. Click Update workflow, copy the file, then Open in GitHub ↗ and replace yours with it. The new file runs the builder at a fixed commit, so a change to the builder can't reach your builds until Ployz offers a new file.

The workflow file
name: Ployz build
on:
  workflow_dispatch:
    inputs:
      build: { required: true, type: string }
      cloud: { required: true, type: string }
      runner: { required: false, type: string, default: ubuntu-latest }
permissions:
  contents: read
  id-token: write
jobs:
  build:
    runs-on: ${{ inputs.runner }}
    steps:
      - uses: getployz/build@39e1f488e492c0641e520777e481e8f5b266985b
        with:
          build: ${{ inputs.build }}
          cloud: ${{ inputs.cloud }}

When GitHub can't take a build, the build log says why, and the next builder takes it:

  • The workflow is missing, disabled or not on the default branch, or the repository shows Installation lacks permission. Fix it in GitHub, as above.
  • The workflow file on the default branch isn't the one Ployz offers, on hosted Ployz Cloud. It runs only that exact file, whatever its line endings. Replace yours with the file above. A Self-hosted Cloud runs the file you have.
  • The service deploys a public repository without the GitHub App, or runs on both x86 and ARM servers. These build on your servers. With GitHub only, they fail, so keep your servers in the order for them.
  • You deployed with ployz up. Uploads always build on your servers.

A build log: GitHub skipped, then Building on ployz-prod-1

  1. Go to Organization → Builds.
  2. Pick an order under Where builds run. Only an owner or admin, or Ployz support, can change it. For a member it is disabled and says so.

Organization → Builds: Where builds run, and the servers that run builds

OrderWhat happens
GitHub, then your serversThe default. GitHub first when the repository has the workflow, otherwise your servers.
Your servers, then GitHubYour servers first. GitHub only when none of your servers runs builds.
Your servers onlyNever GitHub, unless a service prefers GitHub Actions.
GitHub onlyOnly GitHub, and a build waits for a GitHub runner however long that takes. Uploads from ployz up still build on your servers, and a service that prefers one of your servers builds on your servers while any of them runs builds.
  1. Open the service and go to Settings → Build.
  2. Set Preferred Builder to GitHub Actions or one of your servers.

Settings → Build: Build method, Build command and Preferred Builder

From the CLI or an agent, give github, or the server's name as ployz server ls lists it, or its ID. Any member can give a name, and --patch takes one too. Ployz saves the server's ID. A name two servers share is refused with both IDs, so give the ID instead:

ployz set web.preferredBuilder=machine-1
ployz set web --patch '{"preferredBuilder":"machine-1"}'

The service tries that builder first, then follows the build order. A service that prefers a server builds on your servers, even with GitHub only, as long as one of them runs builds. It goes to GitHub only when none of them does. If the preferred server is gone or doesn't run builds, another of your servers takes the build. Auto follows the build order alone. Preferred Builder applies at once, from the next build.

A deploy names the server each service built on. When GitHub came first and couldn't take the build, for example because the repository has no Ployz build workflow, the deploy says so and why.

Builds on servers that enforce device approval

Section titled “Builds on servers that enforce device approval”

A build runs steps from your repository and opens your service's sealed values. A server with device enforcement on refuses a build Ployz Cloud starts, so Ployz Cloud can't run steps of its choosing there. The deployment fails with:

No eligible Build Machine was selected; no build was started: Server web-1 (…): This server runs only builds an approved device starts.

This covers builds on your servers, builds on GitHub Actions, and builds in a preview. A GitHub build checks in, is refused, and moves to your servers, which refuse it too, so the deploy stops before anything changes. A build an approved device starts over its own connection still runs. A build already under way when you turn enforcement on can't start another request for sealed values or another image push, though a request it started before then may still finish.

A build moves to the next builder when a builder can't take it, or when a GitHub run ends early for reasons outside your code, such as running out of time or pushing no image. If a build step fails, on GitHub or on your servers, the build fails: moving it wouldn't fix your code. Either way, the deploy stops before anything changes.

When no builder can take a build, it fails with one of these:

  • No eligible Build Machine was selected; no build was started. Your servers were last in the order and none could take it. Turn on Run builds here on an online server, or pick an order that ends with GitHub.
  • …No other Builder in your Build Order can take it. GitHub was last and couldn't take it. The build log says why GitHub was skipped. Fix that, or pick an order that ends with your servers.

See Troubleshooting builds for failed build steps.