Running jobs on Windows Server 2016

Only runSh jobs are supported on Windows. This means that you should not enable your repository for CI and your shippable.yml cannot have any of the CI sections defined here.

You can use a Shippable provided on-demand node or bring your own node (BYON).

Setting up On-demand Nodes

1. Purchase the on-demand WindowsServer 2016 SKU

  • Go to your subscription billing plan by following the instructions documented here.
  • Click Edit plan, Add new SKU.
  • Click the dropdown under Type and select On Demand.
  • Click the dropdown under Architecture and select x86_64.
  • Click the dropdown under Operating System and select WindowsServer_2016.
  • Click the dropdown under Size and select the node size.
  • Adjust the number in the Quantity column to the capacity you need.
  • Enter the billing contact and credit card information and click on Upgrade

2. Configure Node pools

  • After you purchase the Windows SKU, a Node Pool is created and all the purchased nodes are assigned to the default Node Pool.
  • You can make this Node pool your default Node pool so that all jobs run on it by default. If the Node pool is not set to be the default Node pool, jobs will need to be explicitly assigned to it.

Setting up BYON Nodes

1. Purchase the BYON WindowsServer 2016 SKU

  • Click Edit plan, Add new SKU.
  • Click the dropdown under Type and select BYON.
  • Click the dropdown under Architecture and select x86_64.
  • Click the dropdown under Operating System and select WindowsServer_2016.
  • Adjust the number in the Quantity column to the capacity you need.
  • Enter the billing contact and credit card information and click on Upgrade

2. Configure Node pools

  • After you purchase the Windows SKU, a default Node Pool is created and all the purchased nodes are assigned to the default Node Pool.
  • You can make this Node pool your default Node pool so that all jobs run on it by default. If the Node pool is not set to be the default Node pool, jobs will need to be explicitly assigned to it.
  • You can create more Node pools if you want and change the allocation of nodes amongst your node pools.

3. Initialize your BYON node

  • Navigate to the Nodes setting page for your subscription by following the steps documented here.
  • Initialize your BYON node by following the steps documented here.

Define CI jobs and resources.

  • Your CI jobs and resources are defined in a shippable.yml in a repository in a supported SCM. The list of supported SCM integrations are documented here.
  • Create the shippable.yml in any of your configured SCM integration repository, except the source code repository that you are building itself. This approach offers several benefits such as controlling execute permissions on the jobs defined in the yml since only users who have write permissions on the repository can execute the jobs defined in it as well as commits to the yml file not triggering the build job itself. You can for experimentation purposes create the shippable.yml file in the source code repository itself, but this will create the undesired side-effect of running the build job whenever the shippable.yml file is committed, since the build job needs the repository as an input in order for it to checkout the repository. We are in the meantime actively working on a feature that will solve this job triggering issue.
  • We now define a gitRepo resource in shippable.yml that points to the repository that you want to build. This resource creates the necessary webhooks on your repository so that the job is automatically triggered on commits/prs/release tags. You can configure which webhooks you want to create, documented here.
resources:

  - name: myGitRepo
    type: gitRepo
    # replace github with your SCM integration name
    integration: github
    pointer:
      # replace devops-recipes/myapp with your source code organization and repository name.
      sourceName: devops-recipes/myapp
      # configure branch
      branch: master
      # configure webhooks
      buildOnCommit:            true
      buildOnPullRequest:       true
      buildOnPullRequestClose:  false
      buildOnRelease:           false
      buildOnTagPush:           false
  • We now define a runSh job in shippable.yml. This job lets you run any build script in your gitRepo or a powershell command. You can run your scripts or powershell commands directly on the host or in a windows container of your choice.

To run powershell commands or scripts in your repository in a container, you will need to specify the docker image, which ideally has your build tool chain already preinstalled, in runtime:options section in TASK. If you have created multiple Node pools and the Windows node pool is not the default Node pool, specify the Node pool in runtime:nodePool section.

  ## Job description:
  - name: ci_job
    type: runSh
    runtime:
      # replace custom__x86_64__WindowsServer_2016 with your node pool name
      nodePool: custom__x86_64__WindowsServer_2016
    steps:
      - IN: myGitRepo
      - TASK:
          name: buildApp
          runtime:
            options:
              imageName: "microsoft/windowsservercore"
              imageTag: "10.0.14393.1884"
          script:
            # cd to the gitRepo directory
            - pushd $env:MYGITREPO_STATE
            # run a build script in the git repo
            - ./runbuild.ps1

To run powershell commands or scripts in your repository on the host, specify container:false under TASK:runtime section. If you want to run docker commands in a TASK, the simplest approach is to run them on the host directly.

  ## Job description:
  - name: ci_job
    type: runSh
    runtime:
      nodePool: custom__x86_64__WindowsServer_2016
    steps:
      - IN: myGitRepo
      - TASK:
          name: buildApp
          runtime:
            container: false
          script:
            # cd to the gitRepo directory
            - pushd $env:MYGITREPO_STATE
            # run a docker build
            - docker build -t mynodeapp:latest .

To run docker commands in a container, you will need to do the following:

  • Package the docker binary in the container image itself (preferred) OR install the docker client in the container using powershell commands in the TASK section. The docker binary path should also be set in the PATH machine environment variable.

Here is an example of a powershell script that you can use either in your Dockerfile or the TASK section.

# Docker client binary
RUN Invoke-WebRequest https://download.docker.com/win/static/stable/x86_64/docker-17.06.2-ce.zip -OutFile docker-17.06.2-ce.zip; \
    mkdir c:\docker; \
    Expand-Archive  .\docker-17.06.2-ce.zip -DestinationPath $env:TEMP/docker/ -Force; \
    Move-Item $env:TEMP\docker\docker\docker.exe c:\docker\docker.exe; \
    $env:PATH = '{0};c:\docker' -f $env:PATH ; \
    [Environment]::SetEnvironmentVariable('PATH', $env:PATH, [EnvironmentVariableTarget]::Machine); \
    Remove-Item .\docker-17.06.2-ce.zip; \
    Remove-Item -recur -force $env:TEMP\docker;
  • Set the DOCKER_HOST environment variable to connect to the docker daemon running on the host.
$env:DOCKER_HOST=tcp://localhost:2375

After Windows Server 1709 is officially supported, you can also use named pipes as described here.

  • Commit the file and create a syncRepo.

The repository containing your jobs and resources is called a Sync repository and represents your workflow configuration. Follow these instructions to import your configuration files into your Shippable account.

  • Trigger your pipeline After you create the syncRepo, you can view the runSh job in the SPOG view. Right click on the job in the SPOG and click Run job. You can also trigger the job by committing changes to the repository.