Move a pipeline into .oore.yaml
Pick a pipeline format, generate a version 2 file from the pipeline editor, validate it, and commit it.
Move a pipeline’s build settings into .oore.yaml so they are reviewed and
versioned with the code they build. The runner reads the file from the exact
commit it builds, so an old build always uses the instructions it was built
with.
What you need
- A pipeline that builds successfully from the UI settings.
- Write access to the repository.
- App developer, maintainer, instance admin, or instance owner access in Oore.
- The
ooreCLI where you edit the repository, to validate the file.
Choose a format
Oore reads three kinds of pipeline definition. Use this table to pick one:
| Format | Status | Use it when |
|---|---|---|
| UI settings | implemented | You are getting started, or only Oore admins should change the build |
.oore.yaml version 2 | preview | The build should change with the code. Recommended for every new file |
.oore.yaml version 1 | implemented | You already have a working version 1 file and need nothing from version 2 |
Our recommendation:
- Start in the UI. The templates get a first build running without a file. The tutorials do this.
- Write new files as version 2. It is the format the pipeline editor
generates. It names each step, writes each platform’s full build command
with nothing hidden, and is the only version that supports
workflows,ontriggers,publish, andvars. - Keep a working version 1 file until you need one of those features.
Then convert it with
oore pipeline migrate, which checks that the new file runs the same commands.
Version 2 is in preview. Like every configuration format in Oore 0.1.x, it
can still change. Version 1 files keep working unchanged.
1. Generate the file
- Open the pipeline and select Edit.
- Scroll to What will run and keep Form settings selected.
- Under Repository file, select Copy or Download.
Oore generates a version 2 file from the current settings. Before it shows
the file, it plans it and checks that it runs the same steps as the form.
Notes under the file say which settings it could not express and that keep
applying from the pipeline, such as trigger settings that have no exact on
equivalent.
The file never contains secret values or store credentials. Env values are
copied as written, so a value that should be secret belongs in
Secrets, referenced as ${{ secrets.NAME }}.
To convert an existing version 1 file instead, run:
oore pipeline migrate --write2. Validate and preview the file
Save the file as .oore.yaml in the repository root, then run:
oore pipeline validate .oore.yaml
oore pipeline plan .oore.yamlvalidate prints .oore.yaml is valid. plan prints the commands each build
runs, in order and by step name.
3. Commit the file
Commit .oore.yaml to the branch Oore builds and push it. For an app that
points at a repository on the Oore Mac, commit it in that repository.
With the default Pipeline file setting, a pipeline checks .oore.yaml, then
.oore.yml, at the commit it builds. From the next build on, every pipeline
in the app that reads that path builds from the file, and its form
settings for the build stop applying. The pipeline editor names those
pipelines before you copy the file.
If the file defines several workflows, each build runs one of them.
Run build lists the workflows in the file at the branch you build and
shows what each builds, when it starts and where it publishes. To start every
manual run on the same one, open the pipeline’s Edit page and pick it
under Default workflow.
Pushes, pull requests and tags start the default workflow. With Default
workflow left at Not set, they start one build for each workflow whose
on matches, so one push can build adhoc and release side by side. The
build page and build lists show which workflow each build ran, and the
pipeline page filters its builds by workflow.
The Default workflow field lists the workflows in the file on the app’s
default branch. The line under it names that branch, such as
Workflows read from main. When the file is only on another branch so far,
select Change branch and enter that branch. When the file is missing,
invalid, or defines no workflows on the branch, the field stays visible and
says which. The branch only changes what the editor shows; builds still read
the file at the commit they build.
Run two workflows with different publishing
One file can hold a test build and a store release side by side, each with its own triggers, signing identity and store destination, run by one pipeline. See Run two workflows from one file.
Create a pipeline from an existing file
When the repository already has a pipeline file on its default branch,
create the pipeline from it. Oore looks for .oore.yaml, .oore.yml, files
named .oore.<name>.yaml in the repository root, such as
.oore.release.yaml, and files in the .oore/ directory.
- Open the app’s Pipelines tab and select Use repository workflow. With other pipelines in the app, select Add pipeline.
- Under Start from, Oore shows Repository workflow found and a summary of the platforms, Flutter version, commands, and artifacts. If it found several files, select the one to use.
- If the file defines several workflows, pick a Default workflow, or leave it at Not set to choose one on each run.
- Enter a Pipeline name and select Create pipeline.
For a file anywhere else, such as ci/oore.yaml, select Set up manually,
choose Use a file at another path under Pipeline file, and enter its path.
Oore reads the file from the default branch as you type, shows what it
builds, and offers Use this file’s settings.
To add a pipeline for a file without the form, or to have new files become pipelines on their own, see Add pipelines from the repository.
Check the result
Run a build. Its log contains a line like this:
Using pipeline config source: file:/.../.oore.yamlThe build’s steps carry the names from the file, such as Get packages and
Build Android. A build that still uses the form settings logs
ui_fallback instead.
Troubleshooting
Validation reports an unknown field
The schema rejects unknown fields. Compare the file with the version 2 reference, or the version 1 reference for a version 1 file.
The build fails because the workflow file is invalid
Fix the file at the commit the build used, validate it, and push again. Oore never falls back to the form settings when the file exists but is invalid.
The build still logs ui_fallback
The file is not at the commit Oore built, or the pipeline reads another path. Check the branch, and the pipeline’s Pipeline file setting. To read a file outside the repository root, choose Use a file at another path and enter its path.
A Google Play pipeline stops uploading after the move
Version 2 runs the Android build command as written. Make sure the Android
target builds an App Bundle, such as flutter build appbundle --release, and
keep an .aab artifact pattern.
Next step
Use secrets in a pipeline for tokens the file needs, or set up triggers, timeouts, and approvals. For why the file wins over the UI settings, read How Oore chooses pipeline configuration.