Skip to main content

Quickstart

This guide walks you through signing up, connecting your repository, and triggering your first deployment with DevRamps.

1. Sign Up​

Go to devramps.com and create an account. You can sign up with:

  • Username and password
  • GitHub OAuth (recommended -- connects your GitHub account in one step)

When you sign up, DevRamps automatically creates a personal organization for you. You can create additional organizations later and invite team members.

2. Connect GitHub​

If you signed up with GitHub OAuth, your GitHub account is already connected. Otherwise:

  1. Go to your organization settings in the DevRamps dashboard.
  2. Click Connect GitHub.
  3. Authorize the DevRamps GitHub App on your GitHub account or organization.
  4. Select which repositories DevRamps should have access to.

This installs a GitHub App that allows DevRamps to detect pipeline definitions and clone your source code for builds.

3. Create Your Pipeline Definition​

In your repository, create a pipeline YAML file at .devramps/<pipeline-slug>/pipeline.yaml. The pipeline slug becomes the name of your pipeline (e.g., .devramps/my-api/pipeline.yaml creates a pipeline called my-api). Pipeline slugs must be lowercase alphanumeric characters and hyphens only (e.g., my-api, frontend-app).

Pre-existing Infrastructure Required

This example assumes you already have an ECS cluster, service, and task definition running in your AWS accounts. If you're starting from scratch, see Your First Pipeline for a more complete example that includes Terraform infrastructure setup.

Here's a minimal example that deploys a Docker container to ECS:

version: "1.0.0"

pipeline:
  cloud_provider: AWS
  pipeline_updates_require_approval: ALWAYS

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

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

  steps:
    - name: Deploy API
      type: DEVRAMPS:ECS:DEPLOY
      params:
        cluster_name: my-cluster
        service_name: my-service
        reference_task_definition: arn:aws:ecs:us-east-1:${{ stage.account_id }}:task-definition/my-task
        image_url: ${{ stage.artifacts["API Image"].image_url }}

  artifacts:
    API Image:
      type: DEVRAMPS:DOCKER:BUILD
      rebuild_when_changed:
        - /src
        - /Dockerfile
      params:
        dockerfile: /Dockerfile

See Pipeline Configuration for the full reference.

4. Bootstrap AWS Accounts​

Before DevRamps can deploy to your AWS accounts, you need to create IAM roles that grant it access. The DevRamps CLI handles this automatically.

From your repository root (where the .devramps/ folder is), first preview what will be created:

npx @devramps/cli bootstrap --dry-run

Once you've reviewed the output and are comfortable with the changes, run the bootstrap:

npx @devramps/cli bootstrap

The CLI will:

  1. Open your browser for authentication with DevRamps.
  2. Read your pipeline definitions to determine which accounts need bootstrapping.
  3. Create a CloudFormation stack in each target account containing:
    • An OIDC identity provider for secure, credential-less authentication.
    • An IAM role (DevRamps-CICD-DeploymentRole) with permissions scoped to your pipeline's step types.

If the bootstrap fails, see Troubleshooting for common issues and solutions. See the CLI Reference for more options.

5. Push Code to Trigger a Deployment​

Commit your pipeline definition and push to your repository:

git add .devramps/
git commit -m "Add DevRamps pipeline"
git push

DevRamps detects the pipeline definition, creates the pipeline, and starts the first deployment automatically. Currently, any branch push to a connected repository triggers a deployment.

First Deployment Timing

Your first deployment will typically take longer than subsequent ones — expect 5-15 minutes depending on artifact build times and infrastructure complexity. Subsequent deployments are faster due to artifact caching.

6. Monitor Your Deployment​

Go to the DevRamps dashboard at devramps.com to watch your deployment progress:

  • See each stage and step status in real time.
  • View build logs for artifact construction.
  • Stream deployment step logs as they execute.
  • Review Terraform plans before approving infrastructure changes.

If a step fails, click into it to view logs and understand what went wrong. You can retry failed stages directly from the dashboard.

What's Next?​