Screwdriver API

8.0.143 verified Sat Apr 25 auth: no javascript

The Screwdriver API is the core server for the Screwdriver.cd continuous delivery service, currently at version 8.0.143. It provides 18 preloaded plugins for managing builds, pipelines, secrets, webhooks, and more, with support for multiple datastores (Postgres, MySQL, Sqlite), executors (Kubernetes, Docker, Nomad), and SCM providers (GitHub, GitLab, Bitbucket). Released weekly, it is actively maintained by Yahoo and the open-source community. Compared to Jenkins or GitLab CI, Screwdriver emphasizes container-native, pluggable architecture and SCM-agnosticism. Requires Node.js >=22.0.0.

Common errors

error Error: Cannot find module 'screwdriver-datastore-sequelize' ↓

cause Missing optional datastore plugin dependency.

fix

Install the package: npm install screwdriver-datastore-sequelize

error TypeError: jwt must be a string ↓

cause JWT_SECRET is not configured.

fix

Set JWT_SECRET environment variable or add to config file.

error Error: listen EADDRINUSE :::8080 ↓

cause Port 8080 is already in use.

fix

Change the port in config or kill the process using it.

error SyntaxError: Unexpected token 'export' ↓

cause Trying to run ESM code in a CJS environment.

fix

Add 'type': 'module' to package.json or use .mjs extension.

Warnings

breaking ESM-only since v6.0.0: CommonJS require() will not work. ↓

fix Use import syntax and ensure project is configured for ES modules.

breaking Node.js >=22.0.0 required starting from v8.0.0. ↓

fix Upgrade Node.js to >=22.0.0.

deprecated setupServer() is deprecated in favor of createServer() in v7.0.0. ↓

fix Use createServer() from 'screwdriver-api' instead.

breaking The 'server' export changed from default to named in v6.0.0. ↓

fix Use import { server } from 'screwdriver-api' instead of import server from 'screwdriver-api'.

gotcha Environment variables take precedence over config file; missing JWT_SECRET causes auth failures. ↓

fix Always set JWT_SECRET environment variable or in local.yaml.

Install

npm install screwdriver-api

yarn add screwdriver-api

pnpm add screwdriver-api

Imports

server

wrong

const server = require('screwdriver-api')

correct

import { server } from 'screwdriver-api'

ESM-only since v6.0.0; no default export.

setupServer
```
import { setupServer } from 'screwdriver-api'
```
Preferred way to start the API server programmatically.

Schema

wrong

import Schema from 'screwdriver-api'

correct

import { Schema } from 'screwdriver-api'

Named export for validation schemas.

Quickstart

Initialize and start Screwdriver API server with Docker executor, SQLite datastore, and GitHub SCM.

import { setupServer, server } from 'screwdriver-api';

const port = parseInt(process.env.PORT ?? '8080', 10);
const config = {
  port,
  datastore: {
    plugin: 'sequelize',
    sequelize: { dialect: 'sqlite', storage: './data.sqlite' }
  },
  executor: { plugin: 'docker' },
  scm: { plugin: 'github', github: { oauthClientId: process.env.GH_CLIENT_ID ?? '', oauthClientSecret: process.env.GH_CLIENT_SECRET ?? '' } },
  auth: { jwtSecret: process.env.JWT_SECRET ?? 'a-really-long-secret-change-me' }
};

const app = await setupServer(config);
app.listen(port, () => {
  console.log(`Screwdriver API running on http://localhost:${port}`);
});