> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gitar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Functional Validation

> Check whether a PR implements what its linked issue asked for

export const ThemeImage = ({src, alt, width}) => {
  let lightSrc, darkSrc;
  if (src.includes("-light.")) {
    lightSrc = src;
    darkSrc = src.replace("-light.", "-dark.");
  } else if (src.includes("-dark.")) {
    darkSrc = src;
    lightSrc = src.replace("-dark.", "-light.");
  } else {
    lightSrc = src;
    darkSrc = src;
  }
  const style = width ? {
    maxWidth: width,
    marginInline: "auto"
  } : undefined;
  return <span>
      <img className="block dark:hidden rounded-lg border" src={lightSrc} alt={alt} style={style} />
      <img className="hidden dark:block rounded-lg border" src={darkSrc} alt={alt} style={style} />
    </span>;
};

## Overview

Functional validation reads the issues a PR claims to close, breaks each one into individual objectives, and judges every objective against the diff. The result is a **Functional validation** row under Verification in the [Gitar dashboard comment](/gitar-dashboard), one block per linked issue, least complete first.

<CardGroup cols={2}>
  <Card title="Objective by Objective" icon="list-check">
    Each requirement in the issue is tracked on its own, so a PR that does most of the work reads as partial rather than done
  </Card>

  <Card title="Re-Judged on Every Push" icon="rotate">
    New commits are re-checked against the same objectives, so the section keeps up with the branch
  </Card>
</CardGroup>

<Note>
  Functional validation is included on the **Enterprise** plan. A tracker issue needs that integration connected. Your code host's own issues need nothing connected.
</Note>

## Supported Issue Sources

| Issue source | Referenced as | Needs |
| - | - | - |
| [Jira](/integrations/jira) | `PROJ-123` | Jira integration connected |
| [Linear](/integrations/linear) | `ENG-45` | Linear integration connected |
| [Plane](/integrations/plane) | `ENG-45` | Plane integration connected |
| [YouTrack](/integrations/youtrack) | `SP-7` | YouTrack integration connected |
| GitHub issues | `#123` | nothing |
| GitLab issues | `#123` | nothing |
| Azure DevOps work items | linked to the PR, or `AB#123` | nothing |
| Bitbucket Cloud issues | `#123` | the repo's issue tracker enabled |

Bitbucket Data Center has no issue tracker of its own, so link a Jira issue there instead.

A tracker key is the same shape on Jira, Linear, Plane, and YouTrack, so connect one tracker per organization. With more than one connected, Gitar reads the key against Jira first, then Linear, then Plane, then YouTrack.

## How It Works

<Steps>
  <Step title="Gitar finds the linked issue">
    Gitar looks for issue keys in the PR title, description, and branch name. Nothing is linked unless the PR claims the issue, so a passing mention is ignored.
  </Step>

  <Step title="The issue becomes a list of objectives">
    Gitar reads the issue text from its source and derives the concrete objectives it asks for.
  </Step>

  <Step title="Each objective is judged against the diff">
    Every objective is marked covered or not covered based on the current diff. Pushing new commits re-runs the judgement, and editing the issue reconciles the objective list against it.
  </Step>

  <Step title="Objectives appear in Verification">
    The section is added to the existing Gitar comment on the PR. Gitar posts no separate comment and adds no status check.
  </Step>
</Steps>

## Linking an Issue

Reference the issue in the PR title, the PR description, or the branch name, the way you already do to close an issue. A tracker key (`PROJ-123`) and your code host's own issue number (`#123`) both work.

A `#123` refers to an issue in the PR's own repository. Another repository's issue (`other/repo#123`) is not linked.

On Azure DevOps, work items attached to the PR are picked up directly, so there is nothing to write in the description.

With validation enabled, Gitar links issues it can read and checks the PR against their objectives. Organization admins can turn **Validate PRs against linked issues** on or off under **Settings -> Configuration -> Behavior**. Uncovered objectives are reported in the comment and do not block merging.

## Reading the Section

The Functional validation row counts active objectives across linked issues, for example **3 covered / 5 objectives**. Each issue keeps its link and count, with the least-covered issue first. Dropped objectives stay excluded.

A partly covered issue is scope information, since an earlier PR may have delivered the rest. Uncovered objectives appear under **Other objectives on this issue, possibly covered elsewhere**. They do not block merging.

Verification opens while any objective is uncovered. Once all recorded outcomes are settled, it collapses. Opening Functional validation reveals up to five objective names across the linked issues. `gitar display:verbose` adds the remaining names and summaries.

<ThemeImage src="/assets/images/verification-mixed-light.png" alt="Verification showing covered objectives and other scope from a linked issue" />

On platforms without collapsible HTML, the same content appears as headings and lists. A linked issue with no active objectives contributes no validation body, while other Verification outcomes can still appear.

[Risk Triage](/features/code-review/risk-triage) separately assesses the impact of the whole change. Objective coverage does not imply Code Review approval or executed runtime tests.

## Changing the Issue

Objectives track the issue rather than a snapshot of it. Add a requirement and it shows up as not covered on the next run. Remove one and it stops counting against the PR: the objective total drops instead of the completion count going up, so cutting scope can never read as work finished.

## Limits

A PR validates at most 5 linked issues. Extra keys beyond that are ignored.

Gitar reads the issue text but never writes to it. Objectives, statuses, and counts live only in the PR comment - your tracker stays the source of truth. To have Gitar post back to the issue on merge, see [Jira](/integrations/jira), [Linear](/integrations/linear), [Plane](/integrations/plane), and [YouTrack](/integrations/youtrack).

Objectives belong to the PR being reviewed. Two PRs against the same issue each track their own set, and Gitar has no combined per-issue view.

## Related

<CardGroup cols={2}>
  <Card title="Jira Integration" icon="jira" href="/integrations/jira">
    Connect Jira so Gitar can read linked issues
  </Card>

  <Card title="Linear Integration" icon="list-check" href="/integrations/linear">
    Connect Linear so Gitar can read linked issues
  </Card>

  <Card title="Plane Integration" icon="square-kanban" href="/integrations/plane">
    Connect a Plane workspace so Gitar can read linked work items
  </Card>

  <Card title="The Gitar Dashboard" icon="comment" href="/gitar-dashboard">
    Where Verification is rendered
  </Card>

  <Card title="Plans" icon="credit-card" href="/account-billing/plans">
    What each plan includes
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.