haxtonfale / jenkins

PowerShell module for interacting with a CloudBees Jenkins server using the Jenkins Rest API.

Jenkins

PowerShell module for interacting with a CloudBees Jenkins server using the Jenkins Rest API.

Module Build Status

Branch	Azure Pipelines	Automated Tests	Code Quality
main

Table of Contents

• Requirements
• Installation
• Compatibility and Testing
• Automated Integration Tests
• Cross Site Request Forgery (CSRF) Support
• Cmdlets
• Known Issues
• Recommendations
• Examples
• Links

Requirements

This module requires the following:

• Windows PowerShell 4.x and above or
• PowerShell Core 6.x on:
  • Windows
  • Linux
  • macOS

Installation

If Windows Management Framework 5.0 or above is installed or the PowerShell Package management module is available:

The easiest way to download and install the Jenkins module is using PowerShell Get to download it from the PowerShell Gallery:

Install-Module -Name Jenkins

If Windows Management Framework 5.0 or above is not available and the PowerShell Package management module is not available:

Unzip the file containing this Module to your c:\Program Files\WindowsPowerShell\Modules folder.

Compatibility and Testing

This PowerShell module is automatically tested and validated to run on the following systems:

• Windows Server 2016 (using Windows PowerShell 5.1)
• Windows Server 2019 (using Windows PowerShell 5.1)
• Ubuntu 16.04 (using PowerShell Core 6)
• Ubuntu 16.04 (using PowerShell Core 7.x)
• Ubuntu 18.04 (using PowerShell Core 7.x)
• macOS 10.14 (using PowerShell Core 6)

This module should function correctly on other systems and configurations but is not automatically tested with them in every change.

Automated Integration Tests

This project contains automated integration tests that use Docker to run a Jenkins master server in a Docker Linux container. These tests can run on Windows 10 with Docker for Windows 2.0.4 or above installed. The tests also run automatically in Travis CI in the Linux build.

Cross Site Request Forgery (CSRF) Support

If a Jenkins Server has the CSRF setting enabled, then a "Crumb" will first need to be obtained and passed to each subsequent call to Jenkins in the Crumb parameter. If you receive errors regarding crumbs then your Jenkins Server has CSRF enabled and you will to ensure you are passing a valid "Crumb" obtained by calling the Get-JenkinsCrumb cmdlet.

To work with a Jenkins Master that has CSRF enabled:

$Crumb = Get-JenkinsCrumb `
    -Uri 'https://jenkins.contoso.com' `
    -Credential $Credential

New-JenkinsFolder `
    -Uri 'https://jenkins.contoso.com' `
    -Credential $Credential `
    -Crumb $Crumb `
    -Name 'Management' `
    -Verbose

Cmdlets

The full details of the cmdlets contained in this module can also be found in the wiki.

• Disable-JenkinsJob: Disables a Jenkins job.
• Enable-JenkinsJob: Enables a Jenkins job.
• Get-JenkinsCrumb: Gets a Jenkins Crumb.
• Get-JenkinsFolderList: Get a list of folders in a Jenkins master server.
• Get-JenkinsJob: Get a Jenkins Job Definition.
• Get-JenkinsJobList: Get a list of jobs in a Jenkins master server.
• Get-JenkinsObject: Get a list of objects in a Jenkins master server.
• Get-JenkinsPluginsList: Retrieves a list of installed plugins.
• Get-JenkinsViewList: Get a list of views in a Jenkins master server.
• Initialize-JenkinsUpdateCache: Creates or updates a local Jenkins Update cache.
• Invoke-JenkinsCommand: Execute a Jenkins command or request via the Jenkins Rest API.
• Invoke-JenkinsJob: Run a parameterized or non-parameterized Jenkins Job.
• Invoke-JenkinsJobReload: Reloads a job config on a given URL.
• New-JenkinsFolder: Create a new Jenkins Folder.
• New-JenkinsJob: Create a new Jenkins Job.
• Remove-JenkinsJob: Remove an existing Jenkins Job.
• Rename-JenkinsJob: Rename an existing Jenkins Job.
• Set-JenkinsJob: Set a Jenkins Job definition.
• Test-JenkinsFolder: Determines if a Jenkins Folder exists.
• Test-JenkinsJob: Determines if a Jenkins Job exists.
• Test-JenkinsView: Determines if a Jenkins View exists.

Known Issues

• Remove-JenkinsJob: An IE window pops up after deleting the job for some reason requesting authentication.
• Initialize-JenkinsUpdateCache: Does not correctly set the signature information in the update-center.json file that is created.

Recommendations

• If your Jenkins Server has security enabled then you should ensure that you are only connecting to it via HTTPS.
• If your Jenkins Server has security enabled, the Credentials parameter that can accept either the password for the Jenkins account or the API Token. It is strongly recommended that you use the API Token for the account as the password rather than the Jenkins account, even if you have implemented HTTPS.

Examples

Get a Crumb from a CSRF enabled Jenkins Server

Import-Module -Name Jenkins
$Crumb = Get-JenkinsCrumb `
    -Uri 'https://jenkins.contoso.com' `
    -Credential $Credential

Get a list of jobs from a Jenkins Server

Import-Module -Name Jenkins
$Jobs = Get-JenkinsJobList `
    -Uri 'https://jenkins.contoso.com' `
    -Credential (Get-Credential)

Get a list of jobs from the 'Misc' folder a Jenkins Server

Import-Module -Name Jenkins
$Jobs = Get-JenkinsJobList `
    -Uri 'https://jenkins.contoso.com' `
    -Credential (Get-Credential) `
    -Folder 'Misc'

