Oore CI
Build and shipConfigure pipelines

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 oore CLI 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:

FormatStatusUse it when
UI settingsimplementedYou are getting started, or only Oore admins should change the build
.oore.yaml version 2previewThe build should change with the code. Recommended for every new file
.oore.yaml version 1implementedYou 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, on triggers, publish, and vars.
  • 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

  1. Open the pipeline and select Edit.
  2. Scroll to What will run and keep Form settings selected.
  3. 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 --write

2. 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.yaml

validate 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.

  1. Open the app’s Pipelines tab and select Use repository workflow. With other pipelines in the app, select Add pipeline.
  2. 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.
  3. If the file defines several workflows, pick a Default workflow, or leave it at Not set to choose one on each run.
  4. 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.yaml

The 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.