Git Integration + ScriptRunner

ScriptRunner for Jira Data Center/Server is an app available on the Atlassian Marketplace that allows you to extend Jira functionality through the use of built-in and custom groovy scripts. It provides administrators with an in-line editor where you can write groovy scripts.

These scripts can be scheduled as a job or to be run on an issue transition within Jira workflows or etc. Out-of-the-box, you can find several built-in scripts ready to go, or you may try some recipes to start using a bit of groovy for custom scripts.

Available APIs

Which APIs or functions can be used while creating these scripts? See ScriptRunner API quick reference at Adaptavist.

A singleton implementing GIJFacade interface is the main object having methods for all the above cases.

Feature use case examples

• The API allows you to write a script for re-associating git commits from one issue to another. With this script, you won’t have to click each git commit and manually re-assign it to another issue.

• Use a script to create a pull request if an issue has been moved to CODE REVIEW status.

Tutorial

Follow the order of steps below:

• Available APIs
• Feature use case examples
• Tutorial
• Getting started with ScriptRunner plugin
• Example 1: How to create a simple script?
• Example 2: How to log?
• Example 3: How to log more than a brief information?
  • So how does it work?
• Example 4: Move an issue in “IN PROGRESS” status when at least one git commit exists
• How to integrate the code into workflow? How to customize it by dynamic IN issueKey parameter?
• Let’s test it
• See more Git Integration for Jira app features

For more example scripts, see GIJFacade JavaDocs.

Getting started with ScriptRunner plugin

For Jira Server/Data Center, you will need to download and install ScriptRunner plugin from the Atlassian Marketplace.
No further GIJ configuration is required.

Downloading the app

1. Go to ScriptRunner for Jira at Atlassian Marketplace and start the free trial or buy it now.

2. Login to your Atlassian account when prompted and generate a new license for the trial.

3. IMPORTANT! Make sure to copy your license and save it.

4. Click Download to download the app to your local system.

Installing the app

REQUIRES ADMIN ACCESS

1. On your Jira Server/Data Center instance, navigate to Manage apps (Jira settings ➜ Manage apps ➜ Manage apps).

   
   

2. Click Upload app and locate the downloaded ScriptRunner JAR file.

3. After the installation, look under the User-installed apps and open the ScriptRunner for Jira tab.

4. Paste the license key into the provided box then click Update.

Example 1: How to create a simple script?

REQUIRES ADMIN ACCESS

Preconditions:

• GIJ plugin is installed.
• One or more repository is connected.
• A Jira issue (e.g. TST-4) having git commits association in the Git Commits issue tab.

If one of the above conditions is not met, the script will return an empty list.

Steps:

• Open ScriptRunner console (Jira settings ➜ Manage apps ➜ ScriptRunner Console). Here you can experiment with scripts, debug scripts, and execute scripts.

  
  

• Input the next code:

  import com.onresolve.scriptrunner.runner.customisers.WithPlugin
  import com.onresolve.scriptrunner.runner.customisers.PluginModule
  @WithPlugin("com.xiplink.jira.git.jira_git_plugin")
  import com.bigbrassband.jira.git.services.GIJFacade;
  
  @PluginModule
  GIJFacade gijFacade;
  
  gijFacade.getCommitsForIssue("TST-4");

• Press the “Run” button

  
  

• A result of the last operation is displayed at the bottom in “Result” tab.

  In our case the last operation is gijFacade.getCommitsForIssue("TST-4"); so the tab displays a list of commits associated with issue “TST-4.

Example 2: How to log?

• Pay close attention to the “Logs” tab at the bottom. There can be a lot of logs while there is only one result.

  Use log.warn("Your message") to log something.

• Do a log for commits and number of changed files. Enter the following script in the ScriptRunner console:

  import com.onresolve.scriptrunner.runner.customisers.WithPlugin
  import com.onresolve.scriptrunner.runner.customisers.PluginModule
  @WithPlugin("com.xiplink.jira.git.jira_git_plugin")
  import com.bigbrassband.jira.git.services.GIJFacade;
  @WithPlugin("com.xiplink.jira.git.jira_git_plugin")
  import com.bigbrassband.jira.git.rest.publicmodels.Commit;
  import java.util.function.Consumer;
  
  @PluginModule
  GIJFacade gijFacade;
  
  gijFacade.getCommitsForIssue("TST-4", true)
      .stream()
      .forEach(new Consumer<Commit>() {
          @Override
          public void accept(Commit commit) {
              log.warn("commit " + commit.getCommitId());
              log.warn("\t number of files changed - " +commit.getFiles().size());
          }
      }
  );

• Click the “Run” button.

• Switch to the “Logs” tab.

  
  

Example 3: How to log more than a brief information?

