Release Automation Explained
Troubleshooting?
Have issues running Release Automation rules? Please check our troubleshooting guide - https://releasemanagement.atlassian.net/wiki/spaces/RMC/pages/2522284033/Release+Automation+Explained#%F0%9F%86%98-Troubleshooting-Automation-Rules.
Topics
- 1 Troubleshooting?
- 2 Introduction
- 3 Successor of “Outcoming WebHooks“
- 4 Integration with Jira Automation
- 5 Release Automation rules
- 5.1 Triggers
- 5.2 Conditions
- 5.2.1 by Standard fields
- 5.2.2 by Properties
- 5.2.3 By JQL
- 5.2.4 Combining conditions
- 5.3 Actions
- 5.3.1 Injectable variables
- 5.3.1.1 Versions specific
- 5.3.1.2 Packages specific
- 5.3.1.3 CHANGE related variables (for versions and packages)
- 5.3.1.4 TIME functions (or datetime offsets)
- 5.3.1.5 Previous WEBHOOK response
- 5.3.2 “Helpers“
- 5.3.2.1 Datetime formatting
- 5.3.2.2 Generic String functions
- 5.3.2.3 Trim HTML tags
- 5.3.2.4 Convert HTML to Wiki markdown
- 5.3.3 Important (!): IPs whitelisting
- 5.3.3.1 As of September 14, 2024
- 5.3.3.2 Till September 14, 2024
- 5.3.4 Action>Execute Webhook
- 5.3.4.1 Summary tab
- 5.3.4.2 Headers tab
- 5.3.5 Action>Invoke Jira Automation
- 5.3.6 Action>Update Version/Package
- 5.3.6.1 Update Tags
- 5.3.6.2 Update Description
- 5.3.6.3 Update Environments
- 5.3.6.4 Add Comment
- 5.3.6.5 Update Properties
- 5.3.6.6 Update .. (more to come)
- 5.3.7 Action>Send Slack message
- 5.3.8 Action>Send Teams message
- 5.3.8.1 How to get URL for Teams integration?
- 5.3.8.2 Plan B: Use Jira Automation
- 5.3.9 Action>Create Jira Issue
- 5.3.9.1 Creating sub-tasks
- 5.3.9.2 Additional issue fields (multiple use cases)
- 5.3.9.3 Plan B: Use Jira Automation
- 5.3.10 More actions
- 5.3.1 Injectable variables
- 5.4 Execution history
- 6 Troubleshooting Automation Rules
Introduction
We aim to be “One Stop Shop“ for Release Management in Jira. And Release Automation is one of the key elements on this pathway. With Jira Automation gaining the momentum in optimizing routine operations and improving efficiency of SDLC … we aim to apply it to Release Management process & practices.
Therefore below you will see a similar notion of Automation rules with Triggers, Conditions and Actions. If you are to scratch with Jira Automation you will feel right at home with Release Automation. Plus you can connect the two to gain Ultimate Automation.
Successor of “Outcoming WebHooks“
For some time we had https://releasemanagement.atlassian.net/wiki/spaces/RMC/pages/2430074881 functionality that our clients successfully used to notify audiences about release status change or trigger certain actions either via Jira Automation or “hook”ing 3rd party system (e.g. CI/CD tools, etc.)
The below is a logical evolution of Outcoming Hooks to
Add all possible triggers
Add flexible options for conditions
Humanize actions via outcoming hooks.
At some point of time we will disable and option to create new “Outcoming WebHooks“ and clone existing to deprecate this functionality after decent transition time as we truly believe that Release Automation is what our clients need for automating their release management use cases.
How to create “former“ WebHooks with “new“ Release Automation
If you want to migrate your old WebHooks or use new functionality the old way meanwhile .. here’s a step by step guide to do so.
Step1. Create automation rule
Step 2. Select Version/Package moved as Trigger
Step 3. Add new Field condition
Step 4. Select status and short list the column(s) as you used to do with Webhooks
Step 5. Add Action were you can see all the actions you used to have in WebHooks. Copy configurations if required.
Integration with Jira Automation
Conceptually our Automation rules are very similar to Jira Automation - triggers, conditions, actions. They could also be easily integrated - you can call a hook from Release Automation to cause execution of Automation rule in Jira (via Incoming webhook as Trigger).
This opens up an endless opportunity to `do any changes you want in Jira following the change in Release Management.
Examples could be found here - https://releasemanagement.atlassian.net/wiki/spaces/RMC/pages/2514157660.
Release Automation rules
In Release Management you can create multiple automation rules.
To do so click on Board Settings and find Automation section on the left.
To create new rule click on Add rule on top left. to Edit existing one just click on it.
For each rule you need to specify couple of basic parameters
Name to differentiate your rules
Status - Active / SUSPENDED
Version/Package toggle (Version includes Fix Versions, Epics, Sprints and JQL Versions)
You can change the scope between Version/Package only upon creation. When you edit the rule it’s not possible. The reason is simple - triggers, conditions and actions have became very scope awere and scope specific to allow change on the fly.
The main essence of the rule is 3 core elements - Trigger, Conditions and Actions. The following sections outline all 3 in details.
Triggers
We support a great variety of triggers.
If you are lacking something we are probably working on it. Just reach out to our support and help us prioritize remaining accordingly.
The aim is to have any possible change to version and/or package as a trigger.
Conditions
by Standard fields
At the moment we support only Status change for versions and properties. This is in backlog to add all other applicable standard fields to conditions
To add condition to your rule click on Conditions drop down to check all the available options. Select the one that suits you most.
Based on condition you will have a configuration dialog to specify other necessary details to be applied
e.g. In example below we what to apply condition for version status change and shortlist a subset of statuses we are interested.
by Properties
You can also add conditions by https://releasemanagement.atlassian.net/wiki/spaces/RMC/pages/2464579589.
To do so select Property condition in Condition look-up
This will allow you to choose from existing Custom properties list for version or package (depending on your automation scope)
Specify the rule and click Add.
By JQL
You can also add conditions by JQL that will be applied to your scope (issues) of version/package (depending of automation scope).
Select JQL condition in Condition look-up
This will allow you to specify JQL and define the rule. You can also inject custom properties in your JQL if required.
Click Add.
Combining conditions
Once you have multiple conditions defined you can switch between OR/AND options for the conditions to be executed.
Actions
Below you will find a list of actions you can execute upon your Tigger and Condition met. But also you can pass on a great deal of version/package data and properties into those actions. Plus you can get a great benefit of some “helpers”, namely formatting capabilities and JS-like functions for data transformations.
Injectable variables
You are able to inject the following variables to the action/hook URL & Request body:
Versions specific
version id
version name
version description
version start date
version release date
link to version (deep link url to navigate to version details)
project name (the version belongs to)
project key
project id
user name (who is making a change causing the trigger to execute automation rule)
status id (internal id of the column/status or version workflow)
status name
VERSION CUSTOM PROPERTIES
Packages specific
package id
package name
package description
package start date
package release date
link to package (deep link url to navigate to package details)
package version id’s (versions encompassing the package)
package project id’s (projects of the versions encompassing the package)
user name (who is making a change causing the trigger to execute automation rule)
status id (internal id of the column/status or version workflow)
status name
PACKAGE CUSTOM PROPERTIES
CHANGE related variables (for versions and packages)
change entity name (e.g. version | package | milestone | environment name)
change entity type
change entity description
change property name (property of the entity changed - standard or custom)
change property old value
change property new value
TIME functions (or datetime offsets)
You can also insert the following time functions. The App will insert an appropriate Macro that is also editable. Datetime formatting functions are the same as listed in following section.
Name | Macro inserted | Other examples |
---|---|---|
Date Offset | {{date.now(0,"dd/MM/yyyy”, ”GTM+1”)}} - today |
|
Start of Week | {{date.startOfWeek(0,"dd/MM/yyyy”, ”GTM+1”)}} - start of the week |
|
End of Week | {{date.endOfWeek(0,"dd/MM/yyyy”, ”GTM+1”)}} - end of the week |
|
Start of Month | {{date.startOfMonth(0,"dd/MM/yyyy”, ”GTM+1”)}} - start of this month |
|
End of Month | {{date.endOfMonth(0,"dd/MM/yyyy”, ”GTM+1”)}} - end of month |
|
Start of Year | {{date.startOfYear(0,"dd/MM/yyyy”, ”GTM+1”)}} - start of the year |
|
End of Year | {{date.endOfYear(0,"dd/MM/yyyy”, ”GTM+1”)}} - end of the year |
|
Previous WEBHOOK response
You can also have access to previous WebHook response data, namely:
prevWebhookData.headers
prevWebhookData.body
prevWebhookData.code
e.g. If your previous webhook returns a list of versions you can access it via
prevWebhookData.body.versions[0].id
“Helpers“
Datetime formatting
Therefore, we support .formatDate(param1, param2)
function where
param1 is your date/time
param2 is optional and represent the desirable timezone, otherwise GMT will be used
Examples:
.formatDate('MMM dd, yyyy HH:mm:ss','GMT+3')
.formatDate('yyyy/MM:dd HH:mm','GMT+4:30')
.formatDate('yyyy/MM:dd')
Here’s a link to supported formats https://date-fns.org/v2.30.0/docs/format.
Generic String functions
To finetune your web hooks even further you can use JS-like function for injectable variables in URL & Request body sections of the hook. Below is a list of functions that could be used:
concat() - concatenates the string arguments to the calling string and returns a new string
{{entity.name.concat('-version')}}
equals() - returns boolean true/false if a calling string matches (exactly) the argument
{{entity.name.equals('version')}}
isEmpty (not exist) - returns boolean true/false if a calling string is empty
split (string regex) - divides a calling string into an ordered list of substrings by searching for the pattern, puts these substrings into an array, and returns the array. So, you can use .split(pattern)[index] to pickup the right element of the array. If used only .split(pattern) it will return a string of comma separated substrings.
slice (int beginIndex, int endIndex) - extracts a section of a string and returns it as a new string, without modifying the calling string
toLowerCase() - returns the calling string value converted to lower case
toUpperCase() - returns the calling string value converted to UPPER case
trim() - removes whitespace from both ends of a string and returns a new string, without modifying the original string
replaceAll (string regex, string replacement) - returns a new string with all matches of regex a replaced by a replacement
Trim HTML tags
Some standard or custom properties might include HTML tags so when used in outcoming hooks not properly received in final destination. e.g. Slack and Teams hooks.
trimHTMLTags() - returns string with erased HTML tags
Convert HTML to Wiki markdown
Instead of trimming HTML tags you might also convert HTML to Wiki markdown and use it elsewhere.
htmlToWiki() - returns string with converted HTML to Wiki markdown
Important (!): IPs whitelisting
Webhooks are outcoming requests from our servers. If you want to receive these requests in your internal network (probably protected by Firewall) you need to while list IPs.
As of September 14, 2024
AWS IPs |
---|
3.134.160.237 |
Till September 14, 2024
Hetzner IPs |
---|
135.181.149.107 |
157.90.227.168 |
162.55.36.74 |
Action>Execute Webhook
Once you select Execute Webhook in the actions list a dialog will popup to specify the details.
Summary tab
This tab contains the main properties of the hook
Description to outline the details of what the hook is doing/aiming.
Method. HTTP method which will be used for the webhook. Available options are:
GET
POST
PUT
DELETE
URL. The URL which will be called from the our server while the webhook execution.
Request body. The request body which will be used while the webhook execution. For instance, it could contact XML or JSON.
Headers tab
On the headers tab, you can define headers for the webhook HTTP request.
The headers could be added in Key-Value format. Multiple headers are supported.
You can also use variables to define headers keys and values (e.g. use authorization ticket you received with previous request).
To Secure your headers turn on Hidden so the App will hide it and encrypt it.
Action>Invoke Jira Automation
Step 1: Create Jira Automation rule
Go to your project and click on Automation to create one.
For the trigger select Integrations and Incoming webhook.
Select “No issues from the webhook“
Click Save.
Step 2: Propagate Jira Automation URL into the App
In the App select Invoke Jira Automation from list of Actions and paste the URL you got from Jira Automation of the previous step. Thi is how you create the bridge between Release Automation and Jira Automation.
Step 3: Add Action in Jira Automation you need
Keep creating your new rule in Jira or edit existing one to create the action you need.
You can use the following standard parameters we are sending from Release Automation to Jira Automation:
webhookData.entityId
- version or package IDwebhookData.entityName
- version or package NamewebhookData.entityDescription
- version or package DescriptionwebhookData.entityDescriptionPlainText
- version or package Description with TrimHTML function applied
webhookData.startDate
- version or package Start DatewebhookData.releaseDate
- version or package Release DatewebhookData.entityLink
- version or package Deep Link so you can access it from any external systemwebhookData.entityJQL
- version or package JQL that defines the scope of release (Jira Issues)webhookData.projectName
- project Name for Fix Versions or Epics, comma separated project names for Cross-Project Versions, empty for Sprints and JQL versionswebhookData.projectKey
- project Key for Fix Versions or Epics, comma separated project keys for Cross-Project Versions, empty for Sprints and JQL versionswebhookData.projectId
- project ID for Fix Versions or Epics, comma separated project ids for Cross-Project Versions, empty for Sprints and JQL versionswebhookData.epicKey
- Epic Key for Epic-based Virtual Versions.webhookData.statusId
- destination ID of the Column where entity sits post actionwebhookData.statusName
- destination Name of the Column where entity sits post actionwebhookData.executorName
- User Name who triggered Release Automation rule led to executing a hookwebhookData.environmentIds
- Environment IDs for version or package (all the versions in the package)webhookData.environmentNames
- Environment Names for version or package (all the versions in the package)webhookData.changedEntityName
- Name of the entity that changes triggering the rule. See EntityType.webhookData.changedEntityType
- Type of the entity that changes triggering the rule. Could be: Version, Epic, Sprint, JQL Version, Package, Milestone, Environment, Comment, Custom PropertywebhookData.changedEntityDesription
- Description of the entity that changes triggering the rule. See EntityType.webhookData.changedEntityDesriptionPlainText
- Description with TrimHTML function applied of the entity that changes triggering the rule. See EntityType.
webhookData.changedPropertyOldValue
- Old Value of the property that changed - standard or customwebhookData.changedPropertyOldValuePlainText
- Old Value with TrimHTML function applied of the property that changed - standard or custom
webhookData.changedPropertyNewValue
- New Value of the property that changed - standard or customwebhookData.changedPropertyNewValuePlainText
- New Value with TrimHTML function applied of the property that changed - standard or custom
webhookData.changedPropertyName
- Name of the property that changed - standard or customwe are also sending a list of custom properties. you can access it via
webhookData.
"Custom Property Name“ - the way you define name in Properties configurationImportant: in case of multi select property value comes as comma separated selections
Important: in case of multi user property value comes as comma separated user names
E.g. use case: Send Email notification
Navigate to https://releasemanagement.atlassian.net/wiki/spaces/RMC/pages/2514157660/Automation+Use+Cases+incl.+Integration+with+Jira+Automation#%E2%9E%A1%EF%B8%8F-Send-email-upon-Release-status-change section of this documentation.
Action>Update Version/Package
Another type of action you can define is updating your version/package (based on the rule definition - whether it’s for version or package).
Update Tags
Click on Tags toggle and specify Tags you want to add to version/package or replace with those tags
Click Add
Update Description
Click on Description toggle and specify Description you want to add to version/package or replace existing description with new one.
You can also decide if you want to use plain text vs HTML editor.
Click Add
Update Environments
Click on Environments toggle to append version environments with designated one. You can also replace the original list with new one.
Click Add
Add Comment
Click on Add comment toggle to specify what comment you want to add upon executing the automation rule. Very good feature to keep audit trail on all the changes happening.
Click Add
Update Properties
Click on Properties toggle and add version/package properties from the list you want to alter.Depending on the property type you can either replace with a new value or append new value
Click Add
Update .. (more to come)
Our backlog is full of stories for other actions to update most of version/package details. We take it according to the priority. If you want to us to prioritize smth please reach out to our support.
Action>Send Slack message
If you select Send Slack message action we will pre-populate webhook URL and Body so you can amend it with your org details.
How to get URL for Slack integration?
Step 1. Navigate to https://api.slack.com/apps?new_app=1 to create an app “From scratch“
Step 2. Choose the name of the App (integration) and a space to send notifications
Step 3. Enable “Incoming Webhooks”
Step 4. Activate it and add new Webhook
Step 5. Allow integration and choose the destination channel from the selected space
Step 6. Copy URL for Slack integration
Tips and Tricks on “How to construct Slack Message“
We are using Slack Block Kit to construct the messages.
Plan B: Use Jira Automation
If you have any difficulties with above or find it easier to configure in Jira because you already have such actions configured there .. feel free to configure Slack Notifications in Jira and use https://releasemanagement.atlassian.net/wiki/spaces/RMC/pages/2522284033/Release+Automation+Explained#%F0%9F%A4%96-Action%3EInvoke-Jira-Automation-(coming-soon) to setup a bridge.
Action>Send Teams message
If you select Send MS Teams notification action we will pre-populate webhook URL and Body so you can amend it with your org details.
How to get URL for Teams integration?
Step 1. Go to the channel where you want to add the webhook and select ••• More options from the top navigation bar.
Step 2. Select Connectors from the dropdown menu:
Step 3. Search for Incoming Webhook and select Add.
Step 4. Select Configure, provide a name, and upload an image for your webhook if required:
Step 5. The dialog window presents a unique URL that maps to the channel. Copy and save the Teams integration URL, to send information to Microsoft Teams and select Done:
Plan B: Use Jira Automation
If you have any difficulties with above or find it easier to configure in Jira because you already have such actions configured there .. feel free to configure Teams Notifications in Jira and use https://releasemanagement.atlassian.net/wiki/spaces/RMC/pages/2522284033/Release+Automation+Explained#%F0%9F%A4%96-Action%3EInvoke-Jira-Automation-(coming-soon) to setup a bridge.
Action>Create Jira Issue
Another action you can define is Creating Jira issue. There could be multiple use cases for it, but what we have heard from the clients the most is the following:
Ticket for end-to-end regression
Ticket for CAB approval (Change Management Board)
Ticket for DevOps to deploy for lower or production environment
Ticket for Marketing Team to start experiment
etc.
To make one click on Add action pull up to choose Create Issue
Create issue dialog will show up where you can specify
Project where you want to create issue (projects will be filtered by your permissions - actor permissions)
Issue type
Issue parent (for subt-tasks only)
Issue summary
Issue description
Additional fields (see below)
Actor upon which Create issue will run (permissions will be verified)
In all - summary, description & additional fields - you can inject variable of versions/packages and change related items.
Creating sub-tasks
If you select sub-task issue type the App will automatically suggest you to select parent standard issue type from the selected project
Additional issue fields (multiple use cases)
There are certain limitations, namely
we can't show you standard Issue Creation dialog to specify other standard and custom fields
we do not know what are the mandatory fields you heave setup for your issue type
To overcome this we created a possibility to add additional fields in JSON format. Thus you can specify mandatory fields and/or any other fields you would like to setup upon issue creation.
Plan B: Use Jira Automation
If for some reason you are missing smth in the App and can’t create issues you need please reach out to our support. Meanwhile you can do a work around via Jira Automation bridge - trigger a hook there, pass over the payload you need from the App and create/update issue via one of the Actions in Jira Automation. Read more details about our https://releasemanagement.atlassian.net/wiki/spaces/RM4J/pages/2514485249.
More actions
Execution history
You can see the history of all the automation rules execution. To do so click on any of the rules and navigate to History tab.
Click Show more the execution you are interested it to receive the details about Trigger, Action (both Request and Response).
Troubleshooting Automation Rules
Tips: How to troubleshoot?
Typical failed cases
Use case | Troubleshooting guide |
---|---|
Release Automation returns 200 but Jira Automation is not invoked |
|