Getting Started with Screwdriver

This page will cover how to build and deploy a sample app with Screwdriver in minutes. In this example, we are using the SCM provider Github.

Requirements

Set Up

First, fork and clone a sample repository into your local development environment and cd into the project directory. We will cover the generic quickstart in this example.

$ git clone git@github.com:<YOUR_USERNAME_HERE>/quickstart-generic.git
$ cd quickstart-generic/

*For applications that are better suited to Makefiles and small scripts, we recommend referencing the generic screwdriver.yaml.

Developing the App

Now that we’ve setup our app, we can start developing. This app demonstrates how to run a Makefile and bash script (my_script.sh) in your Screwdriver build.

screwdriver.yaml

The screwdriver.yaml is the only config file you need for using Screwdriver. In it, you will define all your steps needed to successfully develop, build and deploy your application.

Workflow

The workflow describes the order that the jobs execute. The "main" job, which is created by default, is always executed first, followed by jobs listed in this workflow block.

Here, we have defined a job named "second_job", which will run after the "main" job.

---
# Workflow list definition
workflow:
  - second_job

Shared

The shared section is where you would define any attributes that all your jobs will inherit.

In our example, we state that all our jobs will run in the same Docker container image "buildpack-deps". The image is usually defined in the form of "repo_name". Alternatively, you can define the image as "repo_name:tag_label", where "tag_label" is a version. See the Docker documentation for more information.

# Shared definition block
shared:
  # Source: https://hub.docker.com/r/library/buildpack-deps/
  image: buildpack-deps

Jobs

The jobs section is where all the tasks (or steps) that each job will execute is defined. All pipelines have "main" implicitly defined. The definitions in your screwdriver.yaml file will override the implied defaults.

Steps

The steps section contains a list of commands to execute. Each step takes the form "step_name: command_to_run". The "step_name" is a convenient label to reference it by. The "command_to_run" is the single command that is executed during this step. Step names cannot start with sd-, as those steps are reserved for Screwdriver steps. Environment variables will be passed between steps, within the same job. In essence, Screwdriver runs /bin/sh in your terminal then executes all the steps; in rare cases, different terminal/shell setups may have unexpected behavior.

In our example, our "main" job executes a simple piece of inline bash code. The first step (export) exports an environment variable, GREETING="Hello, world!". The second step (hello) echoes the environment variable from the first step.

We also define another job called "second_job". In this job, we intend on running a different set of commands. The "make_target" step calls a Makefile target to perform some set of actions. This is incredibly useful when you need to perform a multi-line command. The "run_arbitrary_script" executes a script. This is an alternative to a Makefile target where you want to run a series of commands related to this step.

# Job definition block
# "main" is a default job that all pipelines have
jobs:
  main:
    # Steps definition block.
    steps:
      - export: export GREETING="Hello, world!"
      - hello: echo $GREETING
  second_job:
    steps:
      - make_target: make greetings
      - run_arbitrary_script: ./my_script.sh

Now that we have a working repository, let's head over to the Screwdriver UI to build and deploy an app. (For more information on Screwdriver YAMLs, see the configuration page.)

Building with Screwdriver

In order to use Screwdriver, you will need to login to Screwdriver using Github, set up your pipeline, and start a build.

Create a New Pipeline

  1. Click on the Create icon. (You will be redirected to login if you have not already.)

  2. Click Login with SCM Provider.

  3. You will be asked to give Screwdriver access to your repositories. Choose appropriately and click Authorize.

  4. Enter your repository link into the field. SSH or HTTPS link is fine, with #<YOUR_BRANCH_NAME> immediately after (ex: git@github.com:screwdriver-cd/guide.git#test). If no BRANCH_NAME is provided, it will default to the master branch. Click Use this repository to confirm and then click Create Pipeline.

Start Your First Build

Now that you've created a pipeline, you should be directed to your new pipeline page. Click the Start button to start your build.

Congratulations! You just built and ran your first app using Screwdriver!