Skip to main content
Skip table of contents

Jenkins

Integrating Apwide Golive with Jenkins offers organizations a solution to empower their workflows through effective automation. This integration provides a range of features aimed at optimizing software development and deployment processes. You can expect those benefits:

✅ Development Team no longer need to manually update Jira tickets.
✅ QA Team can easily track where the Jira tickets are deployed.
✅ Release Managers always have access to up-to-date release notes.

Integration capabilities

This integration can automatically track your application deployments and your environment statuses.

Learn more

Integrating Apwide Golive with Jenkins will bring you the following capabilities:

  • Pushing deployment information and content to Jira/Golive
    Your Jenkins deployment pipelines create Golive deployments each time they are executed. All Jira issues mentioned in the related commit messages (via the Jira issue key) will be automatically linked to your Golive deployment. This ensures that the environment and timing details of your deployment are accessible directly from each linked Jira issue.

  • Creating any missing Jira versions
    If the version specified in the deployment doesn't yet exist in your Jira project, the integration can automatically create it and link the respective tickets.

  • Synchronizing versions across multiple Jira projects, as needed
    If the deployed Jira issues belong to different Jira projects, the integration can automatically create all relevant Jira versions and link the respective tickets.

  • Adding Jira issues to versions by updating the fixVersion field
    The fixVersion field of the deployed Jira issues is automatically updated to reflect the relevant Jira version.

  • Creating the missing information in Golive, if necessary
    In cases where applications, categories, or environments are missing in Golive, they can be created automatically 'on the fly'. This allows you to automatically build your environment inventory from your deployment pipelines, reducing manual effort and ensuring consistency.

Get started

Refer to our Jenkins Shared Library documentation explaining how to configure this integration.

Popular Use Cases

Send deployment information from a Jenkins pipeline (Shared Library)

Here are the steps you can re-use in your Jenkins pipelines, in order to send deployment information from Jenkins to Golive and keep track of status during deployment.

The advantage of using the apwSendDeploymentInfo step from our shared library is that, in addition to sending the provided parameters, the step will attempt to extract Jira tickets from commit messages to associate them with the ongoing deployment. This allows us to precisely determine which ticket is available on which environment.

If you have enabled deployment synchronization with Jira versions, Golive will take care of creating the version in the appropriate Jira project if it doesn't exist and will assign the fix version to the corresponding tickets.

This example is using our open source Jenkins Shared Lib
If you want to use curl instead, refer to the next section.

GROOVY 
@Library('apwide-jenkins-shared-lib')

pipeline {
    agent any
    environment {
    // APW_JIRA_BASE_URL = 'https://mycompany.com/jira'
    // APW_JIRA_CREDENTIALS_ID = 'jira-credentials'
    // Better to define above environment variables globally

        VERSION_NAME = "2.1.5.0"
        BUILD_NUMBER = currentBuild.number

        DEV_ENV_ID = 6 // identifies the target environment
        
        DEPLOY_STATUS_NAME = "Deploy"
        UP_STATUS_NAME = "Up"
    }
    parameters {
        choice(
          name: 'PROMOTE_TO_ENV', 
          choices: ['Dev', 'Demo'], 
          description: 'Should the output be promoted to an environment ?'
        )
    }
    stages {
        stage('Build & Test') {
            steps {
                script {
                    sh 'sleep 2s' 
                    // this simulates a build stage
                }
            }
        }
        stage('Deploy on Dev') {
            when {
                equals expected: 'Dev', actual: params.PROMOTE_TO_ENV
            }
            steps {
                apwSetEnvironmentStatus(
                  environmentId: env.DEV_ENV_ID,
                  status: env.DEPLOY_STATUS_NAME
                )
                
                sh "sleep 5s" // this simulated a deployment execution
                
                apwSendDeploymentInfo(
                  environmentId: env.DEV_ENV_ID, 
                  version: env.VERSION_NAME, 
                  buildNumber: env.BUILD_NUMBER
                )
                // this pushes the deployment information to Golive
                // N.B. This also automatically adds the list of Jira tickets 
                // found in commit history (since the last successful build),
                // to the deployment description
                
                apwSetEnvironmentStatus(
                  environmentId: env.DEV_ENV_ID,
                  status: env.UP_STATUS_NAME
                )
            }
        }
    }
}

Send deployment information from a Jenkins pipeline (curl)

Here are the steps you can re-use in your Jenkins pipelines, in order to send deployment information from Jenkins to Golive and keep track of status during deployment.

In the case of an update using curl, Jira tickets will not be automatically extracted from commit messages, and it is up to you to implement this logic yourself.

This example is using curl, which has to be present on the agent you are running the pipeline on.
If you want to use the Shared Lib instead, refer to the previous section.

