Skip to main content

Project lifecycle

Prerequisites

This page assumes familiarity with Project Structure and CI/CD integration.

Overview​

When you deploy a project with obproject-deploy, several resources are created on the platform. Understanding what gets created — and how to inspect or remove it — is essential for managing feature branches, cleaning up after experiments, and building custom deployment pipelines.

What deploy creates​

obproject-deploy reads your obproject.toml and processes the project directory in four stages:

StageWhat it doesResources created
1. AssetsRegisters data and model assets from data/ and models/ directoriesData assets, model assets
2. FlowsDeploys each flow under flows/ to Argo WorkflowsWorkflow templates, CronWorkflows (for @schedule), Sensors (for @trigger)
3. AppsDeploys app capsules from deployments/App capsules
4. MetadataRegisters a flowproject spec describing all deployed resourcesFlowproject metadata record

Each resource is scoped to a project and branch. The branch is derived from your git ref (e.g., main becomes the production branch, feature-v2 becomes a test branch).

Branch naming​

Branch names are normalized during deployment:

  • - and / characters are replaced with _
  • The result is lowercased

For example, git branch feature/add-scoring becomes feature_add_scoring.

Workflow template IDs follow a specific format where underscores are stripped entirely:

{project}.{metaflow_branch}.{flow_name}

For a project named fraud_detection on branch main with a flow called TrainFlow:

frauddetection.prod.trainflow

For a test branch feature-v2:

frauddetection.test.feature_v2.trainflow

The prod / test.{branch} prefix is Metaflow's @project branch convention.

Inspecting deployed resources​

Use the outerbounds flowproject CLI to inspect what's currently deployed.

List workflow templates​

outerbounds flowproject list-templates --id fraud_detection/main

This queries Argo directly for templates matching the project and branch annotations, so it reflects the actual cluster state regardless of what the metadata record says.

View metadata​

outerbounds flowproject get-metadata --id fraud_detection/main | jq .

The metadata record contains the full deployment spec: workflows, assets, apps, and their configurations as registered by the last obproject-deploy run.

Tearing down a branch​

When a feature branch is merged or abandoned, use teardown-branch to clean up all its deployed resources:

# Preview what will be deleted
outerbounds flowproject teardown-branch --id fraud_detection/feature-v2 --dry-run

# Execute the teardown
outerbounds flowproject teardown-branch --id fraud_detection/feature-v2 --yes

Teardown deletes resources in this order:

  1. Workflow templates — cascade-deletes associated CronWorkflows and Sensors
  2. Data assets
  3. Model assets
  4. Apps (capsules)
  5. Flowproject metadata

If any individual deletion fails, the command continues with remaining resources and reports errors at the end with a non-zero exit code.

Automating teardown in CI/CD​

Add a teardown step to your CI/CD pipeline when branches are deleted or PRs are closed:

# GitHub Actions example
on:
  delete:
    branches-ignore: [main]

jobs:
  teardown:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Configure Outerbounds
      run: |
        # ... authentication setup (see CI/CD integration) ...
    - name: Teardown branch
      run: |
        BRANCH=${GITHUB_EVENT_REF}
        PROJECT=$(yq .project obproject.toml)
        outerbounds flowproject teardown-branch \
          --id "$PROJECT/$BRANCH" --yes -o json

Building a custom deploy pipeline​

If you need more control than obproject-deploy provides, you can use the outerbounds flowproject commands directly. This is useful when you want to:

  • Deploy a subset of flows or assets
  • Integrate with a non-standard CI/CD system
  • Add custom validation steps between deploy stages

Registering metadata​

After deploying flows and assets through your own tooling, register the metadata so the platform knows what's deployed:

outerbounds flowproject set-metadata '{
  "project": "fraud_detection",
  "branch": "main",
  "workflows": [
    {"flow_template_id": "frauddetection.prod.trainflow"}
  ],
  "data": [
    {"id": "training_data"}
  ],
  "models": [
    {"id": "fraud_classifier"}
  ]
}'

Deleting metadata only​

If you manage resource lifecycle separately and only need to clean up the metadata record:

outerbounds flowproject delete-metadata --id fraud_detection/feature-v2 --yes

This does not touch workflow templates, assets, or apps.

See Also​