Configuration Overview
Quick Start
Download plugin from Atlassian Marketplace
Install YACC plugin into Bitbucket Server
If you want to require valid Jira issues, configure a Jira Application Link in Bitbucket Server
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:
Pre-receive hook – in this mode, YACC checks all commits at the time they’re pushed or added to the repository.
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
To configure per-repository settings, go to the Project settings > Merge checks.
To configure global settings, select “YACC global merge check” in the Bitbucket admin page
The hook can also be configured via the Bitbucket REST API.
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\-]+: .*
will require commit message to be in the form of:
PROJ-123: added new feature xyz
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!
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
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.