In this page

What are automation triggers?

Every rule starts with a trigger. They kick off the execution of your rules based on various events:

  1. The built-in triggers provided by the Automation for Jira app listen for the events in Jira. For example, as when an issue is created or when a field value is changed. There is a separate trigger to run automations based on a schedule.
  2. The DevOps triggers discussed in this page and provided by the Better DevOps Automation app listen for the events in the Version Control System (Git, Bitbucket, GitHub, GitLab, Subversion, Mercurial, etc.). For example, when new commits are pushed to the repository or when a new tag is created.

Triggers can be configured before being applied to a rule.

Semantics of DevOps triggers

This section explains what triggers are invoked, how many times and in what order when pushing changes to the Version Control System.

Starting DevOps automation rules

What happens with the automation rules when a changeset (containing one or more commits) is pushed to the repository?

First, the changeset is verified against the commit policy, and...

  1. if it was accepted, then...
  2. otherwise...

Version Control System specific notes about how triggers work:

  • Git and Mercurial: automation rules are not triggered when the commits are created locally on the developer's machine. Those are triggered only when the commits are pushed to the central repository.
  • Subversion: changesets always contain exactly one commit. It is because SVN is a centralized version control system where "commit" and "push" are essentially the same operation.
  • Bitbucket: the Better Commit Policy for Bitbucket app triggers the automation rules only from version 5.0.0. (If you are using Bitbucket, make sure you're using a newer app version!)

Order of concurrent rule executions

As you see, pushing a single changeset can start the execution of multiple automation rules around the same time. It is very important to understand that the execution order of the rules is completely undefined and that the rules are executed concurrently (in parallel) and asynchronously (they don't wait for each other to complete)!

It means:

  • It is not guaranteed that the Changeset Accepted trigger starts before the Genius Commit Created starts with the first commit.
  • It is not guaranteed that the Genius Commit Created trigger starts with the Nth commit before it starts with the (N+1)th one.
  • It is not guaranteed that if the commit message is "FOO-1 BAR-1 @comment Bug fixed!", then the Genius Commit Created trigger starts with FOO-1 before BAR-1.
  • It is not guaranteed that if the commit message is "FOO-1 @comment Bug fixed! @status Done", then the Genius Commit Created trigger starts with the "@comment" command before the "@status" command.

Therefore, you should never rely on the execution order when configuring your automation rules! A robust rule should be independent from the result of other rules and from the state left behind by other rules.

(Re-)processing already existing commits

(for Git)

Distributed Version Control Systems allow the same commit (a commit with the same hash, to be precise) to appear on multiple branches. This is, however, important to avoid re-processing the same commit multiple times. It should be processed only the first time when it is accepted to the repository.

For example, if developer "alice" logs 2 hours of work to an issue in the commit message, it should be processed only when she pushes that commit the first time. If that commit is later merged from the feature branch to the release branch or from the release branch to the master branch, it should not be processed again, because the worklog would be created again and again.

Therefore, it's handled like this:

  • Git: our Git integration supports the detection of existing commits. Consequently, the Commit Created and Genius Commit Created triggers are invoked only once for the same commit if that's merged between branches. It guarantees that the automation rules that use these triggers are executed only once. (The identity of the commit is based on its hash which does not change when it is merged between branches.)
  • Mercurial: our Mercurial integration does not support the detection of existing commits yet. Consequently, the Commit Created and Genius Commit Created triggers may be invoked multiple times for the same commit if that's merged between branches. It may result in repeated execution of the automation rules that use these triggers. (It's a known limitation at the moment.)
  • Subversion: this problem does not exist with Subversion. (When merging a branch to another branch in Subversion, there is always a new commit created.)

Note that those triggers that work with the whole changeset are not affected by the existence of the individual commits in it. Only the Commit Created and the Genius Commit Created triggers are affected, because these are the only triggers that work with individual commits.

For example, if you push a changeset with new branches, new tags, and a mix of new and existing commits, the following will happen:

  • Changeset Accepted triggers kick off their rules.
  • Branch Created triggers kick off their rules.
  • Tag Created triggers kick off their rules.
  • Commit Created triggers kick off their rules, but only for the new commits.
  • Genius Commit Created triggers kick off their rules, but only for the new Genius Commits.

Bulk vs. concurrent execution

In terms of "issue cardinality", there are two modes to start an automation rule:

  • Concurrent mode: run for each issue separately.
  • Bulk mode: run only once for the collection of all issues.

Built-in triggers can be configured to execute in either mode. Due to current technical limitations, DevOps triggers always run in bulk mode (will change in future app versions!).

DevOps triggers

This section explains the additional triggers that the Better DevOps Automation app introduces to the Automation for Jira app. These can kick off automation rules based on Version Control System (Git, Bitbucket, GitHub, GitLab, Subversion, Mercurial, etc.) activity.

Changeset Accepted trigger

This trigger executes a rule when a new changeset is pushed to the Version Control System, and it is accepted because it satisfies the commit policy.

Configuring a changeset accepted trigger for a DevOps Automation for Jira rule

It should be used for the automations which take the accepted changeset as input (not the individual commits) and which should be triggered only once, regardless the number of commits. A typical example is sending a notification email with the summary of the changes.

This trigger supports the following smart values:

See the smart value reference for the complete list.

Changeset Rejected trigger

This trigger executes a rule when a changeset is pushed to the Version Control System, but it is rejected because it violates the commit policy.

Configuring a changeset rejected trigger for a DevOps Automation for Jira rule

For each changeset, either this or the Changeset Accepted trigger is invoked. In that sense, these two triggers are complementary and work similarly.

This trigger supports the following smart values:

See the smart value reference for the complete list.

Branch Created trigger

This trigger executes a rule when a new branch is created in the Version Control System.

Configuring a branch created trigger for a DevOps Automation for Jira rule

It should be used for the automations that take the new branch as input. An example is sending a quick Slack message to your team members.

This trigger supports the following smart values:

See the smart value reference for the complete list.

Tag Created trigger

This trigger executes a rule when a new tag is created in the Version Control System.

Configuring a tag created trigger for a DevOps Automation for Jira rule

It should be used for the automations that take the new tag as input. An example is running the Jenkins build which deploys your software to production when a new tag in the format "1.2.3" is created.

This trigger supports the following smart values:

See the smart value reference for the complete list.

Commit Created trigger

This trigger executes a rule when a new commit is created in the Version Control System.

Note that there is a related trigger which executes an automation rule when a parametric command is entered to the commit message. For example, you can create a commit with the commit message "Bug fixed! @deploy prod" and push it to start an automation rule which deploys your code to the instance "prod". If your use case requires commands and parameters, see the Genius Commit Created trigger instead. Otherwise, this is the trigger for you.

Configuring a Commit Created trigger for a DevOps Automation for Jira rule

It should be used for the automations that take the new commit as input. (If you merge an existing commit to a new branch, the rule will not be executed again.)

A typical example is transitioning the issue to "In Progress" automatically when a developer created a commit for the issue, but it was left in "To Do".

Note that this trigger executes the rule for all new commits, including:

  • Simple commits: All new non-merge commits.
  • Merge commits: All new merge commits.
  • Genius Commits: By definition, a Genius Commit is always a commit, but not vice versa. (Genius Commits are a subset of commits.)
    Therefore, for a new Genius Commit, both the Commit Created and the Genius Commit Created triggers will execute their rules. For a non-genius commit, only Commit Created will. Make sure that the rules have no overlapping functionality to avoid conflicts.

This trigger supports the following smart values:

See the smart value reference for the complete list.

Genius Commit Created trigger

This trigger executes a rule when a so-called Genius Commit is created in the Version Control System.

Genius Commits can use customizable commands to start customizable automation rules. By definition, a commit is a Genius Commit if its commit message contains one of those commands.

Genius Commits is a super-smart implementation of the original Smart Commit feature in Bitbucket. Being a more complex feature, it is discussed in the dedicated Genius Commits page. (Make sure you learn more about it, it will fundamentally change the way you practice DevOps!)

Note that there is a related trigger which executes an automation rule for all new commits (with or without commands). If your use case doesn't require commands and parameters, see the Commit Created trigger instead. Otherwise, this is the trigger for you.

Configuring a Genius Commit Created trigger for a DevOps Automation for Jira rule

It should be used for the automations that take the new commit as input. (If you merge an existing commit to a new branch, the rule will not be executed again.)

A typical example is transitioning an issue by parsing the new status name from the commit message like: 

FOO-1 Check against the null. @status Testing

This trigger supports the following smart values:

See the smart value reference for the complete list.

Questions?

Ask us any time.