/apwide-jenkins-shared-lib

Jenkins shared library to interact with Jira from pipeline

Primary LanguageGroovy

Jenkins shared library for Jira and Apwide Golive

Your are at the right place if you use Jira + Apwide Golive + Jenkins and if you love automation!

You should use this open source Jenkins Shared Library to easily exchange information between Jenkins, Jira and Apwide Golive.

If you prefer examples over documentation, jump directly to the pipeline examples library and come back here later.

Pre-requisites

Get Started

  1. Import the Jenkins Shared Library
  2. Create your first Hello World pipeline:
Push eCommerce Dev environment's deployed version to Apwide Golive
steps {
    apwSetDeployedVersion(
        jiraBaseUrl: 'http://admin:admin@mycompany.com/jira',
        application: 'eCommerce',
        category: 'Dev',
        version: '0.0.1-SNAPSHOT'
    )
}

In this example script, we have set:

  • jiraBaseUrl, user and password to connect to Jira with Apwide Golive (keep reading to learn how to get rid of these ugly hard coded values...)
  • deployed version of the "eCommerce Dev" environment to "0.0.1-SNAPSHOT"

A bit cleaner

You can use Jenkins credentials instead of hard coding user/password in your pipeline. Usage of predefined global variables also makes your pipeline more readable:

environment {
    APW_JIRA_BASE_URL = 'http://mycompany.com/jira'
    APW_JIRA_CREDENTIALS_ID = 'jira-credentials'
    APW_APPLICATION = 'eCommerce'
    APW_CATEGORY = 'Dev'
}
steps {
    apwSetDeployedVersion version: '0.0.1-SNAPSHOT'
    apwSetEnvironmentStatus status: 'Up'
}

Much more concise, isn't it ?

Using Jenkins variable is very powerful. Learn more how use them at different levels:

More powerful

You just need a single step to check the url of all your Apwide environments:

environment {
    APW_JIRA_BASE_URL = 'http://mycompany.com/jira'
    APW_JIRA_CREDENTIALS_ID = 'jira-credentials'
    APW_UNAVAILABLE_STATUS = 'Down'
    APW_AVAILABLE_STATUS = 'Up'
}
steps {
    apwCheckEnvironmentsStatus
}

This single step will automatically call the url of each environment and set its status to "Up" (valid Http response) or "Down" (Http error). Quite powerful, isn't it ? ;-)

Direct calls to Jira and Apwide Golive Rest API

You can also make direct calls to any endpoints of Jira and Apwide Golive REST API using this more generic step:

steps {
    apwCallJira httpMode: 'GET', path: '/rest/api/2/project/10000'
    apwCallJira httpMode: 'POST', path: '/rest/api/2/versions', body:[:]
}

To add more predefined steps: fork the project and add your own script sugars! We will be happy to merge your pull requests! ;-)

More Examples

Browse our "examples" folder to get inspired and to reuse portion of scripts to write your own pipelines. They start from the easiest to the most advanced ones. A quick overview:

Environment Monitoring

Deployment tracking

Self-Service Environments

Predefined Global Variables

To avoid duplication in your pipelines, Jenkins global variables can be set and overriden at different levels.

Here are the available predefined global variables:

Jira global variables

  • APW_JIRA_BASE_URL : Jira base url. (e.g. http://localhost:8080 or if you use a context http://localhost:2990/jira). Replace jiraBaseUrl parameter.
  • APW_JIRA_CREDENTIALS_ID : Id of the Jenkins credentials use to to call Jira Rest API. Replace jiraCredentialsId parameter. If not provided the shared library will look for the credentials id 'jira-credentials'
  • APW_JIRA_PROJECT : id of key of a given jira project that will be used by steps using a Jira project (ex: creation of Jira versions)

Note that you can also override the global variables using inline properties at step level like in this example:

environment {
    APW_JIRA_BASE_URL = 'http://mycompany.com/jira'
    APW_JIRA_CREDENTIALS_ID = 'jira-credentials'
}
def project = apwCallJira(
    jiraBaseUrl: 'http://localhost:2990/jira',
    jiraCredentialsId: 'localhost-jira-admin',
    httpMode: 'GET',
    path: '/rest/api/2/project/10000'
)

This allows you to easily deal with multiple Jira and Apwide Golive servers if required.

Apwide Golive global variables

  • APW_APPLICATION : Environment application name used in Apwide Golive (e.g. 'eCommerce'). Replace application parameter.
  • APW_CATEGORY : Environment category name used in Apwide Golive (e.g. 'Dev', 'Demo', 'Staging'...). Replace category parameter
  • APW_UNAVAILABLE_STATUS : Status name when environment is considered as not available by enmvironment status check. Replace unavailableStatus parameter
  • APW_AVAILABLE_STATUS : Status name when environment is considered as available by environment check status. Replace availableStatus parameter
  • APW_ENVIRONMENT_ID : Id of the Apwide Golive Environment (used when updating environment details, attributes). Replace environmentId parameter

Browse documentation in Jenkins UI

You can browse the list of step parameters and global variables of the shared lib in Parameters Global Variable Reference. This documentation will be visible from the pipeline editor only after having successfully ran the job once.

Provided Pipeline Steps

Call any REST endpoint

Manage Environment

Search and List Environments

Manage Application

Manage Category

Monitor Environments

Jira Project

Jira Version

References