Overview

With the acquisition of "Automation for Jira" app by Atlassian, Jira Cloud now provides built-in automation capabilities allowing easy implementation of automated Jira processes and workflows.

This way, users can implement rules that are triggered upon some event, executed if certain condition(s) are met and, that perform certain action(s). 

Rules can also be triggered manually or may be scheduled.

Since Xray uses issue types for most of its entities, you can take advantage of it to implement some rules related to Xray.

Automation rules are available and, can be created, from the project settings, namely from the "Automation" tab.

This document highlights some examples around triggering test automation but you may implement other automation rules related to your processes.

Usage Examples

Jenkins

Trigger a Jenkins project build from an issue

In this very simple scenario, we'll implement a rule, triggered manually, that will trigger a Jenkins project/job. The action will be available from the "Automation" panel, in all issues of the selected project.

We're assuming that:

• you just want to trigger a CI job, period; this job may be totally unrelated to the issue from where you triggered it
• what the CI job will do, including if it will report the results back to Xray or not, is not relevant

Jenkins configuration

In Jenkins, we need to generate an API token for some user, which can be done from the profile settings page.

At the project level, we need to enable remote build triggers, so we can obtain an "authentication token" to be used in the HTTP request afterwards.

The project itself is a normal one, without parameters.

Automation configuration

1. create a new rule and define the "When" (i.e. when it to should be triggered), to be "Manually triggered"

2. define an action (i.e. the "Then") as "Send webhook" and configure it as follows

• the Webhook URL provided above follows this syntax:
  • <jenkins_base_url>/job/<name_of_jenkins_project_job>/build?token=<token>
• besides the "Content-Type" header that should be "application/json", define also an "Authorization" header having the value "Basic <auth>", where  the base64 encoded <auth> can be generated using your Jenkins API credentials

After publishing the rule, you can go to the screen of an issue and trigger the Jenkins project/job.

In this case, since Jenkins was configured to report results back to Xray, a new Test Execution would be created in Jira/Xray.

Trigger a Jenkins project build from a Test Plan and report the results back to it

In this simple scenario, we'll implement a rule, triggered manually, that will trigger a Jenkins project/job. The action will be available from the "Automation" panel, for all Test Plan issues of the selected project.

We're assuming that:

• you just want to trigger a CI job, period; this job may be totally unrelated to the issue from where you triggered it
• the results will be submitted back to Xray, if the project is configured to do so in Jenkins

Jenkins configuration

In Jenkins, we need to generate an API token for some user, which can be done from the profile settings page.

At the project level, we need to enable remote build triggers, so we can obtain an "authentication token" to be used in the HTTP request afterwards.

The project itself is a normal one; the only thing relevant to mention is that this project is a parameterized one, so it receives TESTPLAN, that in our case will be coming from Jira Cloud.

Automation configuration

1. create a new rule and define the "When" (i.e. when it to should be triggered ), to be "Manually triggered"

2. define the condition so that this rule can only be executed from Test Plan issue

3. define an action (i.e. the "Then") as "Send webhook" and configure it as follows

• the Webhook URL provided above follows this syntax:
  • <jenkins_base_url>/job/<name_of_jenkins_project_job>/buildWithParameters?token=<token>&TESTPLAN={{issue.key}}
• besides the "Content-Type" header that should be "application/json", define also an "Authorization" header having the value "Basic <auth>", where  the base64 encoded <auth> can be generated using your Jenkins API credentials

After publishing the rule, you can go to the screen of an issue and trigger the Jenkins project/job.

In this case, since Jenkins was configured to report results back to Xray, a new Test Execution would be created and linked back to the source Test Plan where the automation was triggered from.

Bitbucket Cloud/Pipelines

Trigger a Bitbucket pipeline build from an issue

In this very simple scenario, we'll implement a rule, triggered manually, that will trigger a Bitbucket pipeline build. The action will be available from the "Automation" panel, in all issues of the selected project.

We're assuming that:

• you just want to trigger a CI job, period; this job may be totally unrelated to the issue from where you triggered it
• what the CI job will do, including if it will report the results back to Xray or not, is not relevant

Bitbucket configuration

In Bitbucket we need to configure the pipeline as usual; no special configuration is needed.  Some variables can be used and defined at multiple layers.