GROOVY 
pipeline {
  agent {
    label "mvn"
  }
  environment {
    GOLIVE_BASE_URL = "https://golive.apwide.net/api"
    ENV_ID = 6
    // Jenkins credentials id of secret storing a previously generated golive token
    // https://golive.apwide.com/doc/latest/cloud/rest-api#RestAPI-api-tokenAPITokenAuthentication
    CREDENTIALS_ID = "golive-cloud-api-token"
    DEPLOY_STATUS_NAME = "Deploy"
    UP_STATUS_NAME = "Up"
  }
  parameters {
    choice(
        name: 'PROMOTE_TO_ENV',
        choices: ['Dev', 'Demo'],
        description: 'Should the output be promoted to an environment ?'
    )
  }
  stages {
    stage('Build & Test') {
      steps {
        script {
          // simulate a build stage
          sh 'sleep 2s'
        }
      }
    }
    stage("Deploy on Dev") {
      when {
        equals expected: 'Dev', actual: params.PROMOTE_TO_ENV
      }
      steps {
        container("atlas-sdk") {
          withCredentials([string(credentialsId: "${env.CREDENTIALS_ID}", variable: "goliveToken")]) {
            script {
              def versionName = "9.6.7"
              def buildNumber = env.BUILD_NUMBER

              // inform Golive of new deployment on going
              sh """curl -H 'Authorization: Bearer ${goliveToken}' -X PUT -H 'Content-Type: application/json' -d '{"name":"${env.DEPLOY_STATUS_NAME}"}' ${env.GOLIVE_BASE_URL}/status-change?environmentId=${env.ENV_ID}"""

              // simulate deployment
              sh "sleep 5s"

              // inform Golive of new deployed version
              sh """curl -H 'Authorization: Bearer ${goliveToken}' -X PUT -H 'Content-Type: application/json' -d '{"versionName":"${versionName}","buildNumber":"${buildNumber}"}' ${env.GOLIVE_BASE_URL}/deployment?environmentId=${env.ENV_ID}"""

              // inform Golive environment is up again
              sh """curl -H 'Authorization: Bearer ${goliveToken}' -X PUT -H 'Content-Type: application/json' -d '{"name":"${env.UP_STATUS_NAME}"}' ${env.GOLIVE_BASE_URL}/status-change?environmentId=${env.ENV_ID}"""
            }
          }
        }
      }
    }
  }
}

Use Jenkins as an url checker to update statuses of your environments

In this example you will learn how you can easily put in place a Jenkins pipeline that will automatically monitor a set of Golive Environments thanks to our integration with Jenkins.

Liveness Probe components:

  • probe url : we will simply re-use the url set in Golive environments

  • job: jenkins pipeline job

  • job scheduler: jenkins

With the Apwide Jenkins Shared Lib

The following jenkins pipeline uses our Jenkins Shared Lib:

JSON 
@Library('apwide-jenkins-shared-lib@develop') _

pipeline {
    agent any
    options {
        disableConcurrentBuilds()
        buildDiscarder(logRotator(numToKeepStr: '1'))
    }
    triggers {
        cron('*/10 * * * *') // triggered every 10 minutes
    }
    environment {
        // check jenkins shared lib documentation to configure credentials
        APW_GOLIVE_CLOUD_CREDENTIALS_ID = 'golive-cloud-api-token'
         
        APW_UNAVAILABLE_STATUS = 'Down' // adapt to your own status name
        APW_AVAILABLE_STATUS = 'Up' // adapt to your own status name
    }
    stages {
        stage('Golive Environments Monitoring') {
            steps {
                // check the url of all golive environments for application "e-Com" 
                apwCheckEnvironmentsStatus application:'e-Com'
                // check the url of all golive environments for application "ERP"
                apwCheckEnvironmentsStatus application:'ERP'
            }
        }
    }
}

Other more advanced examples of useful Jenkins pipelines to monitor your environments can be found here: https://github.com/apwide/apwide-jenkins-shared-lib/tree/master/examples/monitoring

Automatically get the versions of the apps installed on your Jira servers

At Apwide, we use several testing environments to deploy and test the various versions of our Jira apps. As we are installing our apps manually on certain Jira environments (ex: on our DEMO environment), we had to find a solution to retrieve this information directly from our test Jira instances.

Following the “eating your own dog food” principle, we are using Golive to track the versions of our apps that are deployed to our various Jira testing environments.

Model our testing environments in Golive

First step was to store all information (required to query our testing environments) in Golive:

Some of our apps testing environments modeled in Golive

Jenkins job retrieving and pushing current deployment state of our apps to Golive

This pipeline is executed every 5 minutes by Jenkins to update status and deployment information of your Jira apps:

