How It Works

This page explains the mental model behind DevRamps. Understanding these concepts will make everything else in the documentation click.

Core Concepts

Pipeline

A pipeline is a YAML file in your repository that describes how to build and deploy your application. It lives at .devramps/<pipeline-slug>/pipeline.yaml in your repo. You can have multiple pipelines in a single repository (e.g., one for your API, one for your frontend).

A pipeline defines three things:

1. Stages -- The environments your code deploys through (e.g., staging, production).
2. Steps -- The deployment actions that run in each stage (e.g., run Terraform, deploy to ECS).
3. Artifacts -- The build outputs your steps consume (e.g., Docker images, file bundles).

Stages

A stage represents a deployment target -- typically an environment in a specific AWS account and region. Stages execute sequentially: staging finishes before production begins.

stages:
  - name: staging
    account_id: "111111111111"
    region: us-east-1

  - name: production
    account_id: "222222222222"
    region: us-east-1

Each stage runs the same set of steps, but against its own AWS account and region. You can customize behavior per stage using variables and skip lists.

Steps

A step is a single deployment action within a stage. Steps run sequentially by default, but you can control ordering with the goes_after field to run steps in parallel.

DevRamps provides built-in steps for common deployment patterns:

Category	Examples
Infrastructure	Terraform synthesis and apply. Use when you need to create or update AWS resources (VPCs, databases, load balancers).
Deploy	ECS, EKS, EKS Helm, CodeDeploy, EC2. Use to deploy your application containers or bundles to AWS services.
Approval	Bake time (soak test), automated test gates. Use to add safety checks between deployment actions.
Script	Run arbitrary scripts. Use for custom logic like cache invalidation, notifications, or data migrations.
Database	Run database migrations. Use to apply schema changes via Flyway, Liquibase, or custom scripts.

You can also build custom steps for anything not covered by the built-ins.

Artifacts

An artifact is something your pipeline builds from your source code. There are two types:

• Docker images -- Built from a Dockerfile, pushed to ECR, and used by container deployment steps (ECS, EKS).
• Bundles -- File archives (zip files) built by running shell commands, uploaded to S3, and used by CodeDeploy, EC2, or Lambda deployments.

Artifacts can also be imported from external sources -- if you build your images or bundles elsewhere, DevRamps can pull them in.

The Deployment Flow

When you push code to your repository, here's what happens:

 Git Push
    │
    ▼
 ┌──────────────────────┐
 │ 1. Pipeline Parsing    │  DevRamps reads and validates your
 │    (Synthesis)         │  pipeline.yaml, planning the deployment.
 └──────────┬────────────┘
            │
            ▼
 ┌──────────────────────┐
 │ 2. Artifact Builds    │  Docker images and bundles are built
 │                       │  from your source code.
 └──────────┬────────────┘
            │
            ▼
 ┌──────────────────────┐
 │ 3. Stage: staging     │  Steps execute in order:
 │   ├─ Terraform Apply  │  infrastructure → deploy → bake
 │   ├─ ECS Deploy       │
 │   └─ Bake (5 min)     │
 └──────────┬────────────┘
            │ (auto-promote on success)
            ▼
 ┌──────────────────────┐
 │ 4. Stage: production  │  Same steps run against the
 │   ├─ Terraform Apply  │  production account.
 │   ├─ ECS Deploy       │
 │   └─ Bake (5 min)     │
 └──────────────────────┘

Key behaviors

• Automatic promotion: When a stage succeeds, the next stage starts automatically. No manual intervention needed (unless you've configured approval gates).
• One deployment at a time: Each stage processes one deployment at a time. If a new push arrives while a stage is deploying, the new deployment queues until the current one finishes.
• Same steps, different targets: Every stage runs the same steps, but each stage has its own AWS account, region, and variables. This ensures your staging and production deployments are consistent.

Where Things Run

It's important to understand the boundary between DevRamps and your AWS accounts:

What	Where it runs
Pipeline parsing and orchestration	DevRamps cloud
Artifact builds (Docker, bundles)	DevRamps build VMs
Terraform plan/apply	DevRamps build VMs, targeting your AWS account
Application deployments (ECS, EKS, etc.)	Your AWS account
Deployed application	Your AWS account
Artifacts (ECR images, S3 bundles)	Your AWS CI/CD account
Terraform state	S3 in your AWS CI/CD account

Your source code is cloned onto DevRamps build VMs during builds. Deployments interact with your AWS account via short-lived IAM credentials obtained through OIDC federation.

What Happens at the End

After a successful deployment, your application is running on the AWS infrastructure defined by your pipeline — whether that's an ECS service behind a load balancer, pods in an EKS cluster, or instances managed by CodeDeploy. Your app becomes accessible at whatever URL your infrastructure provides (e.g., an ALB DNS name, a CloudFront distribution, or a custom domain).

Expressions

DevRamps uses an expression language (${{ }}) to inject dynamic values into your step parameters. This lets you reference stage-specific values, secrets, step outputs, and variables:

params:
  region: ${{ stage.region }}
  cluster_name: ${{ steps.infra.ecs_cluster_name }}
  api_key: ${{ organization.secrets["API_KEY"] }}
  environment: ${{ vars.env }}

See Expressions for the full reference.

What's Next?

• Prerequisites -- What you need before getting started.
• Quickstart -- Sign up and deploy your first application.