# Use Maven 3.5 and JDK8
image: maven:3.5-jdk-8


pipelines:
  default:
    - step:
        caches:
          - maven
        script:
          - |
              echo "building my amazing repo..."
              mvn test
              export token=$(curl -H "Content-Type: application/json" -X POST --data "{ \"client_id\": \"$client_id\",\"client_secret\": \"$client_secret\" }" https://xray.cloud.xpand-it.com/api/v1/authenticate| tr -d '"')  
              echo $token
              curl -H "Content-Type: text/xml" -H "Authorization: Bearer $token" --data @target/surefire-reports/TEST-com.xpand.java.CalcTest.xml  "https://xray.cloud.xpand-it.com/api/v1/import/execution/junit?projectKey=CALC&testPlanKey=$testplan"
              echo "done

Automation configuration

1. create a new rule and define the "When" (i.e. when it to should be triggered), to be "Manually triggered"

2. define an action (i.e. the "Then") as "Send webhook" and configure it as follows

{
    "target": {
      "ref_type": "branch",
      "type": "pipeline_ref_target",
      "ref_name": "master"
    }
}

• the Webhook URL provided above follows the Bitbucket pipelines REST API syntax 
  
  • https://api.bitbucket.org/2.0/repositories/<workspace>/<repository>/pipelines/

• the Webhook HTTP POST body content, defined in the "Custom data" field, will be used to identify the target branch and also a variable containing the Test Plan issue key that will be accessible to the pipeline build

  custom data (i.e. HTTP body content) Expand source

  {
      "target": {
        "ref_type": "branch",
        "type": "pipeline_ref_target",
        "ref_name": "master"
      }
   ,
      "variables": [
        {
          "key": "testplan",
          "value": "{{issue.key}}"
        }
      ]
  }

• besides the "Content-Type" header that should be "application/json", define also an "Authorization" header having the value "Basic <auth>", where  the base64 encoded <auth> can be generated using your Bitbucket credentials

After publishing the rule, you can go to the screen of an issue and trigger the Bitbucket pipeline build.

In this case, a new Test Execution would be created in Jira/Xray.

Trigger a Bitbucket pipeline build from a Test Plan and report the results back to it

In this simple scenario, we'll implement a rule, triggered manually, that will trigger a Bitbucket pipeline build. The action will be available from the "Automation" panel, for all Test Plan issues of the selected project.

We're assuming that:

• you just want to trigger a CI job, period; this job may be totally unrelated to the issue from where you triggered it
• the results will be submitted back to Xray, if the pipeline is configured to do so

Bitbucket configuration

In Bitbucket pipeline definition we will make use of a variable named "testplan" (referenced by $testplan). This variable does not need to be defined explicitly as such in Bitbucket; Bitbucket will pass to the pipeline all "variables" identified in the REST API request, if so, whenever triggering the pipeline. 

# Use Maven 3.5 and JDK8
image: maven:3.5-jdk-8


pipelines:
  default:
    - step:
        caches:
          - maven
        script:
          - |
              echo "building my amazing repo..."
              mvn test
              export token=$(curl -H "Content-Type: application/json" -X POST --data "{ \"client_id\": \"$client_id\",\"client_secret\": \"$client_secret\" }" https://xray.cloud.xpand-it.com/api/v1/authenticate| tr -d '"')  
              echo $token
              curl -H "Content-Type: text/xml" -H "Authorization: Bearer $token" --data @target/surefire-reports/TEST-com.xpand.java.CalcTest.xml  "https://xray.cloud.xpand-it.com/api/v1/import/execution/junit?projectKey=CALC&testPlanKey=$testplan"
              echo "done

Automation configuration

1. create a new rule and define the "When" (i.e. when it to should be triggered ), to be "Manually triggered"

2. define the condition so that this rule can only be executed from Test Plan issue

3. define an action (i.e. the "Then") as "Send webhook" and configure it as follows

• the Webhook URL provided above follows the Bitbucket pipelines REST API syntax
  
  • https://api.bitbucket.org/2.0/repositories/<workspace>/<repository>/pipelines/

• the Webhook HTTP POST body content, defined in the "Custom data" field, will be used to identify the target branch and also a variable containing the Test Plan issue key that will be accessible to the pipeline build

  custom data (i.e. HTTP body content) Expand source

  {
      "target": {
        "ref_type": "branch",
        "type": "pipeline_ref_target",
        "ref_name": "master"
      }
   ,
      "variables": [
        {
          "key": "testplan",
          "value": "{{issue.key}}"
        }
      ]
  }

• besides the "Content-Type" header that should be "application/json", define also an "Authorization" header having the value "Basic <auth>", where  the base64 encoded <auth> can be generated using your Bitbucket credentials

After publishing the rule, you can go to the screen of an issue and trigger the Jenkins project/job.

In this case, a new Test Execution would be created and linked back to the source Test Plan where the automation was triggered from

Bamboo Server

Trigger a Bamboo plan build from an issue

In this very simple scenario, we'll implement a rule, triggered manually, that will trigger a Bamboo plan build. The action will be available from the "Automation" panel, in all issues of the selected project.

We're assuming that:

• you just want to trigger a CI job, period; this job may be totally unrelated to the issue from where you triggered it
• what the CI job will do, including if it will report the results back to Xray or not, is not relevant

 Bamboo configuration

No special configuration needs to be done in Bamboo.

Automation configuration

1. create a new rule and define the "When" (i.e. when it to should be triggered), to be "Manually triggered"

2. define an action (i.e. the "Then") as "Send webhook" and configure it as follows

• the Webhook URL provided above follows this syntax:
  • <bamboo_base_url>/rest/api/latest/queue/${projectKey}-${planKey}

• the Webhook HTTP POST body content, defined in the "Custom data" field, will be used to identify the stages to run and other parameters

  custom data (i.e. HTTP body content) Expand source

  default&ExecuteAllStages=true

• besides the "Content-Type" header that should be "application/x-www-form-urlencoded", define also an "Authorization" header having the value "Basic <auth>", where  the base64 encoded <auth> can be generated using your Bamboo credentials

After publishing the rule, you can go to the screen of an issue and trigger the Bamboo plan build.

In this case, since Bamboo was configured to report results back to Xray, a new Test Execution would be created in Jira/Xray.

Trigger a Bamboo plan build from a Test Plan and report the results back to it

In this simple scenario, we'll implement a rule, triggered manually, that will trigger a Bamboo's plan build. The action will be available from the "Automation" panel, for all Test Plan issues of the selected project.

We're assuming that:

• you just want to trigger a CI job, period; this job may be totally unrelated to the issue from where you triggered it
• the results will be submitted back to Xray, if the project is configured to do so in Bamboo

Bamboo configuration

The project itself is a normal one; the only thing relevant to mention is that this project is a parameterized one, so it receives a TESTPLAN variable, that in our case will be coming from Jira.

Automation configuration

1. create a new rule and define the "When" (i.e. when it to should be triggered ), to be "Manually triggered"

2. define the condition so that this rule can only be executed from Test Plan issue

3. define an action (i.e. the "Then") as "Send webhook" and configure it as follows

• the Webhook URL provided above follows this syntax:
  • <bamboo_base_url>/rest/api/latest/queue/${projectKey}-${planKey}

• the Webhook HTTP POST body content, defined in the "Custom data" field, will be used to identify the stages to run and other parameters

  custom data (i.e. HTTP body content) Expand source

  default&ExecuteAllStages=true&bamboo.TESTPLAN={{issue.key}}

• besides the "Content-Type" header that should be "application/x-www-form-urlencoded", define also an "Authorization" header having the value "Basic <auth>", where  the base64 encoded <auth> can be generated using your Jenkins API credentials

After publishing the rule, you can go to the screen of an issue and trigger the Bamboo plan.

In this case, since Bamboo was configured to report results back to Xray, a new Test Execution would be created and linked back to the source Test Plan where the automation was triggered from

Tips

Accessing network-restricted CI/CD tools

If your target system is behind a firewall or it's a local IP address, you can use ngrok tool to create a temporary tunnel to it. Please check with your IT/security team(s).

References

• Automation for Jira documentation
• Bitbucket Cloud
  • REST API for pipelines 
  • using variables in pipelines
  • integrating Jira Cloud and Bitbucket Cloud