GROOVY 
pipeline {
    agent {
        label 'monitoring'
    }
    options {
        disableConcurrentBuilds()
        buildDiscarder(logRotator(numToKeepStr: '1'))
    }
    triggers {
        cron('*/5 * * * *')
    }
    environment {
//        APW_JIRA_BASE_URL = 'https://your-jira-data-center-base-url'
//        APW_JIRA_CREDENTIALS_ID = 'jira-jenkins-user'
        APW_GOLIVE_CLOUD_CREDENTIALS_ID = 'golive-cloud-api-token'
        APW_UNAVAILABLE_STATUS = 'Down'
        APW_AVAILABLE_STATUSA = 'Up'
    }
    stages {
        stage('Apwide Jira Applications Monitoring') {
            steps {
                apwCheckEnvironmentsStatus criteria: [
                        'jira-plugin-key': '*'
                ], checkStatus: { environment ->
                    def pluginKey = java.net.URLEncoder.encode(environment.attributes['jira-plugin-key'], "UTF-8")
                    def baseUrl = environment.attributes['base-url']
                    echo "baseUrl: ${baseUrl}"
                    def credentialsId = credentialsMapping[environment.category.name]
                    def pluginInformation = apwCallJira(
                        jiraBaseUrl: baseUrl,
                        jiraCredentialsId: credentialsId,
                        path: "/rest/plugins/1.0/${pluginKey}-key" // https://ecosystem.atlassian.net/wiki/spaces/UPM/pages/6094960/UPM+REST+API
                    )
                    def pluginVersion = pluginInformation.version
                    echo "Plugin version: ${pluginVersion}"
                    apwSetDeployedVersion(
                              environmentId: environment.id,
                              version:pluginVersion
                      )
                }
            }
        }
    }
}

Environments, Applications, Categories Auto-Discovery

In a scenario where you already have the maturity to deploy application versions to your environments using your CI or even dynamically provision your environments, our shared library provides the ability to discover and capture this information from your pipelines to simplify the creation and referencing in Golive.

The apwSendEnvironmentInfo step allows you to retrieve version and status information for a given application and category. You have the option to enable automatic creation so that provisioning occurs in Golive, and you only need to let your CI build your inventory on your behalf.

Just like apwSendDeploymentInfo, this step is capable of extracting Jira tickets included in the build and associating them with the Golive deployment. This enables your users to know, from the Jira tickets, where these deployments are available and can be tested.

image-20240205-151651.png

Issue screen displaying where ticket is available

Here is an example of a parameterized pipeline that allows promoting a version to an environment or not. When the version is promoted to the environment, the information is pushed to Golive. In the example, the application and category are hard-coded, but if you have a common pipeline for provisioning your environments, the applications and categories could come from variables/parameters and be dynamically filled in the step:

GROOVY 
@Library('apwide-jenkins-shared-lib') _

pipeline {
    agent any
    environment {
//        APW_JIRA_BASE_URL = 'http://mycompany.com/jira' // these variables can be defined at different level: jenkins global properties, pipeline level, stage level
//        APW_JIRA_CREDENTIALS_ID = 'jira-credentials'
        VERSION_NAME = "2.1.5.0"
        BUILD_NUMBER = currentBuild.number
    }
    parameters {
        choice(name: 'PROMOTE_TO_ENV', choices: ['Dev', 'Demo'], description: 'Should the output be promoted to an environment ?')
    }
    stages {
        stage('Build & Test') { //
            steps {
                script {
                    sh 'sleep 2s' // here is just an example of build stage, build you can define your here, or choose to put on another pipeline
                }
            }
        }
        stage('Deploy on Dev') {
            when {
                equals expected: 'Dev', actual: params.PROMOTE_TO_ENV
            }
            steps {
                sh "sleep 5s" // replace this step with your own deployment procedure

              apwSendEnvironmentInfo([
                  targetEnvironmentAutoCreate: true,
                  targetApplicationName: "eCommerce",
                  targetApplicationAutoCreate: true,
                  targetCategoryName: "Staging",
                  targetCategoryAutoCreate: true,
                  environmentUrl: "https://ecom.stg.apwide.com",
                  environmentAttributes: [
                      Contact: "Max",
                      CPU: "2.8Ghz"
                  ],
                  statusName: "Up",
                  deploymentVersionName: "ECOM-3.0",
                  deploymentAttributes: [
                      Branch: "master",
                      Commit: "SHA-21aa23"
                  ],
                  deploymentBuildNumber: env.BUILD_NUMBER,
                  deploymentDescription: "Deployed from Jenkins",
                  deploymentIssueKeys: ["ECOM-20200", "ECOM-20201"]
              ])
            }
        }
    }
}
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close