Package 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 Details

    • 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:

    • 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:

    • 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:

      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:

      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:

      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