Quick Start

  1. Download plugin from Atlassian Marketplace

  2. Install YACC plugin into Bitbucket Server

  3. If you want to require valid Jira issues, configure a Jira Application Link in Bitbucket Server

  4. Configure YACC globally or per-repository

Modes of Operation

YACC can be configured globally, per project, or per repository. There are two modes of operation, which can be enabled independently:

  1. Pre-receive hook – in this mode, YACC checks all commits at the time they’re pushed or added to the repository.

  2. Merge checks – in this mode, checks are only performed for pull requests. If there are any failures, the pull request is blocked from being merged.

Turning on the pre-receive hook

  • To configure per-repository settings, go to the Project settings > Hooks.

  • To configure global settings, select “YACC global push hook” in the Bitbucket admin page

  • The hook can also be configured via the Bitbucket REST API.

Turning on the merge check

Settings inheritance

You can define YACC settings on 3 levels:

  • global: these settings will be applied for all projects and repositories by default (if not overridden)

  • project: settings will work on project level for all repositories where YACC hook is configured to Inherited (default)

  • repository: affect specific repository level only when YACC hook is explicitly set to Enabled

So, hook settings defined on lower level will override higher-level ones, otherwise settings will be inherited.

Supported Configuration Settings

YACC settings are grouped into tabs, where you can configure different aspects of the hook.

Configuration

Scan All Commits in Pull Request

If enabled, pre-receive hook will scan all commits in Pull Request on merge attempt, even if they have been scanned before.

Jira Impersonation, a.k.a. Overridden username

By default YACC uses the user account associated with the committer to make connection to Jira to validate issues, running JQL queries, etc. This can cause authentication issues when the user pushing code doesn’t have read access in the corresponding Jira project. Examples of this include commits from continuous integration, or commits made through SSH access keys.

If this parameter is configured, the specified user will be used instead for all Jira queries. Must be a valid Bitbucket username associated with a Jira account.

The Jira Overridden Username parameter can be specified in the global settings only. The setting is shared between the pre-receive hook and the merge check.

Commits

Require Committer Matches Valid User

If enabled, YACC will check that committer email matches some valid Bitbucket Server user.

Require Matching Committer Email

If enabled, committer email must match the email of the Bitbucket Server user.

Require Matching Committer Name

If enabled, committer name must match the name of the Bitbucket Server user.

Committer Email Regex

If a regex is present, the committer email must match regex.

Commit Message Regex

If a regex is present, commit message must match regex.

Note: Leading and trailing whitespace are ignored.

Example,

[A-Z0-9\-]+: .*
CODE

will require commit message to be in the form of:

PROJ-123: added new feature xyz
CODE
Multi-line Commit Message Regex

Multi-line commit messages can be matched by including newlines into the regex (like (.|\n)*), or by enabling Pattern.DOTALL by starting your regex with (?s).

See My regex is not working for more debugging details.

Jira Issues

Require Valid Jira Issue(s)

If enabled, commit messages must contain valid Jira issue ids. Jira issue ids are defined as any item that matches the regex [A-Z][A-Z_0-9]+-[0-9]+.

This check requires Jira to be first linked with Bitbucket Server using an Application Link.

Note: This may result in false positives if commit messages contains strings that look like Jira issue, for example, "UTF-8". Enable Ignore Unknown Jira Project Keys to tell YACC to ignore items that don't contain a valid Jira Project key.

Locating Issues Using a Regex Group

If a regex group is present in the Commit Message Regex, only text contained within this group will be examined when extracting Jira issues.

For example, a ([A-Z0-9\-]+): .* commit message regex will mean only PROJ-123 will be checked against Jira in the following commit message:

PROJ-123: fixed bug involving UTF-8 support. I deserve a HIGH-5 for this fix!
CODE

UTF-8 and HIGH-5 will be ignored because they are not contained within the regex group. Using a regex group can be used as an alternative to Ignore Unknown Jira Project Keys to deal with issue false positives, especially when you want to detect project key typos.

Require Matching Jira Issue In Branch Name

When enabled, issue keys found in the commit message will be checked against the branch name. If the branch name doesn’t contain at least one of them, the commit is rejected. The default branch (typically master) is automatically excluded.

Example:

  • Sample commit message PROJ-123 Clean up leftover interfaces from PROJ-3

  • Allowed branch names: bugfix/PROJ-123, PROJ-123-cleanup, PROJ-3-update

  • Blocked branch names: fixes, feature/PROJ-12

Note: you need to enable Require Valid Jira Issue(s) option first to use this feature.

Ignore Unknown Jira Project Keys

If enabled, any issue-like items in commit messages that do not contain a valid Jira project key (such as "UTF-8") will be ignored.

Issue JQL Matcher

If JQL query is present, detected Jira issues must match this query.

For example,

 assignee is not empty and status="in progress" and project=PROJ
CODE

will require that Jira issues be assigned, in progess, and from project PROJ.

See Jira Advanced Searching for documentation regarding writing and testing JQL queries.

Branches

Branch Name Regex

If present, only branches with names that match this regex will be allowed to be created. This also affects branches created within the Bitbucket Server UI. This only affects new branches, existing branches that don't match this regex will still be allowed.

For example, master|(?:(?:bugfix|hotfix|feature)/[A-Z]+-\d+-.+) would enforce that branch names follow the Bitbucket Server Branching Model naming convention.

Note: Leading and trailing whitespace are ignored.

Exclusion

Exclude Commits From Bitbucket UI

If enabled, skips validation of changes made through the Bitbucket UI. This includes edits made through the built-in web editor, and using the “Apply suggestion” feature. The latter doesn’t display a rejection message and doesn’t allow repeat attempts even after correcting the commit message (Bitbucket bug report), so it may be useful to not validate such changes.

Exclude Merge Commits

If enabled, merge commits will be excluded from commit requirements. This includes merge commits pushed through the command line and merges made via the Pull Request UI.

Exclude by Regex

If present, commits will be excluded from all requirements if part of the commit message matches this regex.

Example: ^Revert \"|#skipchecks

Note: Leading and trailing whitespace are ignored.

Exclude Branch Regex

If present, commits on branches that match the specified regex will be excluded from all checks. Branch regex exclusion is applied prior to the “Branch Name Regex” option; i.e. branch creation is never blocked when a branch matches the “exclude branch” pattern.

Example: experimental/.*

Note: Leading and trailing whitespace are ignored.

Exclude Service User Commits

If enabled, commits from service users (ie, using SSH Access Keys) will be excluded from commit requirements.

Exclude Commits From Users or User Groups

Comma delimited list of BitBucket User Names or User Groups. Commits from these users or members of user groups will be excluded from commit requirements.

Error Messages

Allows to customize various messages produced by YACC hook.