public interface HookScriptService
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
).
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)
|
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)
|
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 . |
@Nonnull HookScript create(@Nonnull HookScriptCreateRequest request)
When creating a hook script, apps are required to provide the contents for the script, as well as a name and their plugin key.
limited
for disk space, but are otherwise not constrained.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
.
request
- a request describing the script to createID
should be retained by the creating appvoid delete(@Nonnull HookScript script)
Deleting a hook script requires SYS_ADMIN permission
.
script
- the script to deleteint deleteByPluginKey(@Nonnull String pluginKey)
Deleting hook scripts requires SYS_ADMIN permission
.
Note: When bulk deleting hook scripts, no event is raised. If HookScriptDeletedEvent
s
are important, callers should find the hook scripts
and delete them
individually, which will trigger an event for each.
pluginKey
- the plugin key to delete all hook scripts for@Nonnull Optional<HookScript> findById(long scriptId)
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.
scriptId
- the ID
of the script to retrieveempty()
if no script exists with that IDgetById(long)
@Nonnull Page<HookScript> findByPluginKey(@Nonnull String pluginKey, @Nonnull PageRequest pageRequest)
Retrieving hook scripts does not require any specific permission.
pluginKey
- the plugin key to search forpageRequest
- describes the page of scripts to returnnull
HookScript getById(long scriptId)
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.
scriptId
- the ID
of the script to retrieveNoSuchHookScriptException
- if no script exists with the specified IDfindById(long)
int getMaxSize()
create(com.atlassian.bitbucket.hook.script.HookScriptCreateRequest)
or update(com.atlassian.bitbucket.hook.script.HookScriptUpdateRequest)
a
script with larger contents will fail.@Nonnull InputSupplier<InputStream> read(@Nonnull HookScript script)
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.
script
- the hook script to readboolean removeConfiguration(@Nonnull HookScriptRemoveConfigurationRequest request)
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
request
- a request describing which script to remove configuration for, and which scope to remove it fromtrue
if configuration was removed; otherwise, false
if the script was already not
configured in the specified scope@Nonnull HookScriptConfig setConfiguration(@Nonnull HookScriptSetConfigurationRequest request)
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:
request
- a request describing which script to configure, and how@Nonnull HookScript update(@Nonnull HookScriptUpdateRequest request)
Hook scripts support updates to their:
Name
Plugin key
last update date
, but only updating the script's
contents will update its version
.
Updating a hook script requires SYS_ADMIN permission
.
request
- a request describing the hook script to update, and howint updatePluginKey(@Nonnull String oldPluginKey, @Nonnull String newPluginKey)
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
.
oldPluginKey
- the app's old plugin keynewPluginKey
- the app's new plugin keyCopyright © 2020 Atlassian. All rights reserved.