Repository and Project Scripts for Administrators

These configured hooks, listeners, merge checks, and built-in scripts (only for project administrators) can be used by project and repository administrators. Global administrators can define a base policy that applies globally or to a specific group of projects or repositories in the Bitbucket area. However, project and repository administrators can overlay that policy with their own specific policy.

To apply per repository and project scripts, follow these steps:

  1. Navigate to the project or repository. 
  2. Select the Cog to view Repository Settings or Project Settings. 
  3. Select a link in the ScriptRunner section. Your options are:
    • Only available for project administrators: Built-In Scripts
    • Pre-Receive Hooks

    • Post-Receive Hooks

      ScriptRunner hooks are not available under the Hooks section because Bitbucket doesn't allow multiple versions of the same hook to be applied. However, it is quite reasonable for instance to define multiple project refs hooks.

      For example: You might want one script to prevent release tags deletion and another to restrict the creation of hot fix branches to a list of trusted listeners.

  4. Once you select a type of script you want to work with, the section functions mostly like it would if you navigated to the feature by selecting General Configuration in ScriptRunner for Bitbucket.

Repository and Project Security Policy

All scripts, including conditions, compile to in-memory classes. As project and repository admins generally do not have system admin permission, the user-defined code is restricted in the following ways:

  • You can only call methods on an allowlist of certain Bitbucket API classes.
  • You cannot use certain other constructs.

A script defined and applied to a single repository or project by an administrator is functionally the same as a global script. The difference is that the user-defined code runs in a restricted sandboxed environment.

Conditions

Per-repository and project script conditions are compiled statically, which prevents using certain Groovy tricks, such as:

 
("java.lang.System" as Class).exit()

Per-repository conditions are validated when you create the item (listener, hook, merge check, etc.). For example, an attempt to call System.exit(0) results in:

Scripts defined globally do not have their condition checked at the time of creation, even if they are applied to just one repository. Validating the code requires static typing, which removes power from Groovy.

Entering the same condition in a global script will result in Bitbucket exiting at the time that it's invoked.

Tips for Editing a Project-Level or Repository-Level Script from Global Administration

If you are working in Global Administration (from the Cog), all configurations (global, project and repository) are listed so you can see all items without navigating to different projects and repositories. The Created In column shows the permission level of the configuration, and the Applied To column shows which Bitbucket object the configuration is applied to.

When you choose to work with an existing project-level or repository-level script, you can see where it is located on the Action pop-up menu. The image below shows a repository-level script: 

The following image shows a project-level script: 

When you edit a script that is an administrator repository-level or project-level script, you receive a warning message. You can still edit the script. 




On this page