en-US/about_Whiskey.help.txt

TOPIC
    about_Whiskey
     
SHORT DESCRIPTION
    Whiskey is a Continuous Integration/Continuous Delivery build platform.
     
LONG DESCRIPTION
         
    ## Overview
 
    Think of Whiskey 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](http://yaml.org/)
    into a "whiskey.yml" text file and committed into the root of your
    source code repository.
 
    ## System Requirements
 
    * PowerShell 4
    * A build server. Jenkins, TeamCity, or Appveyor are supported.
 
    ## Getting Started
 
    1. Create a `.whiskey` directory in the root of your source code
       repository.
    2. [Download Whiskey](https://www.powershellgallery.com/packages/Whiskey)
       from the PowerShell Gallery and put it in the ".whiskey" directory.
    3. Copy the ".whiskey\build.ps1" script into the root of your repository.
    4. Copy the ".whiskey\whiskey.sample.yml" file into the root of your
       repository. Rename it to "whiskey.yml".
    5. Add the .whiskey directory and the build.ps1 and whiskey.yml files to
       your repository. If you're using Git, run:
            
           > git add .whiskey build.ps1 whiskey.yml
           > git commit -m "Adding Whiskey."
            
    6. Run your build:
         
           > .\build.ps1
 
    ## Configuring Your Build
 
    ### Overview
 
    A Whiskey build has two phases: building and publishing (i.e.
    promoting). These are handled by the `BuildTasks` and `PublishTasks`
    pipelines in your whiskey.yml file. A pipeline is a list of tasks to
    perform when running that pipeline. Your first pipelines are empty:
 
       BuildTasks:
        
       PublishTasks:
     
    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 the next line and be indented four
    spaces. If a task has properties, the task name must end with a `:`. For
    example:
 
        BuildTasks:
        - TaskOne:
            Property1: Value
            Property2: Value2
        - TaskTwo:
            Property: Value
        # This task has no properties, so the ":" may be ommitted.
        - TaskThree
 
    YAML must be indented with spaces, not tabs.
 
    See the `about_Whiskey_Tasks` help topic to see Whiskey's tasks.
 
    ### Building
 
    Under the "BuildTasks" pipeline in your whiskey.yml file, add tasks you
    want to run when building. For example, Whiskey's build process looks
    like this:
 
        BuildTasks:
        - 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 "PublishTasks"
    pipeline. For example, Whiskey's publish process looks like this:
 
        PublishTasks:
        - 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](
    https://www.appveyor.com/), 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
        }
 
 
SEE_ALSO
    about_Whiskey_Tasks
    about_Whiskey_Variables
    about_Whiskey_Writing_Tasks