Get a list of 'Freestyle' jobs from a Jenkins Server

Import-Module -Name Jenkins
$Jobs = Get-JenkinsJobList `
    -Uri 'https://jenkins.contoso.com' `
    -Credential (Get-Credential) `
    -IncludeClass 'hudson.model.FreeStyleProject'

Get a list of job folders from a Jenkins Server

Import-Module -Name Jenkins
$Folders = Get-JenkinsFolderList `
    -Uri 'https://jenkins.contoso.com' `
    -Credential (Get-Credential)

Get the job definition for 'My App Build' from a Jenkins Server

Import-Module -Name Jenkins
$MyAppBuildConfig = Get-JenkinsJob `
    -Uri 'https://jenkins.contoso.com' `
    -Credential (Get-Credential) `
    -Name 'My App Build'

Update the job definition for 'My App Build' on a Jenkins Server

Import-Module -Name Jenkins
Set-JenkinsJob `
    -Uri 'https://jenkins.contoso.com' `
    -Credential (Get-Credential) `
    -Name 'My App Build' `
    -XML $MyAppBuildConfig

Test if a job exists on a Jenkins Server

Import-Module -Name Jenkins
if (Test-JenkinsJob `
        -Uri 'https://jenkins.contoso.com' `
        -Credential (Get-Credential) `
        -Name 'My App Build') {
    # ... Jenkins Job was found
}

Create a new job called 'My App Build' on a Jenkins Server

Import-Module -Name Jenkins
New-JenkinsJob `
    -Uri 'https://jenkins.contoso.com' `
    -Credential (Get-Credential) `
    -Name 'My App Build' `
    -XML $MyAppBuildConfig

Rename an existing job called 'My App Build' to 'Other Build' on a Jenkins Server

Import-Module -Name Jenkins
Rename-JenkinsJob `
    -Uri 'https://jenkins.contoso.com' `
    -Credential (Get-Credential) `
    -Name 'My App Build'
    -NewName 'Other Build'

Remove a job called 'My App Build' from a Jenkins Server

Import-Module -Name Jenkins
Remove-JenkinsJob `
    -Uri 'https://jenkins.contoso.com' `
    -Credential (Get-Credential) `
    -Name 'My App Build'

Invoke a job called 'My App Build' on a Jenkins Server

Import-Module -Name Jenkins
Invoke-JenkinsJob `
    -Uri 'https://jenkins.contoso.com' `
    -Credential (Get-Credential) `
    -Name 'My App Build'

Invoke a parameterized job called 'My App Build' on a Jenkins Server

Import-Module -Name Jenkins
Invoke-JenkinsJob `
    -Uri 'https://jenkins.contoso.com' `
    -Credential (Get-Credential) `
    -Name 'My App Build' `
    -Parameters @{ verbosity = 'full'; buildtitle = 'test build' }

Get a list of installed plugins installed on a Jenkins Server

$Plugins = Get-JenkinsPluginsList `
        -Uri 'https://jenkins.contoso.com' `
        -Credential (Get-Credential) `
        -Verbose

Reload a job

Invoke-JenkinsJobReload `
        -Uri 'https://jenkins.contoso.com' `
        -Credential (Get-Credential) `
        -Verbose
    Triggers a reload of the jenkins server 'https://jenkins.contoso.com'

For further examples, please see module help for individual cmdlets.

Links

• Project site on GitHub
• Blog