Skip to content

CLAUDE.md

Latest commit

 

History

History
181 lines (133 loc) · 7.31 KB

CLAUDE.md

File metadata and controls

181 lines (133 loc) · 7.31 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This repository contains sample ScriptRunner plugins for Atlassian products (Jira, Confluence, and Bitbucket). These plugins demonstrate how to create custom scripts that extend Atlassian product functionality using Groovy.

Reference documentation:

Repository Structure

The repository is organized as a multi-module Maven project:

├── jira/           - Jira ScriptRunner samples
├── confluence/     - Confluence ScriptRunner samples
└── bitbucket/      - Bitbucket ScriptRunner samples

Each module:

  • Uses product-specific parent POMs from Adaptavist (e.g., scriptrunner-jira-standard, scriptrunner-confluence-standard, scriptrunner-bitbucket-standard)
  • Contains Groovy scripts in src/main/resources/com/adaptavist/ and src/main/resources/com/example/
  • Has integration tests in src/test/groovy/it/com/adaptavist/ using Spock framework
  • Packages as an atlassian-plugin

Common Commands

Prerequisites

These commands require:

  • Atlassian SDK (atlas-mvn) - Install following the Atlassian SDK documentation
  • Java 11 or later - The project is configured for Java 11 (Jira requires Java 11+)

Building

Build all modules from the root:

atlas-mvn clean install

Build a specific product module:

cd jira
atlas-mvn clean install

Running Integration Tests

Run tests for a specific module:

cd jira
atlas-mvn integration-test

Run a single test:

cd jira
atlas-mvn integration-test -Dit.test=CustomEventListenerIT

Running with Atlassian Product

Start Jira with the plugin installed (in debug mode):

cd jira
atlas-mvn jira:debug -U

Start Confluence with the plugin installed (in debug mode):

cd confluence
atlas-mvn confluence:debug -U

The -U flag forces Maven to update snapshots and releases from remote repositories, useful if parent POM versions have been updated.

Note on Bitbucket: Running Bitbucket locally requires additional setup (git server/sidecar configuration). The Bitbucket module can be built and tested, but running the full application may require extra infrastructure.

Architecture

ScriptRunner Configuration Files

Each module contains a scriptrunner.yaml file in src/main/resources/ that defines:

  • scriptListeners - Event listeners that react to product events
  • restConfigItems - REST endpoint configurations
  • fragmentConfigItems - UI customizations (web items, panels)
  • scriptJobs - Scheduled jobs (Confluence/Jira)
  • customSearchFields - Custom Confluence search fields
  • cqlFunctions - Custom CQL functions

The YAML file references Groovy scripts via the scriptPath or clazz field (e.g., com/adaptavist/CustomEventListenerScript.groovy). ScriptRunner reads this descriptor and automatically registers the scripts with the Atlassian product.

Script Types by Product

Jira:

  • Custom Event Listeners (e.g., CustomEventListenerScript.groovy) - React to Jira events like project creation
  • REST Endpoints (e.g., SampleRest.groovy) - Custom REST APIs using CustomEndpointDelegate

Confluence:

  • Custom CQL Functions (e.g., CustomCqlFunctionScript.groovy) - Extend Confluence Query Language
  • Custom Search Fields (e.g., CustomSearchFieldScript.groovy) - Add custom searchable fields
  • Custom Event Listeners (e.g., CustomEventListenerScript.groovy)
  • REST Endpoints (e.g., SampleRest.groovy)

Bitbucket:

  • Pre-receive Hooks (e.g., SamplePreHook.groovy) - Validate commits before acceptance
  • REST Endpoints (e.g., SampleRest.groovy)

Script Plugin Pattern

All scripts follow the ScriptRunner plugin pattern:

  1. Scripts are placed in src/main/resources/ with appropriate package structure
  2. ScriptRunner automatically discovers and registers these scripts at runtime
  3. Scripts use @BaseScript annotation to declare their type (e.g., CustomEndpointDelegate for REST endpoints)
  4. Event listener scripts access the event object via implicit event variable

Testing Pattern

Integration tests use Spock framework and run against actual Atlassian product instances:

  • Tests extend Specification class
  • Use @Shared for expensive-to-create objects
  • Access Atlassian APIs via ComponentAccessor
  • Tests verify that script behaviors work correctly in the product context

Dependencies

  • Parent POMs handle most dependencies automatically
  • Custom dependencies can be added to each module's pom.xml
  • All modules require access to the Adaptavist Nexus repository at https://nexus.adaptavist.net/content/repositories/external

Product Versions

Current versions configured in module POMs:

  • Parent POM version: 89 (scriptrunner-*-standard)
  • Java: 17 (explicitly set via maven.compiler.source/target)
  • Jira: 10.3.8 (requires Java 17 minimum)
  • Confluence: 9.2.6 (supports Java 17 and 21)
  • Bitbucket: 9.4.8 (bundles Java 17.0.13)

To change product versions, update the respective property in each module's pom.xml. If you encounter repository resolution issues with the parent POM, version 89 is known to work.

Note on Java versions: Jira 10.3+ was compiled with JDK 17 and does not support Java 8 or 11. All modules are configured to compile with Java 17 for maximum compatibility.

Development Notes

  • The ScratchScript.groovy files in com.example package are templates for quick experimentation
  • Logging levels can be configured in each module's POM via the logging.levels property
  • Jira module includes optional configurations for Jira Software and Service Desk (commented out by default)

Experimental Branches

The repository has several branches with alternative configurations that may be useful references:

bugfix/listener-registration

  • Uses parent POM version 34 (much older than current 89)
  • Older product versions: Jira 8.13.25, Confluence 7.13.9, Bitbucket 7.17.10
  • Uses https://nexus.adaptavist.com instead of https://nexus.adaptavist.net
  • Package paths use dots instead of slashes: com.adaptavist/ vs com/adaptavist/
  • Tests extend SrSpecification instead of Specification
  • Simplified scriptrunner.yaml files (removed REST, web items, jobs examples)
  • May be useful if encountering listener registration issues

feature/test-service-implementation

  • Targets Jira 11.0.0 compatibility
  • Completely different approach: uses JAR packaging instead of atlassian-plugin
  • No parent POM dependency - manually defines all dependencies
  • Includes Java service implementation with Jakarta Inject for JDK 21
  • Uses custom MANIFEST.MF
  • Represents a fundamentally different plugin architecture

task/platform-7-compatibility

  • Updates for Platform 7 compatibility
  • Bumps Bitbucket to latest Platform 7 supported version

Version History

  • Master is currently at parent POM version 90 (may have resolution issues)
  • Version 89 (current) is stable
  • Many intermediate versions (88, 87, 86...) are available in commit history