sd-localとは？

sd-localではSCMにコードをアップロードせずに、手元でScrewdriverと同じビルドを再現することができます。sd-localは、Command, Template, Metadataといった機能をScrewdriverと同様に利用することができます。

sd-localのインストール

実行環境について

sd-local実行には以下のコマンドが必要になります

• docker
  • ビルドの実行環境としてdockerコンテナを利用します
• git
  • --src-urlオプションを利用する場合に必要になります

インストール方法

sd-localをインストールするのにはHomebrewを使ってください。 手順はこちらを参照してください。

アップデート方法

sd-localのupdateコマンドを利用できます。

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

アップデートコマンドの実行中に下記のエラーが出た場合、

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

GitHub personal access tokenを設定してください。

export GITHUB_TOKEN=<token>

クイックスタート

sd-localでビルドを実行するまでの流れを説明します。

ここでは、ScrewdriverのAPIを https://api.screwdriver.cd、 Storeを https://store.screwdriver.cd とします。

ユーザAPIトークンの作成

sd-localでは、Screwdriver API, Storeとやり取りするためにユーザAPIトークンを利用します。 認証と認可を参考に、ユーザAPIトークンを作成してください。

ビルド対象のリポジトリを取得

ビルド対象のソースコードと screwdriver.yaml を取得します。ここではquickstart-genericを使います。

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

ビルド設定

ビルドを実行するための設定を行います。

$ 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トークン>
$ sd-local config set launcher-version latest

ビルドの実行

sd-localを使ってmainジョブを実行します。

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

ビルドが完了すると ./sd-artifacts 以下にビルド成果物が生成されます。

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

configコマンド

configコマンドでは、sd-local自体の設定を行います。設定内容は、環境ごとに複数保持することができます。 設定内容は ~/.sdlocal/config 以下の形式で保存されます。

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 はsd-localの初回利用時に自動的に作成されます
• current は現在使用中の設定を表します

使い方

createサブコマンド

新規設定を作成します。

$ sd-local config create <name>

deleteサブコマンド

設定を削除します。

$ sd-local config delete <name>

• 現在使用中の設定は削除できません

useサブコマンド

現在使用中の設定を変更します。

$ sd-local config use <name>

setサブコマンド

現在使用中の設定に対してkey/value形式で設定を行います。ビルドを実行するにはapi-url, store-url, tokenを設定する必要があります。 利用できる設定内容については、設定できるキーの一覧を参照してください。

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

viewサブコマンド

設定内容を確認できます。先頭に*がついているものが現在使用中の設定です。

$ 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

設定できるキーの一覧

buildコマンド

手元の環境でビルドを実行します。

使い方

ジョブを指定し、ビルドを実行します。実行したジョブが成功した場合も後続のジョブは実行されません。

$ sd-local build <job name>

上記のコマンドではカレントディレクトリの screwdriver.yaml をもとにジョブを実行します。 また、ビルド成果物は./sd-artifacts ディレクトリ以下に保存されます。

オプション

buildコマンドには以下のオプションを設定することができます。

注意：

• --env, --env-file オプションで同じ環境変数が指定された場合、 --env で指定した環境変数が優先されます
• --meta, --meta-file オプションを同時に指定することはできません
• Dockerランタイムの実行権限がない場合、--sudoオプションを使ってください

env-fileの形式

--env-file オプションで指定するファイルは docker の .env と同様の形式です。

• ファイルの各行は VAR=VAL の形式で構成されます
• # で始まる行はコメントとして無視されます
• 空行は無視されます
• 引用符に特殊な処理はされません。値の一部とみなされます

Secretsの利用方法

sd-localではSecretsを利用する場合、screwdriver.yamlのsecretsの項目で設定していた値を環境変数として--envもしくは--env-fileオプションによって直接指定する必要があります。

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

環境変数の一覧

sd-localのビルド内では、以下の環境変数が利用できます。デフォルト値に-が設定されているものは、Screwdriver上でのビルドと同様のため、環境変数を参照してください。