HookScriptService

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.

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

Deleting a hook script requires SYS_ADMIN permission.

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.

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.

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.

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.

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

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.

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

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 -> ADMIN
• Project scope -> PROJECT_ADMIN
• Repository scope -> REPO_ADMIN

Updates a hook script.

Hook scripts support updates to their:

• Contents
• Name
• Plugin key

Updating a hook script requires SYS_ADMIN permission.

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.