com.atlassian.bitbucket.hook.script

Interface HookScriptService

public interface HookScriptService

A service for creating, updating and configuring hook scripts.

An SPI is provided which allows app developers to write hooks in Java, but for many that is not their language of choice. Enter hook scripts. Hook scripts allow hooks to be written in other languages, such as Python or Perl, or as shell scripts. App developers can create hook scripts, providing their contents, and then configure the scopes in which they should run (optionally filtered to specific triggers).

Since:

6.2

Method Summary

Modifier and Type	Method and Description
HookScript	create(HookScriptCreateRequest request) Creates a new hook script.
void	delete(HookScript script) Deletes the specified hook script, and removes any configuration which has been applied.
int	deleteByPluginKey(String pluginKey) Deletes all of the hook scripts associated with the specified plugin key, and removes any configuration which has been applied for them.
Optional<HookScript>	findById(long scriptId) Finds a hook script by its globally unique ID, which was assigned when the script was created.
Page<HookScript>	findByPluginKey(String pluginKey, PageRequest pageRequest) Finds a page of hook scripts which were created by the app with the specified plugin key.
HookScript	getById(long scriptId) Retrieves a hook script by its globally unique ID, which was assigned when the script was created.
int	getMaxSize() Retrieves the configured limit for hook script contents.
InputSupplier<InputStream>	read(HookScript script) Returns an InputSupplier which can be used to open an InputStream to read the current contents for the specified hook script.
boolean	removeConfiguration(HookScriptRemoveConfigurationRequest request) Removes any configuration for a given hook script from the specified scope.
HookScriptConfig	setConfiguration(HookScriptSetConfigurationRequest request) Configures a hook script to run for a given scope.
HookScript	update(HookScriptUpdateRequest request) Updates a hook script.
int	updatePluginKey(String oldPluginKey, String newPluginKey) Updates existing hook scripts which reference oldPluginKey to reference newPluginKey.

Method Detail

create

@Nonnull
HookScript create(@Nonnull
                           HookScriptCreateRequest request)

Creates a new hook script.

When creating a hook script, apps are required to provide the contents for the script, as well as a name and their plugin key.

• The contents are limited for disk space, but are otherwise not constrained.
• The name is free-form, and limited to 255 characters. Operating system-specific limitations to filenames do not apply to hook script names.
  • Note: Uniqueness is not enforced for hook script names, so apps can create multiple hooks with the same name
• The plugin key, also limited to 255 characters, correlates all of the scripts created by a given app, allowing them to be found later.

When a script is created, it is assigned a globally unique ID. App developers are required to track the IDs of the scripts they create, to allow them to manage them later. Scripts can potentially be found again using the plugin key, but IDs are intended to be the primary mechanism for configuring, deleting or updating scripts after they're created.

Creating a hook script requires SYS_ADMIN permission.

Parameters:

request - a request describing the script to create

Returns:

the created script, whose ID should be retained by the creating app

delete

void delete(@Nonnull
            HookScript script)

Deletes the specified hook script, and removes any configuration which has been applied.

Deleting a hook script requires SYS_ADMIN permission.

Parameters:

script - the script to delete

deleteByPluginKey

int deleteByPluginKey(@Nonnull
                      String pluginKey)

Deletes all of the hook scripts associated with the specified plugin key, and removes any configuration which has been applied for them.

Deleting hook scripts requires SYS_ADMIN permission.

Note: When bulk deleting hook scripts, no event is raised. If HookScriptDeletedEvents are important, callers should find the hook scripts and delete them individually, which will trigger an event for each.

Parameters:

pluginKey - the plugin key to delete all hook scripts for

Returns:

the number of hook scripts that were deleted

findById

@Nonnull
Optional<HookScript> findById(long scriptId)

Finds a hook script by its globally unique ID, which was assigned when the script was created.

If the caller expects the script to exist getById(long) can be used instead to drop the Optional wrapping, but an exception will be thrown if the script doesn't exist.

Retrieving a hook script does not require any specific permission.

Parameters:

scriptId - the ID of the script to retrieve

Returns:

the script with the specified ID, or empty() if no script exists with that ID

See Also:

getById(long)

findByPluginKey

@Nonnull
Page<HookScript> findByPluginKey(@Nonnull
                                          String pluginKey,
                                          @Nonnull
                                          PageRequest pageRequest)

Finds a page of hook scripts which were created by the app with the specified plugin key.

Retrieving hook scripts does not require any specific permission.

Parameters:

pluginKey - the plugin key to search for

pageRequest - describes the page of scripts to return

Returns:

a page of scripts, which may be empty but never null

getById

HookScript getById(long scriptId)

Retrieves a hook script by its globally unique ID, which was assigned when the script was created.

