Docs: what hosted jobs cost, size labels in runs-on, and cancelling superseded runs (#218)
* Docs: what hosted jobs cost, runner size labels in runs-on, and cancelling superseded runs
3 files changed+21−2
modifiedapps/diffinery/docs/actions/runners.md+18−0View file
| @@ -95,6 +95,24 @@ | ||
| 95 | 95 | |
| 96 | 96 | Set `runs-on: diffinery-large` to keep a job on large whatever it uses. |
| 97 | 97 | |
| 98 | +### What hosted jobs cost, and keeping it low | |
| 99 | + | |
| 100 | +A hosted runner exists only while its job runs: Diffinery starts a fresh container when the job starts and stops it when the job ends, and Cloudflare bills it by the 10 milliseconds, with no rounding up to whole minutes. Its memory and disk are billed for what the size provides, and its CPU for what the job uses. Nothing runs or bills between jobs. | |
| 101 | + | |
| 102 | +What that means for your workflows: | |
| 103 | + | |
| 104 | +- **CPU-bound jobs** (builds, test suites) are best on large, where they finish fastest; their cost follows the CPU they use, so a faster machine costs about the same per job. Automatic sizing keeps them there. | |
| 105 | +- **Jobs that wait** (deploys, API calls, polling, `sleep`) pay mostly for memory. If you know a job waits, pin a size: `runs-on: [ubuntu-latest, diffinery-small]` costs about a third of large per minute and `diffinery-tiny` about a tenth. Automatic sizing moves a job only when its own measured runs leave room to spare even on the slowest hosts. A job that checks out and then calls an API and waits typically moves to medium after its third measured run, about a third less per minute at the same speed; steps such as `actions/setup-node` or installing a CLI keep a core busy for a few seconds, which keeps a job on large. Pin a size to go further. | |
| 106 | +- **Superseded runs** keep running unless the workflow says otherwise, as on GitHub: a new push to a pull request doesn't cancel the run for the commit before it. To stop paying for runs nobody will look at, cancel them with a concurrency group per workflow and branch: | |
| 107 | + | |
| 108 | + ```yaml | |
| 109 | + concurrency: | |
| 110 | + group: ${{ github.workflow }}-${{ github.ref }} | |
| 111 | + cancel-in-progress: ${{ github.event_name == 'pull_request' }} | |
| 112 | + ``` | |
| 113 | + | |
| 114 | + This cancels a pull request's older runs when a new commit arrives, and leaves runs on your default branch (such as deploys) to finish. It isn't on by default, because cancelling a run can cut off a deploy halfway or turn an older commit's checks into "cancelled". See [concurrency](/docs/actions/workflow-syntax#concurrency). | |
| 115 | + | |
| 98 | 116 | ### The Ubuntu 24.04 image |
| 99 | 117 | |
| 100 | 118 | The hosted image is built from `containers/runner/Dockerfile` in the Diffinery source. It is deliberately small. This is the complete list of what is preinstalled: |
modifiedapps/diffinery/docs/actions/workflow-syntax.md+2−2View file
| @@ -237,7 +237,7 @@ | ||
| 237 | 237 | | `name` | Supported | Display name. May use `matrix`; evaluated for each matrix combination. | |
| 238 | 238 | | `needs` | Supported | Jobs that must finish first. | |
| 239 | 239 | | `if` | Supported | Condition evaluated before the job starts. | |
| 240 | -| `runs-on` | Supported | Hosted Linux labels or self-hosted labels. May use `matrix`; evaluated for each matrix combination. `group` is ignored. | | |
| 240 | +| `runs-on` | Supported | Hosted Linux labels or self-hosted labels, plus `diffinery-large`, `-medium`, `-small` or `-tiny` to pick a hosted [runner size](/docs/actions/runners#runner-sizes). May use `matrix`; evaluated for each matrix combination. `group` is ignored. | | |
| 241 | 241 | | `environment` | Supported | The deployment environment: its branch policy, required reviewers, wait timer, secrets and variables apply, and a deployment is recorded. See [environment](#environment). | |
| 242 | 242 | | `outputs` | Supported | Values passed to dependent jobs through `needs`. | |
| 243 | 243 | | `env` | Supported | Environment variables for every step of the job. | |
| @@ -322,7 +322,7 @@ | ||
| 322 | 322 | |
| 323 | 323 | | Labels | Where the job runs | |
| 324 | 324 | | --- | --- | |
| 325 | -| Only labels matching `ubuntu-*`, `linux`, `diffinery`, `diffinery-*`, `x64` or `amd64` (case-insensitive) | A Diffinery-hosted Linux container (Ubuntu 24.04, x64). `ubuntu-latest`, `ubuntu-22.04` and `ubuntu-24.04` all get the same image. | | |
| 325 | +| Only labels matching `ubuntu-*`, `linux`, `diffinery`, `diffinery-*`, `x64` or `amd64` (case-insensitive) | A Diffinery-hosted Linux container (Ubuntu 24.04, x64). `ubuntu-latest`, `ubuntu-22.04` and `ubuntu-24.04` all get the same image. `diffinery-large`, `diffinery-medium`, `diffinery-small` or `diffinery-tiny` picks its size; without one, the job's own earlier runs pick it. See [Runner sizes](/docs/actions/runners#runner-sizes). | | |
| 326 | 326 | | Any list that includes `self-hosted` | A self-hosted runner whose labels include every label in the list. See [Runners](/docs/actions/runners). | |
| 327 | 327 | | Anything else (for example `windows-latest` or `macos-14` without `self-hosted`) | Nowhere. The job fails with `No Diffinery runner matches runs-on: <labels>. Linux (ubuntu-*) runners are hosted; anything else needs runs-on: [self-hosted, ...] and a registered runner.` | |
| 328 | 328 |
modifiedapps/diffinery/docs/migrate-from-github.md+1−0View file
| @@ -816,6 +816,7 @@ | ||
| 816 | 816 | |
| 817 | 817 | | If a workflow... | Do this on Diffinery | |
| 818 | 818 | | --- | --- | |
| 819 | +| Has jobs that mostly wait (deploys, API calls, polling), or runs on every push | They run as they are. To spend less hosted runner time, pin a smaller size for waiting jobs (`runs-on: [ubuntu-latest, diffinery-small]`) and cancel superseded pull request runs with a `concurrency` group. See [What hosted jobs cost](/docs/actions/runners#what-hosted-jobs-cost-and-keeping-it-low). | | |
| 819 | 820 | | Uses `runs-on: windows-*` or `macos-*` | Diffinery has no Windows or macOS hosted runners: Cloudflare Containers run Linux only. Run the job on a self-hosted runner (`diffinery runner`). See [Runners](/docs/actions/runners). | |
| 820 | 821 | | Uses `actions/github-script` | Works with the REST API (`github.rest.*`) and the job's token. `github.graphql` doesn't: the job's token can't use Diffinery's [GraphQL API](/docs/reference/graphql-api) yet. | |
| 821 | 822 | | Relies on `GITHUB_TOKEN` writing (comments, labels, statuses, releases, pushes) without a `permissions:` block | Repositories created on Diffinery, imported ones included, give the job token GitHub's restricted default, `contents` and `packages` read. Add a `permissions:` block (for example `contents: write`, `issues: write`, `pull-requests: write`) to the workflow or job, or have an admin set the repository default to write. Each endpoint needs its permission, as on GitHub; a missing one gets `403 Resource not accessible by integration`. See [Workflow permissions](/docs/actions/workflow-permissions). | |