Cross-Entity Consistency
Overview
The Cross-Entity Consistency validator checks that task IDs (e.g., JIRA ticket references) are consistent across the MR and its commits. It enforces two checks:
- Commit task subset: Task IDs referenced in commit titles must be a subset of the task IDs found in the MR title or description.
- Changelog consistency: Task IDs appearing in
CHANGELOG:lines in commit bodies must not exceed the number of MR task IDs, and must not reference tasks not present in the MR.
This rule is useful for teams where each MR maps to one or more tickets and each commit is expected to reference only those tickets.
Configuration
Optional Properties
taskIdPattern: Regex pattern to extract task IDs from text (string, default:[A-Z]+-\d+)commitTasksSubsetOfMr: Enforce that commit task IDs are a subset of MR task IDs (boolean, default:true)changelogConsistency: Enforce changelog task ID consistency (boolean, default:true)changelogDuplicateDetection: Detect duplicate changelog entries across commits (boolean, default:true)changelogDuplicateRequiresMatchingText: When detecting duplicates, also require that the entry text matches (boolean, default:false)changelogPrefix: Line prefix that identifies changelog entries in commit bodies (string, default:CHANGELOG:)changelogCoverage: Require every task ID of the MR to appear in at least one CHANGELOG entry. Checked only once some commit already carries a CHANGELOG entry (boolean, default:false)mrTaskSource: Where to extract MR task IDs from (string, default:title)title- extract from MR title onlydescription- extract from MR description onlyboth- extract from both MR title and descriptionticketFormat: Structured ticket format type - alternative totaskIdPattern. Ignored whentaskIdPatternis set (TicketFormat, default:null). Values:JIRA,LINEAR,YOUTRACK,GITHUB,SHORTCUT,CUSTOM.ticketProjects: List of project keys used together withticketFormatto build the effective task ID pattern (list of strings, default:null)
Examples
Default Configuration
rules:
cross-entity-consistency: true
With defaults, task IDs matching [A-Z]+-\d+ (e.g., PROJ-123) are extracted from the MR title. Each commit title's task IDs must be a subset of those.
Extract Task IDs from Both Title and Description
rules:
cross-entity-consistency:
mr-task-source: "both"
Custom Task ID Pattern
rules:
cross-entity-consistency:
task-id-pattern: "#\\d+"
mr-task-source: "title"
Custom Changelog Prefix
rules:
cross-entity-consistency:
changelog-prefix: "CHANGES:"
changelog-consistency: true
Subset Check Only (Disable Changelog)
rules:
cross-entity-consistency:
commit-tasks-subset-of-mr: true
changelog-consistency: false
How Changelog Consistency Works
When changelogConsistency is enabled, the validator scans commit bodies for lines beginning with changelogPrefix (default: CHANGELOG:). Task IDs found in those lines are collected across all commits. The check fails if:
- The number of unique changelog task IDs exceeds the number of MR task IDs, or
- Any changelog task ID is not present in the MR task IDs.
Example commit body that would be checked:
PROJ-123: Implement user authentication
CHANGELOG: PROJ-123 Added OAuth2 login flow
Error Messages
- Commit references unknown task:
Commit a1b2c3d mentions ALPHA-7, which is not in the MR title (ALPHA-1)., or, when the MR has no task ID at all,Commit a1b2c3d mentions ALPHA-1234, but the MR title has no task ID.The suggestion:Add [ALPHA-1234] to the MR title or remove it from the commit subject.When three or more commits fail the same way, they fold into one finding -{N} commits mention tasks not in the MR title ({sha1}, {sha2}, {sha3}, +{rest} more)- and every per-commit message stays in its collapsibleAll {N} commitsattachment. - Changelog references unknown task: one finding for all of them,
CHANGELOG mentions 8 tasks not in the MR title (ALPHA-1, ALPHA-2, ALPHA-3, +5 more); the suggestion lists every task - Invalid regex: Reported as a finding if
taskIdPatterncannot be compiled
Notes
- Task ID extraction uses
findAllon the pattern - all non-overlapping matches in the text are collected. - The MR task ID set is computed once per MR and reused for all commit checks.
- When
mrTaskSourceistitle(default) and the MR title contains no task IDs, all commit task IDs are treated as "extra" and will fail the subset check.
Related Rules
- JIRA Ticket - Require and validate JIRA ticket references
- JIRA Validation - Live JIRA ticket status and field validation
- Commit Messages - Validate commit message format