Skip to end of metadata
Go to start of metadata
Table of Contents

About Plugins

Artifactory Pro allows you to easily extend Artifactory's behavior with your own plugins written in Groovy.

User plugins are used for running user's code in Artifactory. Plugins allow you to perform the following tasks:

  • Add scheduled tasks
  • Extend Artifactory with your own security realms
  • Change resolution rules
  • Manipulate downloaded content
  • Respond to any storage events on items and properties
  • Deploy and query artifacts and metadata
  • Perform searches
  • Query security information
  • Invoke custom commands via REST
  • Execute custom promotion logic
  • Provide information and strategies for Artifactory's Build Servers Plugins.

During the development phase, you can change plugin source files and have your plugins redeployed on-the-fly. You can even debug the plugin code using your favorite IDE.

Deploying Plugins

Place your plugin files under ${ARTIFACTORY_HOME}/etc/plugins.

Any file name ending with .groovy is loaded on startup. You can have multiple plugin files which are loaded in alphabetical order. Callbacks defined in plugins are called by the order they were loaded.

Auto Reload

By default, plugins are not reloaded after Artifactory has started-up. You can configure Artifactory to automatically detect plugin changes on disk or new plugin files and automatically reload them in runtime (plugin removals are not detected).

To do this, set the number of seconds to check for plugin updates to a number greater than 0, by changing the following property in ${ARTIFACTORY_HOME}/etc/artifactory.system.properties, or by specifying the property with -D to the JVM running Artifactory:

NOTE! that deleting or renaming plugin files while auto-reloading is active is not fully supported and requires an Artifactory restart.

Disabling Plugin Reloading for Production

Ensure plugin auto-reloading is disabled in a production environment.

Writing Plugins

Artifactory plugins are written as Groovy scripts in regular files and have a simple DSL to wrap users code in closures inside well-known extension points.

Scripts have a couple of helper objects that are globally bound (see the plugin script template).

The Artifactory Public API (PAPI)

Scripts have access to the full classpath of Artifactory.  However, the only API supported for plugins is the (info) Artifactory Public API, defined in the artifactory-papi.jar.

The artifactory-papi.jar can be found under WEB-INF/lib folder inside the artifactory.war.

Please see the Plugin Code Template and Sample Plugin below for more details.

IDE code completion

All major IDEs have good Groovy editing and debugging capabilities.

In order to make your developing experience complete, we provide support for our own DSL for IntelliJ IDEA. IntelliJ IDEA's Groovy DSL script for Artifactory User Plugins can be found in our GitHub repo.
Eclipse DSLD file is also available courtesy of James Carnegie.

Globally Bound Variables 

Variable NameVariable TypeComments
log

org.slf4j.Logger

Writes to Artifactory log
logger name is the name of the script file 
repositories

org.artifactory.repo.Repositories

Allows queries and operations on repositories
and artifacts 
security

org.artifactory.security.Security

Provides information about current security context,
(e.g. current user and her permissions) 
searches
org.artifactory.search.SearchesAPI for searching for artifacts and builds
Since 2.3.4 
builds

org.artifactory.build.Builds

Allows CRUD operations on builds
Since 2.6

Plugins Repository

Enhancing Artifactory with user plugins is community-driven effort.

If you are looking to go beyond Artifactory's out-of-the-box functionality take a look at already contributed plugins on GitHub, you might find what you are thinking about. If not, your contribution is very welcome!

Plugin Execution Points

The following table summarizes the available execution points. For more details about specific plugin look follow the section links.

Plugin Type

Code block name

When executed

Description

Download
Event Callback (with return values)
 
 
altResponse

On any download

Provide an alternative response, by setting a success/error status code value and an optional error message or by setting new values for the inputStream and size context variables (For succeeded resolutions).

altRemotePath

When reaching out to remote repositories

Provides an alternative download path under the same remote repository, by setting a new value to the path variable.

altRemoteContent

After fetching content from remote repositories

Provide an alternative download content, by setting new values for the inputStream and size context variables.
afterDownloadError
After failing during content fetching from remote repositoriesProvide an alternative response, by setting a success/error status code value and an optional error message or by setting new values for the inputStream and size context variables (For failed resolutions).

