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

• docker
  • Use Docker container as build environment.
• git
  • Required when using --src-url option.

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

• default is created automatically when the first time you use sd-local
• current points the setting which you are currently using

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>

• You can’t delete the setting currently in use

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.

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:

Note:

• sd-local uses the value specified by --env option, if a same environment variable is specified in both --env and --env-file options.
• You can’t use both --meta and --meta-file options.
• If you don’t have a permission for docker runtime, use --sudo option.

env-file format

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

• Each line in an env file should follow VAR=VAL format.
• Lines beginning with # are processed as comments and ignored.
• Blank lines are ignored.
• There is no special handling of quotation marks. This means that they are part of the VAL.

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.