Pipeline Overview

A DevRamps pipeline is a YAML file that defines how your application is built and deployed. It lives in your repository at .devramps/<pipeline-slug>/pipeline.yaml.

File Location

your-repo/
├── .devramps/
│   ├── my-api/
│   │   ├── pipeline.yaml                        # Pipeline definition
│   │   └── aws_additional_iam_policies.yaml     # Optional: extra IAM permissions
│   └── my-frontend/
│       └── pipeline.yaml                        # Another pipeline
└── ... your application code

Each subfolder under .devramps/ becomes a pipeline. The folder name is the pipeline slug (used in URLs and API calls). You can have multiple pipelines in a single repository.

The optional aws_additional_iam_policies.yaml file lets you add custom IAM permissions beyond what DevRamps provisions by default. See the CLI documentation for details.

Pipeline Discovery

Pipelines are discovered automatically. When you push code to a repository connected to DevRamps, the system scans for .devramps/*/pipeline.yaml files and creates or updates pipelines accordingly. There's no manual pipeline creation step -- just commit the YAML file and push.

Top-Level Structure

version: "1.0.0"

pipeline:
  cloud_provider: AWS
  pipeline_updates_require_approval: ALWAYS
  tracks: main                        # Optional: branch to track (default: main)

  stage_defaults:
    deployment_time_window: PACIFIC_WORKING_HOURS

  stages:
    - name: staging
      # ... stage config
    - name: production
      # ... stage config

  steps:
    - name: My Step
      # ... step config

  artifacts:
    My Artifact:
      # ... artifact config

Top-level fields

Field	Required	Description
`version`	Yes	Pipeline definition version. Use `"1.0.0"`.
`pipeline`	Yes	The pipeline configuration object.

Pipeline fields

Field	Required	Description
`cloud_provider`	Yes	Cloud provider for deployments. Currently only `AWS` is supported.
`pipeline_updates_require_approval`	Yes	When pipeline definition changes need approval: `ALWAYS`, `NEVER`, or `DESTRUCTIVE_CHANGES_ONLY`.
`tracks`	No	The Git branch this pipeline tracks. Defaults to `main`. Only pushes to the tracked branch trigger deployments. See Branch Tracking.
`stage_defaults`	No	Default settings applied to all stages. See Stages.
`stages`	Yes	Array of deployment stages. At least one required. See Stages.
`steps`	Yes	Array of deployment steps. See Steps.
`artifacts`	Yes	Map of artifact definitions. If your pipeline has no artifacts (e.g., Terraform-only), provide an empty map: `artifacts: {}`. See Artifacts.

Pipeline update approval

The pipeline_updates_require_approval field controls what happens when you change your pipeline.yaml:

Value	Behavior
`ALWAYS`	Every pipeline change requires manual approval before taking effect.
`NEVER`	Pipeline changes are applied automatically on push.
`DESTRUCTIVE_CHANGES_ONLY`	Only changes that remove stages, steps, or artifacts require approval.

Complete Example

version: "1.0.0"

pipeline:
  cloud_provider: AWS
  pipeline_updates_require_approval: ALWAYS

  stage_defaults:
    deployment_time_window: PACIFIC_WORKING_HOURS

  stages:
    - name: staging
      deployment_time_window: NONE
      account_id: "111111111111"
      region: us-east-1
      vars:
        env: staging
        azs: ["us-east-1a", "us-east-1b", "us-east-1c"]
        service_name: data-plane

    - name: prod-us-east-1
      account_id: "222222222222"
      region: us-east-1
      vars:
        env: prod
        azs: ["us-east-1a", "us-east-1b", "us-east-1c"]
        service_name: data-plane

    - name: prod-us-west-2
      account_id: "222222222222"
      region: us-west-2
      vars:
        env: prod
        azs: ["us-west-2a", "us-west-2b", "us-west-2c"]
        service_name: data-plane

  steps:
    - name: Synthesize Infrastructure
      id: infra
      type: DEVRAMPS:TERRAFORM:SYNTHESIZE
      params:
        requires_approval: ALWAYS
        source: /infrastructure
        variables:
          stripe_api_key: ${{ organization.secrets["STRIPE_API_KEY"] }}
          bundle_s3_url: ${{ stage.artifacts["Data Plane Bundle"].s3_url }}
          pipeline_name: ${{ pipeline.name }}
          region: ${{ stage.region }}
          aws_account_id: ${{ stage.account_id }}
          environment: ${{ vars.env }}
          azs: ${{ vars.azs }}

    - name: Deploy Service
      type: DEVRAMPS:ECS:DEPLOY
      goes_after: ["Synthesize Infrastructure"]
      params:
        cluster_name: ${{ steps.infra.ecs_cluster_name }}
        service_name: ${{ steps.infra.ecs_service_name }}
        reference_task_definition: ${{ steps.infra.task_definition }}
        image_url: ${{ stage.artifacts["API Image"].image_url }}

    - name: Bake Period
      type: DEVRAMPS:APPROVAL:BAKE
      params:
        duration_minutes: 1

  artifacts:
    API Image:
      type: DEVRAMPS:DOCKER:BUILD
      rebuild_when_changed:
        - /services/api-plane
      params:
        dockerfile: /services/api-plane/Dockerfile

    Data Plane Bundle:
      type: DEVRAMPS:BUNDLE:BUILD
      architecture: "linux/arm64"
      host_size: "medium"
      dependencies: ["node.24"]
      rebuild_when_changed:
        - /services/data-plane
      params:
        build_commands: |
          cd services/data-plane
          npm install
          npm run build
          zip -r ../../bundle.zip .
        file_path: /bundle.zip

Pipeline validation errors

If your YAML is malformed or contains invalid configuration, DevRamps will surface a validation error during pipeline synthesis. Common errors include:

Invalid YAML syntax — Indentation errors, missing colons, unclosed quotes.
Unknown step type — Using a step type that doesn't exist (e.g., typo in DEVRAMPS:ECS:DEPLOY).
Missing required fields — Omitting required parameters like account_id or region.
Invalid expression — Referencing an object that doesn't exist in ${{ }} syntax.

Validation errors appear in the deployment view in the dashboard during the synthesis step.

Branch Tracking

By default, a pipeline tracks the main branch. Only pushes to the tracked branch trigger deployments for that pipeline. You can change this with the tracks field:

version: "1.0.0"

pipeline:
  cloud_provider: AWS
  pipeline_updates_require_approval: ALWAYS
  tracks: develop
  # ...

This is useful when you have separate pipelines for different environments or release workflows. For example, you might have one pipeline tracking develop for staging deployments and another tracking main for production.

Multiple pipelines per branch

You can have multiple pipelines in a single repository, each tracking a different branch. Each pipeline lives in its own .devramps/<slug>/ folder and can independently specify which branch it tracks.

Next Steps

Stages -- Configure deployment stages, accounts, and regions.
Steps -- Configure deployment steps and ordering.
Artifacts -- Configure artifact builds and imports.
Expressions -- Use dynamic values in your pipeline.

File Location​

Pipeline Discovery​

Top-Level Structure​

Top-level fields​

Pipeline fields​

Pipeline update approval​

Complete Example​

Pipeline validation errors​

Branch Tracking​

Next Steps​