If no script exists with the specified ID, an exception is thrown. If the caller anticipates that the script may not exist, findById(long) can be used instead to avoid the exception.

Retrieving a hook script does not require any specific permission.

Parameters:

scriptId - the ID of the script to retrieve

Returns:

the script with the specified ID

Throws:

NoSuchHookScriptException - if no script exists with the specified ID

See Also:

findById(long)

getMaxSize

int getMaxSize()

Retrieves the configured limit for hook script contents. Attempting to create(com.atlassian.bitbucket.hook.script.HookScriptCreateRequest) or update(com.atlassian.bitbucket.hook.script.HookScriptUpdateRequest) a script with larger contents will fail.

Returns:

the configured limit, in bytes

read

@Nonnull
InputSupplier<InputStream> read(@Nonnull
                                         HookScript script)

Returns an InputSupplier which can be used to open an InputStream to read the current contents for the specified hook script.

While hook scripts can be retrieved by anyone, reading their contents requires SYS_ADMIN permission. Hook script metadata, which is provided by the HookScript interface, is not sensitive, but hook script contents may contain credentials (in order to access remote systems, for example) or other sensitive data.

Parameters:

script - the hook script to read

Returns:

a supplier which can be used to stream the hook script's contents

removeConfiguration

boolean removeConfiguration(@Nonnull
                            HookScriptRemoveConfigurationRequest request)

Removes any configuration for a given hook script from the specified scope.

Removing a hook script's configuration means it may no longer run. If the script is also configured in an overlapping, more general scope, that configuration will take over. For example, if a script is configured for a specific repository and for the project which contains that repository, removing the repository-level configuration will not prevent the script from running; the project-level configuration will be used instead.

Removing configuration for a hook script requires the appropriate admin permission for the scope:

• Global scope requires ADMIN permission
• Project scope requires PROJECT_ADMIN permission
• Repository scope requires REPO_ADMIN permission

Parameters:

request - a request describing which script to remove configuration for, and which scope to remove it from

Returns:

true if configuration was removed; otherwise, false if the script was already not configured in the specified scope

setConfiguration

@Nonnull
HookScriptConfig setConfiguration(@Nonnull
                                           HookScriptSetConfigurationRequest request)

Configures a hook script to run for a given scope. All scope types are supported, allowing scripts to be configured to run for an individual repository, all repositories in a project, or all repositories. If the script is already configured for the specified scope the existing configuration is replaced, including its triggers (triggers are not cumulative).

If no trigger IDs are specified, the script will run for all triggers in the configured scope. Otherwise, it will only run for the specified triggers.

When scripts are run, the configuration for the most specific scope is used. Any configuration applied to less-specific scopes is ignored; the levels do not merge. For example, if a script is configured for a specific repository, as well as for the project the repository is in, when the script runs in that repository it will use the repository-level configuration and the project-level configuration will be ignored.

Configuring a hook script requires the appropriate admin permission for the scope:

• Global scope -> Permission.ADMIN
• Project scope -> Permission.PROJECT_ADMIN
• Repository scope -> Permission.REPO_ADMIN

Parameters:

request - a request describing which script to configure, and how

Returns:

the configuration applied for the script

update

@Nonnull
HookScript update(@Nonnull
                           HookScriptUpdateRequest request)

Updates a hook script.

Hook scripts support updates to their:

• Contents
• Name
• Plugin key

Requests can update any combination of those properties at once. Updates to any of those properties will update the script's last update date, but only updating the script's contents will update its version.

Updating a hook script requires SYS_ADMIN permission.

Parameters:

request - a request describing the hook script to update, and how

Returns:

the updated script

updatePluginKey

int updatePluginKey(@Nonnull
                    String oldPluginKey,
                    @Nonnull
                    String newPluginKey)

Updates existing hook scripts which reference oldPluginKey to reference newPluginKey.

Even configured hook scripts are only executed as long as the app associated with their plugin key is still installed and enabled. That means if an app's plugin key changes, any hook scripts it created will no longer execute until they are updated to reference its new plugin key. This method facilitates that update.

Updating hook script plugin keys requires SYS_ADMIN permission. Additionally, it is required that no installed app, enabled or disabled, have the specified oldPluginKey, and the newPluginKey must reference an installed and enabled app.

Warning: No "duplicate" checking is performed when updating plugin keys. If an app creates a hook script with a given plugin key, then its plugin key is changed and it creates a new hook script with the new plugin key, calling this method will result in two hook scripts that use the new key, even if the two hook scripts have the same name.

Parameters:

oldPluginKey - the app's old plugin key

newPluginKey - the app's new plugin key

Returns:

the number of hook scripts updated with a new plugin key