What is sd-local ?

sd-local enables running a more feature-complete local Screwdriver without needing uploading source code to SCM. With sd-local, you can use features such as Command, Template, Metadata, and more.

Installing sd-local

Requirements

How to Install

Use Homebrew to install sd-local. Instructions here.

How to Update

Use the sd-local update command.

$ sd-local update
Do you want to update to 1.0.x? [y/N]: y
Successfully updated to version 1.0.x

If you get the following error while running the update command,

Error occurred while detecting version: GET https://api.github.com/repos/screwdriver-cd/sd-local/releases: 403 API rate limit exceeded.

Please set the GitHub personal access token.

export GITHUB_TOKEN=<token>

Quick start

This section describes the steps needed to execute a build with sd-local. Let Screwdriver API be https://api.screwdriver.cd, and let Screwdriver Store be https://store.screwdriver.cd in this section.

Create user API token

sd-local uses an user API token to communicate with Screwdriver API and Store. Please create an user API token with reference to Tokens.

Get repository for build

You have to get source code and screwdriver.yaml for build. You can use quickstart-generic.

$ git clone https://github.com/screwdriver-cd-test/quickstart-generic.git
$ cd quickstart-generic

Build configuration

sd-local needs some settings for builds, so you have to configure using the config command:

$ sd-local config set api-url https://api.screwdriver.cd
$ sd-local config set store-url https://store.screwdriver.cd
$ sd-local config set token <API Token>
$ sd-local config set launcher-version latest

Execute build

You can execute the main job using sd-local build command:

$ sd-local build main
INFO[0000] Prepare to start build...
sd-setup-launcher: Screwdriver Launcher information
sd-setup-launcher: Version:        v6.0.48
sd-setup-launcher: Pipeline:       #0
sd-setup-launcher: Job:            main
sd-setup-launcher: Build:          #0
sd-setup-launcher: Workspace Dir:  /sd/workspace
sd-setup-launcher: Checkout Dir:     /sd/workspace/src/screwdriver.cd/sd-local/local-build
sd-setup-launcher: Source Dir:     /sd/workspace/src/screwdriver.cd/sd-local/local-build
sd-setup-launcher: Artifacts Dir:  /sd/workspace/artifacts
export: $ export GREETING="Hello, world!"
export: set -e && export PATH=$PATH:/opt/sd && finish() { EXITCODE=$?; tmpfile=/tmp/env_tmp; exportfile=/tmp/env_export; export -p | grep -vi "PS1=" > $tmpfile && mv $tmpfile $exportfile; echo $SD_STEP_ID $EXITCODE; } && trap finish EXIT;
export:
hello: $ echo $GREETING
hello: Hello, world!
hello:
set-metadata: $ meta set example.coverage 99.95
set-metadata:

The build artifacts are created under the “./sd-artifacts” directory after the build is finished.

$ ls ./sd-artifacts
builds.log       environment.json steps.json

config command

You can configure sd-local for multiple environments by config command. Your settings are stored in ~/.sdlocal/config like below.

configs:
  default:
    api-url: ""
    store-url: ""
    token: ""
    launcher:
      version: stable
      image: screwdrivercd/launcher
  yourConfigName:
    api-url: ""
    store-url: ""
    token: ""
    launcher:
      version: stable
      image: screwdrivercd/launcher
current: default

Usage

create subcommand

You can create a new setting.

$ sd-local config create <name>

delete subcommand

You can delete a setting.

$ sd-local config delete <name>

use subcommand

You can switch a setting in use.

$ sd-local config use <name>

set subcommand

You can configure the setting currently using by key/value format. You must set api-url, store-url, and token in order to execute builds. Please refer to the List of keys about available settings.

$ sd-local config set <key> <value>

view subcommand

You can confirm the current settings. The setting starts with * is in use.

$ sd-local config view
  cluster1:
    api-url: https://cluster1-api-screwdriver.com
    store-url: https://cluster1-store-screwdriver.com
    token: yourcluster1token
    launcher:
      version: stable
      image: screwdrivercd/launcher
* cluster2:
    api-url: https://cluster2-api-screwdriver.com
    store-url: https://cluster2-store-screwdriver.com
    token: yourcluster2token
    launcher:
      version: stable
      image: screwdrivercd/launcher

List of keys

You must set api-url, store-url, and token in order to execute builds.

key description
api-url The Screwdriver API URL of the cluster you are using
store-url The Screwdriver Store URL of the cluster you are using
token An API token for the Screwdriver API of the cluster you are using
launcher-image The launcher image (default: screwdrivercd/launcher)
launcher-version The launcher version (default: stable)

build command

This command runs builds in your local environment.

Usage

Run a build for a specific job. Even if the build succeeds, other builds are not triggered.

$ sd-local build <job name>

It starts the build based on the screwdriver.yaml config in the current directory. Build artifacts will be created under the “./sd-artifacts” directory.

Options

The following options can be used with the build command:

option description
–artifacts-dir The build artifacts destination (default: ./sd-artifacts)
-e, –env The environment variables in a build environment using <key>=<value> format (multiple variables allowed)
–env-file The environment variables in a build environment using file format (refer to env-file format)
-i, –interactive Attach the build container in interactive mode
-m, –memory The memory limit of the build environment (can be specified in b, k, m, or g memory unit)
–meta The metadata used in a build environment using string JSON format: e.g. "{\"HOGE\": \"FOO\"}"
–meta-file The metadata used in build environment using file format
–src-url The remote SCM URL to build (https or ssh format)
–sudo Use sudo command to execute docker runtime

Note:

env-file format

--env-file option expects a file with a file format like the .env format of docker.

How to use Secrets

You can use Secrets by passing secrets in screwdriver.yaml as environment variables with --env or --env-file option.

$ sd-local build <job name> --env <secret name>=<secret value>

List of environment variables

You can use the following environment variables in sd-local build. The default values shown as - are the same defaults as in production Screwdriver. Please refer to environment variables for more details.

environment variable name default value
SCREWDRIVER false
CI false
CONTINUOUS_INTEGRATION false
SD_API_URL api-url in your config
SD_STORE_URL store-url in your config
SD_TOKEN generated JWT based on the token in your config
SD_SOURCE_DIR /sd/workspace/src/screwdriver.cd/sd-local/local-build
SD_JOB_NAME -
SD_TEMPLATE_FULLNAME -
SD_TEMPLATE_NAME -
SD_TEMPLATE_NAMESPACE -
SD_TEMPLATE_VERSION -
SD_META_DIR -
SD_META_PATH -
SD_ROOT_DIR -
SD_SOURCE_PATH -
SD_ARTIFACTS_DIR -