Configuration overview - Yet Another Commit Checker
Quick start
Download plugin from Atlassian Marketplace.
Install YACC plugin into Bitbucket Server.
To set Jira Issue Requirements through YACC, you must also 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 by repository. There are two modes of operation which can be enabled independently:
Pre-receive hook – YACC checks all commits when they are pushed or added to the repository.
Merge checks – Checks are only performed for pull requests. For an unsuccessful check, the pull request is blocked from being merged.
Configure the pre-receive hook settings
To configure per-repository settings, go to your repository and click Repository settings → Hooks from the side menu. Locate Yet Another Commit Checker under the Pre Receive heading and select Enabled from the dropdown to open the Yet Another Commit Checker dialog. Refer to the Configuration section for settings information. See Using repository hooks for additional information.
To configure global settings, click the Bitbucket Administration cog → YACC global push hook under the Add-Ons heading on the Bitbucket admin page.
The hook can also be configured via the Bitbucket REST API.
Configure the merge check settings
To configure per-repository merge check settings, go to your repository and click Repository settings → Merge checks from the side menu. Locate Yet Another Commit Checker under the Merge checks heading and select Enabled from the dropdown to open the Yet Another Commit Checker dialog. Refer to the Configuration section for settings information. See Checks for merging pull requests for additional information.
To configure global merge check settings, click the Administration cog → YACC global merge check under the Add-Ons heading on the Bitbucket admin page.
The hook can also be configured via the Bitbucket REST API.
Settings inheritance
You can define YACC settings on three levels:
Global: These settings are applied for all projects and repositories by default (if not overridden).
Project: These settings work on the project level for all repositories where the YACC hook is configured to
Inherited
(default).Repository: When the YACC hook is explicitly set to
Enabled
for a repository, the settings only affect that specific repository level.
Hook settings defined on lower levels override higher-level ones; otherwise, settings are inherited.
Configuration settings
YACC settings are grouped into tabs, where you can configure the different aspects of the hook.
Where are the configuration settings?
Global - Go to Administration
YACC Global push check
YACC Global merge check
Project: settings work on the project level for all repositories where the YACC hook is configured to
Inherited
(default)
Go to Project Settings → Hooks
Go to Project Settings → Merge ChecksRepository - Go to Repository settings
Hooks
Merge Checks
Configuration
The Configuration tab contains different options, depending on where you are configuring settings (GLOBAL PUSH HOOKGLOBAL MERGE CHECK orREPOSITORY).
Overriding global configuration
GLOBAL PUSH HOOK GLOBAL MERGE CHECK
Bitbucket administrator defines who can override hook settings defined on a global level:
Do not allow, force to use global: Use global configuration for all enabled Project and Repository level hooks, ignoring existing settings.
Allow to selected user groups: Only the selected user groups can change Project and Repository hook settings. All previously configured hooks remain unchanged.
Allow to project/repository admins (default): Global settings can be overridden by users with the necessary permissions.
Limiting configuration changes does not modify or remove existing hooks configuration so that you can switch this option with no risk to existing configurations.
This option can be changed for Pre-receive hooks and Merge checks independently.
Scan All Commits in Pull Request
GLOBAL PUSH HOOK REPOSITORY
When enabled, the pre-receive hook scans all commits in a Pull Request on a merge attempt, even if they have been scanned before.
Enable dry run mode
GLOBAL PUSH HOOK REPOSITORY
When enabled, the pre-receive hook displays an error but does not reject the push action.
Jira Authentication Configuration
GLOBAL PUSH HOOK
By default, YACC uses the user account associated with the committer to make a connection to Jira to validate issues, run JQL queries, etc. This can cause authentication issues when the user pushing the code does not have read access to the corresponding Jira project. Examples include commits from continuous integration or commits made through SSH access keys.
The specified user is used for all Jira queries if this parameter is configured. There must be a valid Bitbucket username associated with a Jira account.
The Jira Authentication Configuration parameter can only be specified in the global settings. The setting is shared between the pre-receive hook and the merge check.
Commits
Require Committer Matches Valid User
When enabled, YACC checks that the committer email matches any valid Bitbucket Server user.
Require Matching Committer Email
When enabled, the committer email must match the email of a valid Bitbucket Server user.
Require Matching Committer Name
When enabled, the committer name must match the name of the Bitbucket Server user.
Committer Email Regex
When a regex is present, the committer email must match the regex.
Commit Message Regex
When a regex is present, the commit message must match the regex. Leading and trailing whitespace are ignored.
Example[A-Z0-9\-]+: .*
requires the 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 enablingPattern.DOTALL
by starting your regex with(?s)
.
See Regex is not workingfor debugging details.
Jira Issues
The Jira Issues tab allows you to set how Bitbucket responds to Jira issues in commit messages.
The Jira Issues tab contains different options, depending on where you are configuring the settings (GLOBAL PUSH HOOKGLOBAL MERGE CHECK orREPOSITORY).
To set Jira Issue Requirements through YACC, you must also configure a Jira Application Link in Bitbucket Server.
Jira App Link
GLOBAL PUSH HOOK GLOBAL MERGE CHECK REPOSITORY
Jira application links are used to:
Check Jira issues, the building blocks of a Jira project and can be anything from bugs to stories
Validate issue keys, used as identifiers for specific work items in a Jira project
When you have multiple application links to your Jira instances, the YACC Jira App Link feature allows you to determine which application links it uses to validate issue keys.
The App Link feature has three options:
All - All available Jira application links are used to validate issue keys. Once an issue key is found, validation stops and returns issue data from the first matching Jira instance
Primary - The Jira application link configured as Primary at the time of commit is used to validate issue keys
Select Links - Only the selected Jira application links are used to validate issue keys
To create a Jira application link, see Link Bitbucket with Jira.
Require Valid Jira Issue(s)
GLOBAL PUSH HOOKGLOBAL MERGE CHECK REPOSITORY
When 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 can result in false positives if commit messages contain strings that look like Jira issues. For example, UTF-8
. Enable Ignore Unknown Jira Project Keys
to tell YACC to ignore items that do not contain a valid Jira Project key.
Require Matching Jira Issue In Branch Name
GLOBAL PUSH HOOKGLOBAL MERGE CHECK REPOSITORY
When enabled, issue keys in the commit message are checked against the branch name. The commit is rejected if the branch name does not contain an issue key. 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
Enable the Require Valid Jira Issue(s) option first to use this feature.
Ignore Unknown Jira Project Keys
GLOBAL PUSH HOOKGLOBAL MERGE CHECK REPOSITORY
When enabled, any issue-like items that do not contain a valid Jira project key (such as UTF-8
) in the commit messages are ignored.
Issue JQL Matcher
GLOBAL PUSH HOOKGLOBAL MERGE CHECK REPOSITORY
When a JQL query is present, detected Jira issues must match this query.
Exampleassignee is not empty and status="in progress" and project=PROJ
requires Jira issues be assigned, in progress,
and from project PROJ
.
Additional topics
See Jira Advanced Searching for documentation regarding writing and testing JQL queries.
See Jira authentication failed message article in the Troubleshooting section.
Branches
The Branches tab is only located at the Repository level and is used to set branch naming requirements.
Branch Name Regex
When present, only branches with names that match this regex can be created. This also affects branches created within the Bitbucket Server UI. This only affects new branches and branches created within the Bitbucket UI; existing branches that do not match this regex are allowed.
Examplemaster|(?:(?:bugfix|hotfix|feature)/[A-Z]+-\d+-.+)
branch names must follow the Bitbucket Server Branching Model naming convention.
Leading and trailing whitespace are ignored.
Exclusions
Exclude Commits From Bitbucket UI
When enabled, YACC skips validation of changes made through the Bitbucket UI. This includes edits from the built-in web editor and the Apply suggestion feature. The latter does not display a rejection message and does not allow repeat attempts even after correcting the commit message (Bitbucket bug report), so it may be useful not to validate such changes.
Exclude Merge Commits
When enabled, merge commits are excluded from commit requirements. This includes merge commits pushed through the command line and merges made via the Pull Request UI.
Exclude by Regex
When present, commits are excluded from all requirements if part of the commit message matches this regex.
Example^Revert \"|#skipchecks
Leading and trailing whitespace are ignored.
Exclude Branch Regex
When present, commits on branches that match the specified regex are excluded from all checks. Branch regex exclusion is applied before the Branch Name Regex option; i.e., branch creation is never blocked when a branch matches the Exclude Branch pattern.
Exampleexperimental/.*
Leading and trailing whitespace are ignored.
Exclude Service User Commits
When enabled, commits from service users (i.e., using SSH Access Keys) are excluded from commit requirements.
Exclude Commits From Users or User Groups
Dropdowns of BitBucket User Names or User Groups. Commits from these users or members of user groups are excluded from commit requirements.
Error Messages
The Error Messages tab allows you to customize various messages produced by the YACC hook. For each entry, you can add a customized error message that replaces the default error message.
Example message
To add a customized error message to help ensure internal policies were being followed, a heading message could look like this:
Your commit message does not conform to organizational requirements. Contact your Bitbucket repository administrator for details
Add your message to the appropriate field; in this case, the Header field and click Enable.
When triggered, Bitbucket displays the custom error message: