Create Your First Build

This tutorial walks you through creating a project, configuring a pipeline, and triggering your first Flutter build.

What you need

• A running Oore CI instance in ready state (Set Up Your Instance)
• A GitHub or GitLab integration connected
• A Flutter project repository accessible through your integration
• The embedded runner active (default) or an external runner started

1. Create a project

1. Open the web UI at https://ci.oore.build (or your self-hosted UI)
2. Sign in with your OIDC provider
3. Click New Project
4. Select your integration (GitHub or GitLab)
5. Choose the repository containing your Flutter app
6. Give the project a name and click Create

2. Configure a pipeline

After creating the project, set up a build pipeline:

Option A: Use a .oore.yaml file (recommended)

Add a .oore.yaml file to the root of your repository:

version: 1
flutter_version: "3.24.0"
platforms:
  - android
commands:
  pre_build:
    - flutter pub get
  build:
    - flutter build apk --release
  post_build: []
artifacts:
  patterns:
    - "**/*.apk"

Push the file to your repository. Oore CI reads this file at build time — no UI configuration needed.

If your repository includes a .fvmrc file, Oore CI uses that Flutter version automatically. The flutter_version field in .oore.yaml is a fallback.

Option B: Configure via the UI

If you don't want a config file in your repo:

1. Open the project in the web UI
2. Go to Pipelines and click New Pipeline
3. Set the pipeline name and select target platforms
4. Configure build commands:
   • Pre-build: flutter pub get
   • Build: flutter build apk --release
5. Set artifact patterns: **/*.apk
6. Click Save

The UI fallback configuration is used when no .oore.yaml file exists in the repository.

3. Trigger a build

You can trigger builds three ways:

Manual trigger (UI)

1. Open the project
2. Click Trigger Build
3. Select the pipeline and branch
4. Click Start Build

Webhook trigger (automatic)

Push a commit or open a pull request. If your pipeline's trigger config matches the branch and event, a build starts automatically.

API trigger

curl -X POST http://127.0.0.1:8787/v1/projects/{project_id}/builds \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_id": "<pipeline_id>",
    "branch": "main"
  }'

4. Watch the build

1. Open the project and click on the running build
2. The build log streams in real-time via Server-Sent Events
3. Watch as the build moves through states: queued → assigned → running → succeeded

When the build succeeds, artifacts (e.g., the .apk file) appear in the build details.

Build states

State	Meaning
queued	Waiting for a runner to pick up the job
scheduled	Assigned to a runner, waiting to start
assigned	Runner has claimed the job
running	Build commands executing
succeeded	Build completed successfully
failed	Build commands returned a non-zero exit code
canceled	Build was manually canceled
timed_out	Build exceeded the time limit
expired	Build sat in queue too long without being claimed

For the full state machine, see Build States.

Troubleshooting

Build stuck in "queued"

• Check Settings > Runners for an active runner
• If using OORED_RUNNER_MODE=external, start a runner: oore runner start
• The default embedded runner should claim builds automatically

Flutter commands fail

Run oore doctor to check your toolchain:

oore doctor

Ensure fvm and flutter are installed and accessible.

"No .oore.yaml found" but UI pipeline exists

This is normal — the UI fallback config is used when no file exists. Builds will use the pipeline's execution config from the UI.

Next steps

• Configure pipeline YAML — full .oore.yaml reference
• Trigger builds — all trigger methods
• Add Android signing — sign your APKs (Wave 3)