• As mentioned above, a commit is logged using brief information by default.

  For example, files are not logged but are present in commit objects when you retrieve them with help of gijFacade.getCommitsForIssue("TST-4", true).

  Refer to Commit JavaDocs and log commits with files in a nice-looking format. Enter the following script in the ScriptRunner console:

  import com.onresolve.scriptrunner.runner.customisers.WithPlugin
  import com.onresolve.scriptrunner.runner.customisers.PluginModule
  @WithPlugin("com.xiplink.jira.git.jira_git_plugin")
  import com.bigbrassband.jira.git.services.GIJFacade;
  @WithPlugin("com.xiplink.jira.git.jira_git_plugin")
  import com.bigbrassband.jira.git.rest.publicmodels.Commit;
  @WithPlugin("com.xiplink.jira.git.jira_git_plugin")
  import com.bigbrassband.jira.git.rest.publicmodels.Commit.ShortFileInfo;
  import java.util.function.Consumer;
  
  @PluginModule
  GIJFacade gijFacade;
  
  gijFacade.getCommitsForIssue("TST-4", true)
      .stream()
      .forEach(new Consumer<Commit>() {
          @Override
          public void accept(Commit commit) {
              log.warn(commit.getCommitId());
              commit.getFiles()
                  .stream()
                  .forEach(new Consumer<ShortFileInfo>() {
                      @Override
                      public void accept(ShortFileInfo file) {
                          log.warn("\t\t" + file.getPath());
                      }
                  });
          }
      }
  );

• Switch to the “Logs” tab. Here you can see the commits with files. It now looks great when viewed.

  
  

So how does it work?

Looking back at the original script, see how it was changed:

• We’ve added more imports to avoid compilation error

• We’ve called gijFacade.getCommitsForIssue("TST-4", true) instead of gijFacade.getCommitsForIssue("TST-4"). Otherwise, the list of files will be empty.

• We’ve looped throughout the commits:

  gijFacade.getCommitsForIssue("TST-4", true)
      .stream()
      .forEach(new Consumer<Commit>() {
          @Override
          public void accept(Commit commit) {        
              log.warn(commit.getCommitId());
              ...
          }
      }
  );

• and then, looped throughout the files belonging to each commit:

  ...
      commit.getFiles()
      .stream()
      .forEach(new Consumer<ShortFileInfo>() {
          @Override
          public void accept(ShortFileInfo file) {
              log.warn("\t\t" + file.getPath());
          }
      });
  ...

Example 4: Move an issue in “IN PROGRESS” status when at least one git commit exists

Let’s write, debug a code and detect whether an issue has at least one git commit:

• Open ScriptRunner console (Jira settings ➜ Manage apps ➜ ScriptRunner Console).

• Use the next code:

  import com.onresolve.scriptrunner.runner.customisers.WithPlugin
  import com.onresolve.scriptrunner.runner.customisers.PluginModule
  @WithPlugin("com.xiplink.jira.git.jira_git_plugin")
  import com.bigbrassband.jira.git.services.GIJFacade;
  
  @PluginModule
  GIJFacade gijFacade;
  
  String issueKey = "TST-4";
  !gijFacade.getCommitsForIssue(issueKey).isEmpty();

• Click Run.

• Open Result tab.

  Result: "true"

• Assign a Jira issue key value to the String issueKey variable. For example: String issueKey = "TST-4"; The above code will return true if the Jira issue has git commits and false if it doesn’t.

How to integrate the code into workflow? How to customize it by dynamic IN issueKey parameter?

The steps below demonstrate the general rule of using gijFacade in ScriptRunner features:

• Create a ScriptRunner Listener which will be triggered by adding a comment to an issue. If the issue has git commits, the listener will transition the issue to the IN PROGRESS status.

  • Open ScriptRunner Listeners (Jira settings ➜ Manage apps ➜ ScriptRunner Listeners).

    
    

  • Click Create Listener.

  • Find and choose Fast-track transition an issue.

    
    

  • Set up the new listener.

    
    

  • Set Event to Issue Commented.

  • Use the following code into the Condition field:

    import com.onresolve.scriptrunner.runner.customisers.WithPlugin
    import com.onresolve.scriptrunner.runner.customisers.PluginModule
    @WithPlugin("com.xiplink.jira.git.jira_git_plugin")
    import com.bigbrassband.jira.git.services.GIJFacade;
    
    @PluginModule
    GIJFacade gijFacade;
    
    String issueKey = issue.key;
    !gijFacade.getCommitsForIssue(issueKey).isEmpty();

  • Set Action to Start Progress.

  • Under Transition Options — tick on the following:

    • Skip Permissions,
    • Skip Validators,
    • Skip Conditions (just in case)

  • Click Add.

Let’s test it

1. Open the TST-4 Jira issue, which is in OPEN status and has associated git commits.

2. Add comment Some comment.

Result:
The Jira issue status becomes IN PROGRESS because it has git commits.

See more Git Integration for Jira app features

Manager permissions (Git Integration for Jira Data Center)

Cancel indexing (Git Integration for Jira Data Center)

Pull request filters (Git Integration for Jira Data Center)

Tag filters (Git Integration for Jira Data Center)

Indexing queue viewer (Git Integration for Jira Data Center)

Deep linking feature (Git Integration for Jira Data Center)

GitHub App integration (Git Integration for Jira Data Center)

Git Integration + ScriptRunner (this page)

Git Integration + Jira Automation (Git Integration for Jira Data Center)

Enforced git permissions for Jira users – Features (Git Integration for Jira Data Center)

Shared reindex queue between DC nodes (Git Integration for Jira Data Center)

Smart commits overview (Git Integration for Jira Data Center)

Associate Pull/Merge Requests to Issues Based on Commits (Git Integration for Jira Data Center)

Creating branches (Git Integration for Jira Data Center)

Creating pull/merge requests (Git Integration for Jira Data Center)

Issue Git integration panel – Features (Git Integration for Jira Data Center)