Git Integration for Jira Self-Managed (Data Center/Server) Documentation

Contact Support: Server  
Contact Support: Data Center  

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.

The Git Integration for Jira app provides additional Java API (GIJFacade interface) allowing you to operate with git information. The API is close to Git Integration for Jira REST API and provides similar functionality (and more):

  • Repositories – get list of repositories connected, create/delete/update a repository
  • Integrations – get list of integrations connected, create/delete/update an integration
  • Reindex – start a reindex of repository/integration, check whether the reindex is finished
  • Commits – get commits associated with an issue, change a commit issue association
  • Branches – get branches associated with an issue, create/delete branch
  • Tags – get tags associated with an issue

One main implementation in the 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:

  • Getting started with ScriptRunner plugin

  • Example 1: a simple script for retrieving list of commits associated with issue TST-4

  • Example 2: a simple script for logging number of files changed in each commit of issue TST-4

  • Example 3: a script listing files changed in each commit of issue TST-4

  • Example 4: a setup of issue workflow in a such way that if an OPEN issue has at least one git commit then it’s moved to IN PROGRESS status

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.

Please be aware that a brief information of the objects are logged by default. For instance, each commit object in the list contains much more information about a commit which can be acquired programmatically. See Commit class javadocs to find a full list of information provided.

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.

Have feedback about this article? Did we miss something? Let us know!
On this page