`.oore.yaml` version 2
Workflows, targets with full build commands, named steps, and vars, secrets and flavor references.
version: 2 describes a pipeline as an app, the targets it builds, the named
steps around those builds, and the inputs they read. Each target’s build is
the complete command. Oore adds no hidden default and appends no arguments.
Version 1 files keep working unchanged.
oore pipeline migrate rewrites a
version 1 file as version 2 that runs the same commands.
version: 2
app:
flutter: 3.24.5 # or omit to use .fvmrc
flavors: [free, pro] # optional; each target builds once per flavor
targets:
android:
build: flutter build appbundle --release --flavor ${{ flavor }}
artifacts: ['build/app/outputs/bundle/${{ flavor }}Release/*.aab']
publish:
play: { track: production, rollout: 0.01 }
ios:
build: flutter build ipa --release --flavor ${{ flavor }} --export-method app-store-connect
artifacts: [build/ios/ipa/*.ipa]
publish:
testflight: { group: Internal }
steps:
- name: Get packages
run: flutter pub get
- name: Tests
run: flutter test --machine > build/tests.json
reports: { tests: build/tests.json }
- build # the targets run here
- name: Size report
run: flutter build apk --analyze-size --target-platform android-arm64 --flavor pro
env:
BUILD_FLAVOR: staging
SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
workflows:
adhoc:
on:
pull_request: true
targets:
android:
build: flutter build apk --release --flavor ${{ flavor }}
artifacts: ['build/app/outputs/flutter-apk/*-${{ flavor }}-release.apk']
flavors: [free]
steps: [Get packages, build]
release:
on:
push: { branches: [main, release/*] }
tag: v*
paths: [lib/**, pubspec.*]
flavors: [pro] # a store takes one buildThe schema rejects unknown fields. Run
oore pipeline plan to see the steps each
workflow runs.
Top-level fields
| Field | Type | Required | Default |
|---|---|---|---|
version | integer | Yes | Must be 2 |
name | string | No | The file’s path |
app | object | No | No Flutter pin, no flavors |
targets | object | Yes¹ | No default |
steps | list | No | [build] |
env | map | No | {} |
vars | map | No | {} |
on | object | No | Pipeline trigger settings |
workflows | map | No | One implicit workflow |
signing | object | No | Pipeline signing settings |
build_number_offset | integer | No | 0 |
runs_on | string[] | No | [macos] |
isolation | string | No | host |
release_notes | object | No | Written in Oore or drafted |
¹ At least one target, at the top level or in a workflow.
build_number_offset, runs_on and isolation work as in
version 1.
release_notes names where the repository keeps the app version’s release
notes, with exactly one of:
| Field | Meaning |
|---|---|
changelog | A Markdown file such as CHANGELOG.md. The section headed with the app version, such as ## [2.5.1] - 2026-11-14, is used. |
dir | A directory with one <locale>.txt file, or fastlane’s <locale>/release_notes.txt, per language. |
release_notes:
changelog: CHANGELOG.mdSee Release notes and changes.
App
| Field | Type | Description |
|---|---|---|
flutter | string | Flutter version. A .fvmrc file takes precedence. |
flavors | string[] | Flavor matrix. Names use letters, digits, - and _. |
With flavors, every target builds once per flavor in the same build, as steps
named Build Android (free), Build Android (pro) and so on.
Targets
targets maps android, ios or macos to:
| Field | Type | Required | Description |
|---|---|---|---|
build | string | Yes | The complete build command for the platform. |
artifacts | string[] | No | Glob patterns. Defaults to the platform’s version 1 defaults. |
publish | object | No | Where the build is uploaded. See Publish. |
budgets | object | No | Artifact size limits for the check. See Budgets. |
Targets build in the order the file lists them. Artifact patterns follow the
version 1 rules and can use vars and
${{ flavor }}, but not ${{ secrets.NAME }}.
Unlike version 1, a Google Play upload does not add a
flutter build appbundle step. Write the App Bundle build into
targets.android.build; oore pipeline migrate leaves a comment with the
command version 1 would have added.
Steps
steps is an ordered list. Each entry is one of:
- a step with
nameandrun, and optionallyreports; build, which places the target builds; without it, the targets build after the last step;- in a workflow only, the name of a top-level step.
Step names are shown in logs and checks, must be unique, and are at most 100
characters. Build Android, Build iOS (pro) and the like name the target
builds and cannot be reused. Steps before build run as pre-build steps and
steps after it as post-build steps; Android signing and the iOS export
settings apply only to the target builds.
reports.tests names a workspace-relative .json (dart test or
flutter test --machine) or .xml (JUnit) file the step writes. Oore reads it
after the step, including when the step fails, and shows the results on the
build’s Tests tab. Plain flutter test and dart test commands are still
detected without it.
When the env var OORE_ANALYZE is true, the runner adds an analyze step
after the steps that runs dart analyze --format=json, as for
version 1.
Environment and references
env maps names to string values. Quote numbers and booleans, such as
RETRIES: '3'. Names follow [A-Za-z_][A-Za-z0-9_]*.
Commands, env values and artifact patterns can use these references:
| Reference | Resolves to |
|---|---|
${{ vars.NAME }} | The value of vars.NAME. Vars can refer to other vars. |
${{ secrets.NAME }} | A stored secret, resolved by the runner. See Use secrets. |
${{ flavor }} | The flavor being built, in a target’s build and artifacts only. |
Any other ${{ }} expression is an error. Vars are repository-owned text and
are substituted into commands before the build starts, so do not put
credentials in them. A var that refers back to itself, directly or through
other vars, is rejected with the cycle it forms, such as
vars form a cycle: vars.A -> vars.B -> vars.A.
Workflows
workflows maps a name to a variant of the top level. Each build runs one
workflow, and a workflow takes everything it does not set from the top level.
Workflow names use letters, digits, - and _.
workflows:
adhoc:
on: { pull_request: true }
signing: { ios: coin-adhoc }
release:
on: { push: { branches: [main] } }
signing: { ios: coin-app-store }
targets:
ios:
build: flutter build ipa --release
publish:
app_store: { destination: testflight, groups: [QA] }What a workflow inherits
| Field | Left out of the workflow | Set in the workflow |
|---|---|---|
on | The top-level on, else the pipeline’s trigger settings | Replaces the top-level on |
targets | Every top-level target, as written | [android] picks top-level targets; a map overrides them per field (see below) |
flavors | app.flavors | A subset of app.flavors |
steps | The top-level steps | Replaces them. Entries can name top-level steps |
env | The top-level env | Adds to or replaces top-level values by name |
vars | The top-level vars | Adds to or replaces top-level vars by name, also where other vars use them |
signing | The top-level signing, else the pipeline’s signing settings | Replaces the top-level signing per platform; a platform it leaves out keeps the top level’s |
name, app.flutter, build_number_offset, runs_on, isolation | Always the top level’s | Not available in a workflow |
A targets map entry overrides one top-level target field by field:
| Target field | Left out | Set |
|---|---|---|
build | The top-level target’s. Required when there is no top-level target of the same platform | Replaces it |
artifacts | The top-level target’s | Replaces it |
publish | The top-level target’s, unless this entry sets its own build: that publish uploads what the top-level build makes | Replaces it. false uploads nothing and keeps build |
budgets | The top-level target’s, even with a new build | Replaces it |
The pipeline can still change a workflow without a commit. Its Workflows tab can pick other signing identities, turn the workflow’s publishing off, or change its approval. See Workflow settings.
Which workflow a build runs
Each build runs one workflow, chosen when the build starts:
- Run build lists the workflows in the file at the branch or commit being
built and starts with the pipeline’s Default workflow selected.
oore build run --workflow NAMEand the build API’sworkflowfield name one the same way. - A build that names none uses the pipeline’s default workflow, then the
file’s only workflow. A file with no workflows builds the top level. A file
with several workflows and no default refuses the build with
invalid_workflowuntil one is named. - Pushes, pull requests and tags start the default workflow only. A pipeline
without a default starts one build for every workflow whose
onmatches the event (see Triggers).
The build page and build lists show each build’s workflow, and the pipeline
page filters its builds by workflow. oore pipeline workflows and
GET /v1/pipelines/{pipeline_id}/workflows?ref= list the workflows a build
can name, with their platforms, triggers and store uploads. A build always
reads the file at the commit it builds. The
Default workflow
setting describes how the pipeline picks its default.
Several pipelines can read one file. Each keeps its own default workflow and workflow settings, so two pipelines can run different workflows of the same file with different gates or identities. See Run two workflows from one file.
Publish
publish on a target says where a build is uploaded after it succeeds:
| Field | Target | Description |
|---|---|---|
play.track | android | internal, closed, open, production, or a custom track name. |
play.rollout | android | Staged rollout as a fraction greater than 0 and at most 1, such as 0.05 for 5%. Left out, the Google Play settings decide. |
play.draft | android | true creates a draft release in Play Console instead of rolling out. Left out, the Google Play settings decide. |
play.service_account | android | Name of the secret holding the Google service account JSON key. Set, the upload needs no pipeline Google Play settings. |
testflight.group | ios | The TestFlight group to add the build to: one name, without commas, at most 128 characters, and not app_store. |
app_store.destination | ios | app_store (default) attaches the build to the App Store version; testflight adds it to TestFlight groups. |
app_store.groups | ios | TestFlight groups, for destination: testflight. Left out, the App Store settings’ groups apply. |
app_store.submit_for_review | ios | Submit the version for App Review, for destination: app_store. Left out, the settings decide. |
app_store.phased_release | ios | Release with Apple’s seven-day phased release, for destination: app_store. Left out, the settings decide. |
play.preflight | android | What a failed pre-flight check does: auto (default), block, warn or off. See Pre-flight. |
app_store.release_type | ios | When Apple releases the approved version: after_approval (default), manual (after Release now) or scheduled. For destination: app_store. |
app_store.earliest_release_date | ios | RFC 3339 time such as 2026-12-01T09:00:00Z, required with release_type: scheduled and only allowed with it. |
app_store.cancel_previous_submission | ios | true cancels another open App Review submission for the app before submitting. Off, the release is blocked until you cancel it. |
app_store.release_notes_dir | ios | Repository directory with “What’s New” per locale, as <locale>.txt or fastlane’s <locale>/release_notes.txt. The top-level release_notes does the same for every store. |
app_store.preflight | ios | What a failed pre-flight check does: auto (default), block, warn or off. |
testflight: { group: QA } is the same as
app_store: { destination: testflight, groups: [QA] }; a target sets one of
the two.
track and group can use ${{ vars.NAME }}, so a workflow can change them
by overriding a var. Secrets and ${{ flavor }} are not available there.
publish: false (or null) publishes nowhere. On a workflow target it drops
the publish the target would otherwise take from the top level, while
keeping the top-level build:
workflows:
qa:
targets:
android:
publish: false # builds the release bundle, uploads nothingThe file says where to upload, and can name the Google Play key. When the planned workflow publishes to a store, the file replaces the pipeline’s Publish settings for that store:
- Google Play: the file’s
trackreplaces the settings’ track, and itsrollout,draftandservice_accountreplace the settings’ own where the file sets them. Withservice_account, the upload needs no Google Play settings; without them it sends the app version’s release notes, uploadsmapping.txtand checks no expected package. Withoutservice_account, the pipeline’s Google Play settings must have Upload after each build on. When they are on, the expected package, release notes, mapping upload, in-app update priority and rollout policy come from them. - App Store Connect (
app_storeortestflight): the file’s destination, groups,submit_for_reviewandphased_releasereplace the settings’ own. The App Store Connect API key comes from the pipeline’s iOS signing settings, which must export App Store IPAs, and App Store Connect publishing must be on. The export compliance answer still comes from the settings, and release notes from the app version.
Stores the file does not name, version 1 files and files without publish
keep the pipeline’s Publish settings exactly. Turning a workflow’s
Publishing off in the pipeline’s
workflow settings
stops every upload of that workflow, whatever the file says.
Problems with publish never stop the build: it runs and keeps its
artifacts, and only its publish-play or publish-app-store step fails, with
a message saying what to fix. That happens when:
- the store is not set up in the pipeline, for App Store Connect or for a
Google Play upload without
service_account(the message names the settings to turn on); - the target builds more than one flavor, since a store takes one build
(narrow it with
flavors: [<one flavor>]on the workflow); trackorgroup, once vars are resolved, is not a valid name, or refers to an undefined var.
oore pipeline validate prints a note: for each of these that it can see in
the file.
Google Play’s rules apply to the combined result. The internal track has no
staged rollouts, so a rollout below 1 there releases to every internal tester,
and a draft ignores rollout. The upload logs the adjustment, and
oore pipeline validate notes it when the file itself sets the combination.
Retrying a failed upload that took its destination from the file reads the file at the build’s commit again, so it uploads where the build would have. Retrying any other upload works as before and does not check out the source.
Google Play takes App Bundles, and Oore runs build as written. When a
workflow publishes to Google Play but its Android build does not appear to
build a bundle, oore pipeline validate prints a note:; the upload looks
for one under build/app/outputs/bundle. Keep an .aab artifact pattern (the
defaults include one) so a failed upload can be retried from the stored
bundle.
oore pipeline plan prints where each
workflow publishes, and the pipeline editor’s What will run section lists
it with the plan’s notes.
Signing
signing names identities from the app’s signing library (App
settings > Signing), so each workflow can sign with its own keys:
signing:
android: coin-upload # every workflow signs Android release builds with it
workflows:
adhoc:
signing: { ios: coin-adhoc } # ad hoc certificate and profiles
release:
signing: { ios: coin-app-store } # App Store certificate and profiles
targets:
ios:
build: flutter build ipa --release
publish:
app_store: { destination: app_store }| Field | Description |
|---|---|
android | An Android keystore identity. It signs release builds. |
ios | An iOS distribution identity: a certificate and its profiles. |
The names carry no secrets; the key material stays in Oore. A workflow without
signing uses the pipeline’s signing settings, as before. The pipeline’s
Workflows settings can pick a different identity for a workflow, or turn
its publishing off, without changing the file. See
Move credentials into the app library.
Oore checks the names when a build is created. A name the library does not
hold, or an identity of the wrong kind, refuses a manual build with
invalid_signing; a build started by a webhook fails at its signing step
with the same message. oore pipeline validate --project runs the same checks
before you push, and oore pipeline plan prints the identities each workflow
names.
The iOS export follows the identity: an identity with App Store profiles
exports App Store IPAs, one with ad hoc profiles exports ad hoc IPAs. A
workflow that uploads to App Store Connect with an ad hoc identity is
refused. A build command’s own --export-method is dropped when it agrees
with the identity and fails the build when it does not.
Budgets
budgets on a target holds its artifacts to a size budget on the pull request
check. It has the same shape and rules as the pipeline’s
size budget:
targets:
android:
build: flutter build appbundle --release
budgets:
mode: fail # or warn, the default
rules:
- kind: aab
max_increase_bytes: 524288 # 512 KiB over the baseline build
- kind: apk
max_bytes: 62914560 # 60 MiB
max_increase_percent: 2.5| Field | Type | Description |
|---|---|---|
mode | string | fail fails the check when an artifact is over; warn (default) only says so. |
rules[].kind | string | The artifact’s lowercase file extension, such as aab, apk or ipa. |
rules[].max_bytes | integer | Largest size allowed, in bytes. Greater than 0. |
rules[].max_increase_bytes | integer | Largest growth over the baseline build, in bytes. 0 or more. |
rules[].max_increase_percent | number | Largest growth over the baseline build, in percent. 0 or more. |
A rule needs at least one limit. A target takes at most 20 rules, each kind
once. aab and apk rules belong on android and ipa rules on ios.
Values are bytes, with no ${{ }} references.
The pipeline’s size budget is a floor: a target’s budgets add limits for
that platform’s check and can tighten the pipeline’s, never loosen or remove
them. Each platform’s check is held to both the pipeline’s size budget and its
own target’s budgets. An artifact over either is listed, with the budget it
went over, and the check fails when any budget it went over has mode: fail.
budgets on one target does not change another target’s check, and
budgets: { rules: [] } adds nothing. The check summary names the field the
budget came from, such as workflows.release.targets.android.budgets. The
budget only changes the check; the build itself never fails because of it.
Triggers
on accepts:
| Field | Type | Example |
|---|---|---|
push | true or { branches: [] } | { branches: [main, release/*] } |
pull_request | true or { branches: [] } | true |
tag | string or string[] | v* |
paths | string[] | [lib/**, pubspec.*] |
When a webhook arrives, Oore reads the pipeline’s file at the pushed commit.
If the pipeline’s default workflow sets on, or the file sets a top-level
on, that decides whether the event starts a build, in place of the
pipeline’s trigger settings. A pipeline without a default workflow matches
each workflow on its own on (or the top-level on) and starts one build
per workflow that matches; a workflow with neither follows the pipeline’s
trigger settings.
pushmatches pushes to a branch,truefor any branch orbranchesfor the listed globs.pull_requestmatches pull and merge requests that are opened, reopened or updated.branchesnames the branch the request targets, so{ branches: [main] }builds requests intomain.tagmatches pushed tags.pathsnarrows pushes and pull requests to changes that touch a matching file, with the same rules as the trigger settings’ path filters. Tag pushes ignore it.- A field left out, or set to
false, starts no builds for that event.
Branch and tag globs use * and ? as in the trigger settings. Schedules and
manual builds still come from the pipeline. Version 1 files, files without
on, and a missing or invalid file keep the pipeline’s trigger settings.
If Oore cannot read the file from GitHub or GitLab, for example during an
outage, a pipeline without a default workflow keeps its trigger settings. A
pipeline with a default workflow is skipped and the webhook delivery is retried (up to five
times), so it never builds from trigger settings its on would not allow.
Other pipelines still build on the first attempt.
For example, with the file above a pipeline set to adhoc builds every pull
request and a pipeline set to release builds pushes to main and
release/* that touch lib/ or pubspec.*, plus v* tags, with no trigger
settings in the UI.
Limits
Oore checks these limits before anything else, so a file stays cheap to validate:
| What | Limit |
|---|---|
| Workflows | 32 |
Flavors, in app.flavors or a workflow | 32 |
| Steps, top level or per workflow | 100 |
| Artifact patterns per target | 64 |
env entries, top level or per workflow | 128 |
vars, top level or per workflow | 128 |
| Branches, tags or paths in one trigger field | 64 |
A run or build command as written | 32 KiB |
| An artifact pattern as written | 2,048 characters |
| What vars add to one value | 64 KiB |
| Var references expanded, whole file | 250,000 |
| Text vars add, whole file | 4 MiB |
The last two count every workflow together. Each var is resolved once per flavor and reused, so ordinary files stay far below them.
Errors
Shape errors, such as an unknown field or a wrong type, name the line and
column. Other errors name the field path, for example
workflows.adhoc.steps[0] refers to step 'Lint', which is not defined in the top-level steps
or steps[2].run uses ${{ flavor }}, which is only available in a target's build and artifacts.
Every workflow is checked when the file is validated, so a broken reference in
any workflow fails oore pipeline validate.