Event Callback (without return value)

 
 
beforeRemoteDownload
Before fetching content from remote repositoriesHandle before remote download events.
afterRemoteDownload 
After fetching content from remote repositoriesHandle after remote download events.
beforeDownload
On any download

Handle before download events.

beforeDownloadRequest
On any downloadHandle before download requset events, executed before Artifactory starts to handle the original client request, useful for intercepting expirable resources (other than the default ones like maven-metadata.xml).
Storage
Event Callback (without return value)
before/after
Create, Delete, Move, Copy,
PropertyCreate, PropertyDelete
Before / After selected storage operationHandle events before and after Create, Delete, Move and Copy operations
Jobs
Scheduled executionany valid Groovy (Java) literal as execution nameAccording to provided interval/delay or cron expression

Job runs are controlled by the provided interval or cron expression, which are mutually exclusive. The actual code to run as part of the job should be part of the job's closure.

Executions
User-driven executionany valid Groovy (Java) literal as execution nameBy REST callExternal executions are invoked via REST requests.
Realms
Event Callback (without return value)

any valid Groovy (Java) literal as realm name with nested blocks:

authenticate
userExists
During user authenticationNewly added realms are added before any built-in realms (Artifactory internal realm, LDAP, Crowd etc.). User authentication will be attempted against these realms first, by the order they are defined.
Build
Event Callback (without return value)
beforeSave 
Before the build info is saved in ArtifactoryHandle before build info save events
afterSave 
After the build info is saved in ArtifactoryHandle after build info save events
Promotions
User or build server driven executionany valid Groovy (Java) literal as promotion nameBy REST callPromotes integration (a.k.a. snapshot) build to be a release invoking any code associated with it.
Staging Strategy   
build server driven executionany valid Groovy (Java) literal as staging strategy nameDuring build server driven staging build configuration

The strategy provides the build server with the following information:

  • How the artifacts in the staged build should be versioned;
  • How the artifacts in the next integration build should be versioned;
  • Should the build server create a release branch/tag/stream in VCS and how it should be called;
  • To which repository in Artifactory the built artifacts should be submitted.
 Replication   
Event callback (with return value)beforeFileReplicationBefore file is replicatedHandle before file replication events. File replication can be skipped.
beforeDirectoryReplicationBefore directory is replicatedHandle before directory replication events. Directory replication can be skipped.
beforeDeleteReplicationBefore file/directory is deletedHandle before file or directory are deleted.
beforePropertyReplicationBefore properties are replicatedHandle properties replication.

Execution Context

The Download, Storage, Execution and Build plugin types are executed under the identity of the user request that triggered them.

It is possible to force a block of plugin code to execute under the "system" role, which is not bound to any authorization rules and can therefore perform actions that are otherwise forbidden for the original user.

To run under the "system" role wrap your code with the asSystem closure:

The Realm and Job plugin types already execute under the "system" role. This cannot be changed.

Plugin Template Source

General Info

Download

Handling and Manipulating Download Events
 

 

Storage

Handling and Manipulating Storage Events

If you want to abort an action, you can do that in 'before' methods by throwing a runtime org.artifactory.exception.CancelException with an error message and a proper http error code.

 

Jobs

Defining Scheduled Jobs
 

Executions

Defining External Executions

Realms

Management of Security Realms

Realms defined here are added before any built-in realms (Artifactory internal realm, LDAP, Crowd etc.). User authentication will be attempted against these realms first, by the order they are defined.

 

Build

Handling Build Info Events

Since 2.6

 

Promotions

Defining REST Executable Build Promotion Operations

Since 2.6

Staging

Defining REST retrievable Build Staging Strategy Construction

Since 2.6.1

Replication

Handling and filtering replication events

Since 3.0.4

Controlling plugin log level

The default log level for user plugins is "warn". To change a plugin logging level add the following to ${ARTIFACTORY_HOME}/etc/logback.xml:

The logger name is the name of the plugin file without the ".groovy" extension (in the example above the plugin file name is my-plugin.groovy). The logging levels can be either error, warn, info, debug or trace.

Sample Plugin

Sample plugin is available to download.

  • No labels