Pipeline settings
Default workflow, per-workflow settings, health, triggers, schedules, concurrency, timeout, approval, and size budget fields on a pipeline, with their UI labels, API fields, and limits.
These settings live on the pipeline, not in the repository. The pipeline’s
Edit page sets most of them, under Default workflow, Triggers and
Size budget, and
Update a pipeline sets the same fields
through the API. A commit cannot change them, except that a .oore.yaml
version 2 file can replace the events, as described in
Triggers in version 2.
| UI label | API field |
|---|---|
| Default workflow | workflow |
| Events | trigger_config.events |
| Branch patterns (optional) | trigger_config.branches |
| Tag patterns (optional) | trigger_config.tags |
| Only these paths (optional) | trigger_config.paths |
| Ignore these paths (optional) | trigger_config.paths_ignore |
| Schedules | trigger_config.schedules |
| Max concurrent builds (optional) | concurrency.max_concurrent |
| Timeout (minutes) | timeout_minutes |
| Builds wait for a maintainer before a runner picks them up | approval.required |
| Which builds | approval.events |
| Size budget rules | size_budget.rules |
| When an artifact is over budget | size_budget.mode |
Per-workflow settings live on the pipeline’s Workflows tab and have their own API; see Workflow settings. Health is read-only; see Health.
Default workflow
workflow names the .oore.yaml version 2 workflow the pipeline runs when a
build names none. null, shown as Not set, leaves the choice to each run.
| A build | With a default workflow | Without one |
|---|---|---|
| Started by hand or the API | Runs the workflow it names, else the default | Runs the workflow it names, else the file’s only workflow. Several workflows and none named: refused with invalid_workflow |
| Started by a push, pull request or tag | Runs the default if the event matches its on; without one, the top-level on; without either, the trigger settings | One build per workflow whose on matches, or whose trigger settings match when neither it nor the top level sets on |
The Default workflow selector lists the workflows in the pipeline’s file
on the app’s default branch, and names that branch beneath it. Select
Change branch to read the file from another branch, for example while the
file is only on develop. The branch changes only what the selector shows;
builds read the file at the commit they build.
When the file on the default branch no longer defines the default workflow, the pipeline’s health is Workflow missing, and builds that fall back to it fail.
Workflow settings
Each workflow of the pipeline’s file can have settings that replace, for this pipeline only, what the file and the pipeline would otherwise decide. Open the pipeline’s Workflows tab and select Settings on a row. The table shows every workflow in the file, what it builds, signs with and publishes, and its approval.
| UI label | API field | Value |
|---|---|---|
| Android signing | android_identity_id | An Android keystore from the app’s signing library. Replaces the file’s signing.android |
| iOS signing | ios_identity_id | An iOS distribution identity from the library. Replaces the file’s signing.ios, and with it the iOS export method |
| Publishing | publish_enabled | false stops every store upload of the workflow, whatever the file and the Publishing tab say. Unset follows them |
| Approval | approval_required | true holds every build of the workflow for approval and false none, whatever its event. Unset follows the pipeline’s approval |
- List workflow settings:
GET /v1/pipelines/{pipeline_id}/workflow-settings. - Update workflow settings:
PUT /v1/pipelines/{pipeline_id}/workflow-settings/{workflow}. The request replaces the workflow’s settings, so a field left out is cleared. An empty request removes them. - Changing
approval_requiredneeds the same role as changing the pipeline’s approval policy. The other fields need app developer access or higher. - An identity must belong to the pipeline’s app and be of the field’s kind.
- A workflow whose settings pick an ad hoc iOS identity, and that uploads to
App Store Connect with publishing on, is refused with
invalid_signing. - An identity a workflow’s settings pick cannot be deleted from the library.
- Settings stay when a workflow is removed from the file, and the table marks the row Not in the file. They apply again if the workflow comes back.
Each build records the identities and publish choice it was created with, so a later change applies to new builds only.
Health
health on a pipeline says whether its file is usable on the app’s
default branch. Oore reads it from the files it last saw on that branch,
never from GitHub or GitLab while a page loads, and leaves it out until it has
read the repository once.
health.state | UI label | Meaning |
|---|---|---|
ok | File OK | The file exists and parses, and defines the default workflow when the pipeline has one |
file_missing | No file | No file at the config path, so builds use the settings saved in Oore |
file_invalid | Invalid file | The file exists but does not parse or validate; builds of this pipeline fail |
workflow_missing | Workflow missing | The file no longer defines the pipeline’s default workflow; builds that fall back to it fail |
| Field | Value |
|---|---|
message | What is wrong, in one line. Absent for ok |
path | The file read. It differs from config_path when .oore.yml stands in for .oore.yaml |
branch | The branch read |
commit_sha | The commit read |
checked_at | When Oore last read the branch, in Unix seconds |
When Oore reads the branch is described in Add pipelines from the repository.
Events
trigger_config.events lists the source events that start a build:
| Value | UI label | Starts a build when |
|---|---|---|
push | Push | A branch receives a push |
pull_request | Pull request | A pull or merge request is opened, reopened or updated |
tag_push | Tag push | A tag is pushed |
An empty list accepts every event. Source events need an app connected to GitHub or GitLab. An app that builds a repository on the Oore Mac builds only from the UI, the API, or a schedule. GitLab sends tag pushes only when the app webhook has Tag push events turned on.
You can always start a build by hand, whatever the events are.
Branch and tag patterns
trigger_config.branches filters push and pull request events by branch.
trigger_config.tags filters tag pushes by tag name. Both take globs such as
release/* or v*.
| Set | Result |
|---|---|
| Neither list | Every branch and every tag can start a build |
Only branches | Tag pushes do not start builds |
Only tags | Branch pushes and pull requests do not start builds |
| Both lists | Each list filters its own events |
A tag build records tag_push as its event and the tag as its ref.
Changed paths
trigger_config.paths starts a push or pull request build only when a changed
file matches one of its globs. trigger_config.paths_ignore skips the build
when every changed file matches one of its globs.
| Pattern | Matches |
|---|---|
* and ? | Characters within one path segment |
** | Any number of segments |
*.md | A file name anywhere, because it has no / |
lib/ | Everything below lib, because it ends in / |
Oore reads the changed files of a push from the webhook. For a pull request, it asks GitHub or GitLab for the files changed since the merge base. When the change set is unknown, such as for a very large push or after a provider error, Oore builds instead of skipping. Path filters do not apply to tag pushes.
Schedules
trigger_config.schedules starts builds on a cron schedule in UTC:
{
"schedules": [
{ "cron": "0 2 * * 1-5", "branch": "main" },
{ "cron": "@weekly" }
]
}| Field | Value |
|---|---|
cron | Five fields: minute, hour, day of month, month, day of week (0 or 7 is Sunday) |
branch | Branch to build. Without it, the app’s default branch at its current commit |
- Lists (
1,15), ranges (9-17), and steps (*/15) work in every field. @hourly,@daily,@weekly,@monthly, and@yearlywork in place of the five fields.- A pipeline can have up to 10 schedules.
- A new or edited schedule starts counting from when Oore first sees it.
- When the daemon was down at a due time, Oore still starts the run if it is less than five minutes late. Older runs are skipped.
Max concurrent builds
concurrency.max_concurrent caps how many of the pipeline’s builds run at
once.
| Property | Value |
|---|---|
| Range | 1 to 100 |
| Default | No limit (null) |
- Builds that are claimed by a runner, assigned or running count against the limit.
- A build over the limit stays Queued. When a running build finishes, the oldest queued build of the pipeline starts next.
- A pipeline at its limit does not hold up other pipelines’ builds; a free runner takes the oldest build it can run.
- A lower limit does not stop builds that are already running.
- Without a limit, the pipeline runs as many builds at once as there are free runners that match.
Timeout
timeout_minutes is how long a running build may take.
| Property | Value |
|---|---|
| Range | 1 to 1440 minutes (24 hours) |
| Default | 60 |
Oore marks a build timed_out within about 15 seconds of reaching the
timeout, and the runner stops the job. A build keeps the timeout it was created
with. A re-run uses the pipeline’s current timeout.
Approval
approval holds new builds until an app maintainer approves them:
{
"approval": {
"required": true,
"events": ["schedule"],
"expires_after_hours": 24
}
}| Field | Value |
|---|---|
required | true holds matching builds |
events | push, pull_request, tag_push, manual, schedule. Empty holds every build |
expires_after_hours | 1 to 8760. Default 168 (7 days) |
- A build that nobody approves or rejects within
expires_after_hoursis canceled with the reason “approval request expired”. - A re-run of a held build is held again.
- A waiting build that is canceled or superseded stops waiting.
- For an app that builds a repository on the Oore Mac, Which builds offers only Manual and Schedule.
- Only app maintainers, instance admins, and the instance owner can change
approval. Developers see it read-only.
Size budget
size_budget limits each kind of artifact on the pipeline’s commit checks. It
never fails the build itself, and it does not change artifacts or releases.
{
"size_budget": {
"mode": "fail",
"rules": [
{ "kind": "aab", "max_bytes": 157286400, "max_increase_percent": 5 }
]
}
}| Field | UI label | Value |
|---|---|---|
kind | Kind | Lowercase file extension, such as aab, apk or ipa |
max_bytes | Max size (MB) | Largest size allowed |
max_increase_bytes | Max increase (MB) | Largest growth allowed compared with the baseline |
max_increase_percent | Max increase (%) | Largest growth allowed compared with the baseline, in percent |
- A rule needs at least one limit. A pipeline can have up to 20 rules. Empty
rulesturns the budget off. - The UI shows sizes in binary units, like the rest of Oore: 1 MB is 1,048,576 bytes. The API takes bytes.
- Every artifact of the rule’s kind on a check’s platform must stay within every limit the rule sets.
- An artifact that Oore cannot tie to a platform, such as a
.zip, counts against every check of the build. - When the build has no baseline, or an artifact has no match in it, only
max_bytesapplies, and the check summary says so. - Any growth from a 0-byte baseline is over a percent limit.
- The budget applies when a build reports its result, so a change shows on the next build or re-run.
size_budgetis a floor. When the.oore.yamlversion 2 file a build ran setsbudgetson a target, that platform’s check is held to both, and the summary names the budget each artifact went over. The check fails when any budget it went over hasmode: fail. A file cannot loosen or turn offsize_budget.
Modes
mode | UI label | An artifact over budget |
|---|---|---|
fail | Fail the check | The GitHub check concludes failure and lists each artifact, the limit it went over, and its size or change. The GitLab commit status fails and names the first artifact |
warn | Warn on the check and keep its result | The check keeps its result. The GitHub summary shows a warning with the same table, and the GitLab status description mentions it |
If Oore cannot load the sizes, the check keeps the build’s result and its summary says the size budget could not be checked.
Baseline
The size comparison and the increase limits use the same baseline: the latest earlier successful build of the same pipeline on the base branch.
- For a pull request, the base branch is the request’s target branch.
- For a push, it is the app’s default branch, so a build on the default branch compares with the one before it.
- Builds of the same commit are skipped, so a re-run never compares with itself.
- Oore records sizes when an upload finishes and keeps them after retention deletes the files, so an old baseline still compares.
- The analyzer counts compare the same way, with the latest such build that reported an analysis.
Artifacts pair up by file name. When the name changes between builds, such as
when it carries a version, an artifact pairs with the only file of the same
kind in the baseline build, such as the only .aab. Split APKs pair by name
only.