Step Registries

A step registry is a GitHub repository that contains your custom step code. When you push code to the registry repository, DevRamps builds it, extracts step metadata, and makes your custom steps available for use in pipelines.

Creating a Step Registry

1. Set up the repository

Create a new GitHub repository (or use an existing one) with this structure:

my-step-registry/
├── src/
│   └── steps.ts           # Your step implementations
├── package.json
└── tsconfig.json

2. Configure package.json

Your package.json must include two npm scripts:

{
  "name": "my-step-registry",
  "scripts": {
    "build-step-registry": "tsc",
    "start-step-registry": "node dist/steps.js"
  },
  "dependencies": {
    "@devramps/sdk-typescript": "^1.0.0",
    "zod": "^3.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

Script	Purpose
build-step-registry	Compiles your TypeScript code. Run during the build phase.
start-step-registry	Entry point for step execution. DevRamps calls this to synthesize metadata and execute steps.

3. Write your steps

Implement your steps using the DevRamps SDK (see Writing Custom Steps):

// src/steps.ts
import { SimpleStep, Step, StepOutputs, StepRegistry } from "@devramps/sdk-typescript";
import { z } from "zod";

const CacheInvalidateSchema = z.object({
  distributionId: z.string(),
  paths: z.array(z.string()),
});

@Step({
  name: "Invalidate CDN Cache",
  type: "cdn-invalidate",
  schema: CacheInvalidateSchema,
})
class CacheInvalidateStep extends SimpleStep<z.infer<typeof CacheInvalidateSchema>> {
  async run(params: z.infer<typeof CacheInvalidateSchema>) {
    this.logger.info("Invalidating CDN cache", {
      distributionId: params.distributionId,
    });

    // Your cache invalidation logic...

    return StepOutputs.success({ invalidated: true });
  }
}

StepRegistry.run([CacheInvalidateStep]);

4. Register with DevRamps

1. Go to your organization settings in the DevRamps dashboard.
2. Navigate to Step Registries.
3. Click Create Step Registry.
4. Enter:
   • Repository: Select the GitHub repository containing your step code.
   • Branch: The branch to build from (e.g., main).
   • Root file path: Path to your package.json (usually just package.json).
   • Language: nodejs (currently the only supported language).
5. Click Create.

5. Push to trigger a build

Push code to the configured branch. DevRamps:

1. Receives the webhook from GitHub.
2. Starts a build in an isolated VM.
3. Clones your repository.
4. Runs npm install and npm run build-step-registry.
5. Runs npm run start-step-registry -- --input '{"job": "SYNTHESIZE-METADATA"}' to extract step metadata.
6. Registers your custom step types with the organization.
7. Packages a build bundle and stores it for deployment use.

Build Process

Every push to your step registry repository triggers a build:

Code Push → Clone Repo → npm install → Build → Synthesize Metadata → Register Steps

After a successful build, your custom steps are immediately available for use in any pipeline in your organization.

Build failures

If a build fails, your previously registered steps remain available — a failed build never removes or overwrites existing step registrations. Common causes of build failures:

• Missing npm scripts — Ensure your package.json includes both build-step-registry and start-step-registry scripts.
• TypeScript compilation errors — Fix type errors before pushing. Run npm run build-step-registry locally to verify.
• Missing dependencies — Ensure all required packages are listed in dependencies (not just devDependencies).
• Metadata synthesis failure — The start-step-registry script must exit cleanly when called with --input '{"job": "SYNTHESIZE-METADATA"}'. Ensure StepRegistry.run() is called with all your step classes.

Check the build logs in Organization Settings > Step Registries to diagnose failures.

Updating Steps

To update your custom steps:

1. Make changes to your step code.
2. Push to the configured branch.
3. DevRamps rebuilds and re-registers your steps.
4. The next deployment that uses your custom steps will use the updated code.

Step registry builds are immutable -- each build is tied to a specific git commit SHA. This ensures deployments use a consistent version of your step code.

Multiple Steps in One Registry

A single step registry can contain multiple custom steps. Register them all in the StepRegistry.run call:

StepRegistry.run([
  CacheInvalidateStep,
  SlackNotifyStep,
  SmokeTestStep,
  DatabaseSeedStep,
]);

Each step gets its own CUSTOM:* type identifier based on the type field in the @Step decorator.

Next Steps

• Using Custom Steps -- Reference your custom steps in pipeline YAML.