Artifacts

Artifacts are the build outputs that your deployment steps consume. DevRamps builds artifacts from your source code (or imports them from external sources) and makes them available to steps via expressions.

Artifact Types

Docker Build

Builds a Docker container image from a Dockerfile in your repository.

artifacts:
  API Image:
    type: DEVRAMPS:DOCKER:BUILD
    architecture: "linux/amd64"
    host_size: "medium"
    rebuild_when_changed:
      - /services/api
      - /Dockerfile
    params:
      dockerfile: /Dockerfile
      build_root: /
      args:
        - NODE_ENV=production

Param	Required	Description
dockerfile	Yes	Path to the Dockerfile, relative to repository root.
build_root	No	Docker build context directory. Defaults to repository root.
args	No	Build arguments passed to docker build --build-arg.
env	No	Environment variables available during the build.

The built image is pushed to an ECR repository managed by DevRamps. Reference it in steps with:

${{ stage.artifacts["API Image"].image_url }}

Bundle Build

Builds a file archive (zip) by running shell commands. Used for Lambda packages, static sites, CodeDeploy bundles, or any file-based artifact.

artifacts:
  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

Param	Required	Description
build_commands	Yes	Shell commands to build the bundle. Run in the repository root.
file_path	Yes	Path to the output file (relative to repo root) that becomes the artifact.
env	No	Environment variables available during the build.

The bundle is uploaded to S3. Reference it in steps with:

${{ stage.artifacts["Data Plane Bundle"].s3_url }}

Docker Import

Imports an existing Docker image from an external ECR repository. Use this when you build images in a separate CI system and want DevRamps to deploy them.

artifacts:
  External Image:
    type: DEVRAMPS:DOCKER:IMPORT
    rebuild_when_changed:
      - /services/api
    params:
      source_image_url: 085591178390.dkr.ecr.us-west-2.amazonaws.com/my-app:latest
      timeout_minutes: 15

Param	Required	Default	Description
source_image_url	Yes	--	Full ECR image URI to import. Supports expressions like ${{ trigger.sha }}.
timeout_minutes	No	15	Max time to wait for the image to be available (1--60 minutes).

Bundle Import

Imports an existing file bundle from an external S3 bucket.

artifacts:
  External Bundle:
    type: DEVRAMPS:BUNDLE:IMPORT
    per_stage: true
    params:
      source_s3_url: s3://my-bucket/builds/bundle.zip
      source_account: "085591178390"
      source_region: "us-west-2"
      timeout_minutes: 15

Param	Required	Default	Description
source_s3_url	Yes	--	Full S3 URI of the bundle to import. Supports expressions.
source_account	Yes	--	AWS account ID where the bundle resides.
source_region	Yes	--	AWS region where the bundle resides.
timeout_minutes	No	15	Max time to wait for the bundle to be available (1--60 minutes).

Common Artifact Fields

These fields apply to all artifact types:

Field	Default	Description
id	--	Short alias for referencing the artifact in expressions.
rebuild_when_changed	--	Array of file/directory paths. The artifact only rebuilds when files in these paths change. If omitted, the artifact rebuilds on every push.
per_stage	false	If true, the artifact is built separately for each stage (useful when build commands reference stage-specific variables).
architecture	"linux/amd64"	CPU architecture for the build VM: "linux/amd64" or "linux/arm64".
host_size	"small"	Build VM size: "small", "medium", or "large".
dependencies	[]	System dependencies to install on the build VM (e.g., ["node.24"]).

Referencing Artifacts in Steps

Use expressions to reference artifact outputs in your step parameters:

steps:
  - name: Deploy to ECS
    type: DEVRAMPS:ECS:DEPLOY
    params:
      image_url: ${{ stage.artifacts["API Image"].image_url }}

  - name: Deploy Bundle
    type: DEVRAMPS:CODEDEPLOY:DEPLOY
    params:
      artifact_name: Data Plane Bundle

Available artifact properties

Property	Available On	Description
image_url	Docker artifacts	Full ECR image URI (with tag).
image_tag	Docker artifacts	Just the image tag.
s3_url	Bundle artifacts	Full S3 URI of the bundle file.

Per-Stage Artifacts

By default, an artifact is built once and shared across all stages. If your build commands reference stage-specific variables (like ${{ vars.env }}), set per_stage: true to build a separate artifact for each stage.

artifacts:
  Frontend Bundle:
    type: DEVRAMPS:BUNDLE:BUILD
    per_stage: true
    rebuild_when_changed:
      - /frontend
    params:
      build_commands: |
        cd frontend
        REACT_APP_ENV=${{ vars.env }} npm run build
        zip -r ../frontend.zip build/
      file_path: /frontend.zip

Rebuild Optimization

Use rebuild_when_changed to skip unnecessary rebuilds. DevRamps compares the specified paths against the changes in the current push -- if none of the paths were modified, the artifact is reused from the previous build.

artifacts:
  API Image:
    type: DEVRAMPS:DOCKER:BUILD
    rebuild_when_changed:
      - /services/api          # Only rebuild when API code changes
      - /Dockerfile
      - /package.json
    params:
      dockerfile: /Dockerfile

If omitted, the artifact rebuilds on every push.

Additional Notes

Path format

All rebuild_when_changed paths are relative to the repository root and should start with /. Directory paths match all files recursively within that directory. Glob patterns (e.g., /src/**/*.ts) are not currently supported — use directory paths instead.

Build caching

Docker builds use standard Docker layer caching within a single build. Layer caches are not shared across deployments — each build starts clean. To optimize build times, structure your Dockerfile to maximize layer reuse (e.g., copy package.json and install dependencies before copying source code).

Multi-architecture

Each artifact targets a single architecture (linux/amd64 or linux/arm64). Multi-architecture builds (building both architectures from a single artifact definition) are not currently supported. If you need both architectures, define separate artifacts for each.