Home

Overview

Whiskey is a build tool. Think of it as a build server you can run from the command line. Instead of writing a bunch of PowerShell/batch/whatever scripts, what you want to happen during your build is written as YAML into a "whiskey.yml" text file and committed into the root of your source code repository.

System Requirements

• Windows PowerShell 5.1 with .NET Framework 4.6 or PowerShell Core 6+ (Windows, Linux, or macOS)
• A build server. Jenkins, TeamCity, or Appveyor are supported.

Getting Started

1. Grab the latest default build.ps1 script, which will bootstraps Whiskey into your repository and create a whiskey.yml file for you:

Invoke-WebRequest 'https://github.com/webmd-health-services/Whiskey/releases/latest/download/build.ps1' -OutFile 'build.ps1'

If you get an error about not being able to create an SSL/TLS secure channel, you need to enable TLS 1.2:

[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor [System.Net.SecurityProtocolType]::Tls12

2. Run your build:

.\build.ps1

3. Add Whiskey to your .gitignore file:

/PSModules/**

4. The build.ps1 script will create a new whiskey.yml file for you. Open it in your favorite editor and start adding tasks!

Configuring Your Build

Overview

A Whiskey build has two phases: building and publishing (i.e. promoting). These are handled by the Build and Publish pipelines in your whiskey.yml file. A pipeline is a list of tasks to perform when running that pipeline. Your first pipelines are empty:

Build:

Publish:

A pipeline is a list of tasks. Each task has properties that control what the task does. In Yaml, you create a list by prefixing each item with - . Task properties should start on a new line and be indented four spaces. If a task has properties, the task name must end with a :. For example:

Build:
- TaskOne:
    Property1: Value
    Property2: Value2
- TaskTwo:
    Property: Value
# This task has no properties, so the ":" may be ommitted.
- TaskThree

Some tasks have default properties. If a task has a default property, you can use a simplified syntax to call them:

Build:
- TaskOne: DefaultValue
  Property1: Value1
  Property2: Value2

Note that when using this simplified syntax, the task name must be the first property in the YAML task map.

Executable commands are also supported as build tasks:

Build:
- cmd.exe /C echo Hello World!

Whiskey uses the Exec task to run these executable commands.

YAML must be indented with spaces, not tabs.

See the Tasks page to see a list of Whiskey's tasks.

Building

Under the Build pipeline in your whiskey.yml file, add tasks you want to run when building. For example, Whiskey's build process looks like this:

Build:
- Pester4:
    Path: Test\*.Tests.ps1

In this example, Whiskey will run the Pester4 task, which in this example, will run all the Pester tests that match the Test\*.Tests.ps1 wildcard path.

Publishing

Publishing only happens after a successful build when the build is running under a build server. Publishing never happens when run by a developer. Additionally, publishing only happens when a build runs on a publishing branch, which are set with the PublishOn property in the root of your whiskey.yml file. The default whiskey.yml file publishes on the master branch:

PublishOn:
- master

The PublishOn property is a list of branch names. Wildcards are allowed.

When publishing, Whiskey runs all the tasks in the Publish pipeline. For example, Whiskey's publish process looks like this:

Publish:
- PublishPowerShellModule:
    RepositoryName: PSGallery
    RepositoryUri: https://powershellgallery.com/
    Path: Whiskey
    ApiKeyID: PowerShellGallery

The PublishPowerShellModule task publishes a PowerShell module to PowerShell repository. In this example, the module is published to the PowerShell Gallery.

API Keys and Credentials

Some tasks, especially those used when publishing, need API keys or credentials. Whiskey does not let you add this sensitive information to your whiskey.yml file. If a publishing tool doesn't support some way of caching/saving and using credentials securely, you can add them to your build using the Whiskey API.

Every task that needs a secret will have an ApiKeyID or CredentialID property. In your build.ps1 script, use this ID when calling Whiskey's Add-WhiskeyApiKey or Add-WhiskeyCredential functions to add the value of that API key or credential.

For example, here is how Whiskey's own build process adds its PowerShell API key to Whiskey, which builds under Appveyor, which exposes the API key as an environment variable:

if( (Test-Path -Path 'env:POWERSHELL_GALLERY_API_KEY') )
{
    Add-WhiskeyApiKey -Context $context -ID 'PowerShellGallery' -Value $env:POWERSHELL_GALLERY_API_KEY
}