CLI

The DevRamps CLI (@devramps/cli) bootstraps the AWS infrastructure that DevRamps needs to deploy to your accounts. It creates IAM roles, OIDC identity providers, and security policies scoped to your pipeline's requirements.

Installation

Run directly with npx (no installation required):

npx @devramps/cli bootstrap

Or install globally:

npm install -g @devramps/cli
devramps bootstrap

Prerequisites

• Node.js 18+: Install Node.js.
• AWS CLI: Configured with credentials that can assume roles in your target accounts.

aws configure
# or
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key

The Bootstrap Command

The bootstrap command reads your pipeline definitions and creates CloudFormation stacks in each target AWS account.

npx @devramps/cli bootstrap [options]

Options

Option	Description	Default
--target-account-role-name <name>	IAM role to assume in target accounts. Use this if your accounts don't use AWS Organizations.	OrganizationAccountAccessRole (fallback: AWSControlTowerExecution)
--pipeline-slugs <slugs>	Comma-separated list of pipeline slugs to bootstrap.	All pipelines
--dry-run	Show what would be created without actually deploying.	false
--verbose	Enable verbose logging.	false

Examples

Bootstrap all pipelines:

npx @devramps/cli bootstrap

Bootstrap specific pipelines:

npx @devramps/cli bootstrap --pipeline-slugs my-api,my-frontend

Preview without deploying:

npx @devramps/cli bootstrap --dry-run

Use a custom cross-account role:

npx @devramps/cli bootstrap --target-account-role-name MyCustomRole

What Gets Created

For each pipeline and target account combination, the CLI creates a CloudFormation stack named DevRamps-<pipeline-slug>-Bootstrap containing:

OIDC Identity Provider

An OpenID Connect identity provider (devramps.com) that enables secure, credential-less authentication. DevRamps uses OIDC federation instead of long-lived access keys -- no secrets are stored anywhere.

IAM Role

An IAM role (DevRamps-CICD-DeploymentRole) with:

• Trust policy: Allows only your specific organization and pipeline to assume the role via OIDC.
• Step permissions: Least-privilege policies for each step type used in your pipeline (ECS, EKS, Terraform, etc.).
• Additional policies: Any custom policies you've defined in aws_additional_iam_policies.yaml.

Project Structure

The CLI expects your repository to have a .devramps/ folder:

your-repo/
├── .devramps/
│   ├── my-api/
│   │   ├── pipeline.yaml                        # Required
│   │   └── aws_additional_iam_policies.yaml     # Optional
│   └── my-frontend/
│       └── pipeline.yaml
└── ... your application code

Additional IAM Policies

If your pipeline needs AWS permissions beyond what the built-in step types provide (e.g., for Terraform to manage custom resources), add them in aws_additional_iam_policies.yaml:

- Version: "2012-10-17"
  Statement:
    - Effect: Allow
      Action:
        - s3:GetObject
        - s3:PutObject
        - s3:DeleteObject
      Resource: "arn:aws:s3:::my-bucket/*"
    - Effect: Allow
      Action:
        - dynamodb:*
      Resource: "arn:aws:dynamodb:*:*:table/my-table"

Or in JSON format (aws_additional_iam_policies.json):

[
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": ["s3:GetObject", "s3:PutObject"],
        "Resource": "arn:aws:s3:::my-bucket/*"
      }
    ]
  }
]

Authentication Flow

When you run bootstrap, the CLI:

1. Opens your browser to the DevRamps authentication page.
2. You log in and select your organization.
3. The CLI receives an authentication token.
4. The token is used to fetch your organization's configuration.
5. Bootstrap proceeds with the authenticated context.

The authentication flow has a 5-minute timeout. If the browser doesn't open automatically, check for popup blockers.

Troubleshooting

"Could not find .devramps folder"

Make sure you're running the CLI from your repository root, where the .devramps/ folder is located.

"No AWS credentials found"

Configure AWS credentials:

aws configure
# or set environment variables
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
# or use SSO
aws sso login

"Unable to assume role"

Your credentials don't have permission to assume the target account role. Verify:

1. The role exists in the target account.
2. Your credentials have sts:AssumeRole permission for that role.
3. The role's trust policy allows your identity.

Try a different role:

npx @devramps/cli bootstrap --target-account-role-name MyCustomRole

"Authentication timed out"

The browser authentication has a 5-minute timeout. Make sure:

1. Your browser opened the DevRamps authentication page.
2. You completed login and organization selection.
3. No popup blocker is preventing the page from opening.

CI/CD Account vs. Target Accounts

DevRamps uses two kinds of AWS accounts:

• CI/CD Account: A central account that stores shared resources — ECR repositories for Docker images, S3 buckets for bundles, Terraform state files, and KMS encryption keys. This is referenced in expressions as organization.cicd_account_id. If you use AWS Organizations, this is typically a dedicated account; otherwise, it can be the same as one of your target accounts.

• Target Accounts: The accounts where your application actually runs. Each pipeline stage specifies a target account in its account_id field. These are where ECS services, EKS clusters, EC2 instances, and other infrastructure live.

Cross-Account Roles

The default role name (OrganizationAccountAccessRole) assumes you're using AWS Organizations, where member accounts have this role created automatically. If you're not using AWS Organizations:

• Create an IAM role in each target account that your bootstrap credentials can assume.
• Use --target-account-role-name to specify the role name.
• The role needs administrator access (for creating CloudFormation stacks with IAM resources).

Permissions Required

The IAM user or role running bootstrap needs:

• sts:AssumeRole — To assume the cross-account role in each target account.
• The cross-account role itself needs administrator access (or at minimum: CloudFormation, IAM, and STS permissions) to create the bootstrap stack.

After bootstrapping, the created DevRamps-CICD-DeploymentRole has only the minimum permissions needed for your pipeline's step types.

Uninstalling / Cleanup

To remove DevRamps from an AWS account, delete the CloudFormation stack created by bootstrap:

1. Open the AWS CloudFormation console in the target account.
2. Find the stack named DevRamps-<pipeline-slug>-Bootstrap.
3. Delete the stack.

This removes the IAM role, OIDC provider, and all associated resources. Deleting the stack does not affect your running applications — it only removes DevRamps' access to the account.

When to Re-bootstrap

Re-run bootstrap when:

• You add a new step type to your pipeline (e.g., adding EKS steps to a pipeline that only had ECS).
• You update aws_additional_iam_policies.yaml with new custom permissions.
• You add a new target account to your pipeline stages.

Re-bootstrapping updates the existing CloudFormation stack — it does not create duplicate resources.