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

# Pull request reviews

> What Vidoc does on your pull requests: when it scans, what it checks, and the comments that it writes.

Vidoc reviews your pull requests (PRs) for security issues. It writes one summary comment on the PR and one inline comment for each confirmed finding. On GitLab, a PR is a merge request (MR). Vidoc comments use "PR" on all platforms.

Vidoc reviews a PR only when **PR reviews** is on for the repository. Refer to [Repositories](/web-app/repositories). To connect your platform, refer to [GitHub](/integrations/github), [GitLab](/integrations/gitlab), or [Bitbucket](/integrations/bitbucket).

## When Vidoc scans

Vidoc scans the head commit of the PR.

| Event                                             | GitHub                                                | GitLab                        | Bitbucket                     |
| ------------------------------------------------- | ----------------------------------------------------- | ----------------------------- | ----------------------------- |
| You open the PR                                   | A new scan starts.                                    | A new scan starts.            | A new scan starts.            |
| You push new commits to the PR                    | A new scan starts.                                    | A new scan starts.            | A new scan starts.            |
| You change the title, description, or labels      | No scan starts.                                       | A new scan starts.            | A new scan starts.            |
| You reopen a closed PR                            | No scan starts. The next update starts a scan.        | Same as GitHub.               | Same as GitHub.               |
| You close or merge the PR                         | Vidoc stops the running scan.                         | Vidoc stops the running scan. | Vidoc stops the running scan. |
| A person sends a scan command in a PR comment     | A new scan starts.                                    | A new scan starts.            | Not supported.                |
| A person selects **Run Vidoc** on the Vidoc check | A new scan starts (only when status reporting is on). | Not available.                | Not available.                |
| You push to the default branch                    | No scan starts.                                       | No scan starts.               | No scan starts.               |

Vidoc runs one scan for each PR at a time. When a new scan starts, Vidoc stops the running scan for the same PR.

Vidoc does not filter PRs by draft status, branch name, or size. Vidoc also scans draft PRs.

The first scan of a repository can take longer than usual. Vidoc prepares data about the repository during that scan.

For scan commands, refer to [Commands](/pull-requests/commands).

## Which files Vidoc checks

In a PR scan, Vidoc checks only the files that the PR changes. In each file, Vidoc looks for security issues in the changed code.

**Scanned in PR scans:**

* Source code in all languages, for example `src/orders/search.ts` or `Service.java`
* `Dockerfile` and `Jenkinsfile`
* Terraform and Pulumi files, for example `main.tf`, `prod.tfvars`, `Pulumi.yaml`
* `.gitlab-ci.yml` and `docker-compose.yml`, only at the repository root
* Files in a `k8s/`, `kubernetes/`, `helm/`, or `charts/` folder below the root folder, for example `deploy/k8s/app.yaml`

**Not scanned in PR scans:**

* Documentation and text files, for example `README.md`
* Data and configuration files: `.json`, `.xml`, `.toml`, `.ini`, `.conf`, `.properties`
* All other YAML files, also CI include files and CI files that are not at the root
* Files that Vidoc never indexes, for example binary files, lock files, `.env` files, and `node_modules/`

If your PR changes only files that Vidoc does not scan in PR scans, ask your AppSec team to run a full scan of the default branch after the merge.

## The flow of a scan

```mermaid theme={null}
sequenceDiagram
    actor Dev as Developer
    participant SCM as Source code platform
    participant V as Vidoc
    Dev->>SCM: Open the PR or push a commit
    SCM->>V: Send the pull request event
    V->>SCM: Write or edit the summary comment: "Currently scanning commit ..."
    V->>V: Find issues in the changed code
    V->>V: Validate each high and critical issue with an agent
    loop For each confirmed finding
        V->>SCM: Start a comment thread on the changed line
    end
    V->>SCM: Edit the summary comment with the result
    V->>SCM: Resolve old Vidoc threads for findings that are gone
```

For more about detection and validation, refer to [How it works](/how-it-works).

## The summary comment

Vidoc writes one summary comment on each PR. The heading is **Vidoc security review**. Vidoc does not write a new summary comment for each scan. It edits the same comment.

While a scan runs, the comment shows this text:

```markdown theme={null}
## Vidoc security review

> [!NOTE]
> Currently scanning commit `3f9c2a1`. Started at 2026-09-24 10:15 UTC. This may take a few minutes, please wait...
```

When the scan is complete, the comment shows one of these results:

| Result                 | Meaning                                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Good to merge**      | Vidoc found no security issues in the changed files.                                                                |
| **Partial review**     | Vidoc found no issues, but it could not fully analyze some changed files. Push a new commit or send a scan command. |
| **Fix before merge**   | Vidoc found one or more findings with critical or high severity.                                                    |
| **Check before merge** | Vidoc found only findings with medium severity.                                                                     |

These results are advice. Vidoc does not block the merge. Your team rules decide if you can merge.

The summary shows only open findings that the validation agent confirmed, with critical, high, or medium severity. It does not show findings in a compliance category, for example weak cryptography. A medium finding is a finding that the validation agent confirmed but rated lower than detection did.

If Vidoc found issues, the comment has a table with the columns **Severity**, **Finding**, and **Location**. The location links to the file and line. If there are critical or high findings, the medium findings go in a collapsed section with the name **Non-blocking**. The **Full analysis** link opens the PR in the Vidoc web app. You must have a Vidoc account to open this link.

The examples below use `app.vidoc.dev` for dashboard links. On a custom deployment, generated links use your configured web app URL.

This is an example of a complete summary comment on GitHub:

```markdown theme={null}
## Vidoc security review

> [!CAUTION]
> **Fix before merge** — 1 finding (1 high). 1 other finding non-blocking.

| Severity | Finding | Location |
| --- | --- | --- |
| High | **SQL injection in order search**<br>The q parameter goes into a raw SQL query without parameters. | [src/orders/search.ts:42](...) |

<details>
<summary><b>Non-blocking (1)</b> — review when convenient</summary>

- **Medium — Missing authorization check on report export** · [src/reports/export.ts:88](...)

</details>

Reviewed 7 changed files. Each finding has an inline comment explaining the risk and the fix. [Full analysis →](https://app.vidoc.dev/...)

<small>💬 Have questions? Tag @vidoc in a comment and I'll answer.</small>
```

The last line shows the handle to use in commands and questions. On GitLab, it shows the username of the Vidoc bot user. On Bitbucket, the comment has no "Have questions?" line, because Vidoc does not read comments there.

### How the comments look on each platform

| Platform  | Formatting                                                                                                                                                                    |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GitHub    | Alert blocks such as `> [!CAUTION]` show as colored alerts. Collapsed sections work.                                                                                          |
| GitLab    | GitLab 17.10 and later show alert blocks as colored alerts. Earlier versions show a normal quote. Collapsed sections work.                                                    |
| Bitbucket | Vidoc converts its comments to Bitbucket markdown. Collapsed sections show expanded. The **Debug** section is removed. Alert blocks can show as normal quotes or bold labels. |

## Inline comments

For each finding in the summary, Vidoc starts a comment thread on the changed line. Vidoc writes these threads while the scan runs. Thus, some threads can appear before the summary comment shows the final result.

Each inline comment has these parts:

1. A header: **Potential issue · High severity** (or Critical, or Medium).
2. A short summary of the risk.
3. A collapsed **Explanation** section. On GitHub and GitLab, it also contains a **Debug** section with identifiers for Vidoc support.
4. A collapsed **Possible fix - diff** section, when Vidoc has a proposed fix.
5. An **Export to AI agent** link. It opens the finding in the Vidoc web app, where you can copy a prompt for an AI coding agent. You must have a Vidoc account to open this link.
6. A feedback prompt: "Did we do a good job? 👍 Was helpful, 👎 Needs improvement".

This is an example on GitHub:

```markdown theme={null}
> [!CAUTION]
> **Potential issue · High severity**
>
> The q parameter goes into a raw SQL query. An attacker can read or change data in the orders table.

<details>
  <summary>Explanation</summary>
  ...
</details>
<details>
  <summary>Possible fix - diff</summary>
  ...
</details>

📋 [Export to AI agent](https://app.vidoc.dev/...)

---
Did we do a good job? 👍 Was helpful, 👎 Needs improvement
<small>Questions about this finding? Tag @vidoc in a reply and I'll answer. Specific feedback or suggestions are welcome too!</small>
```

If your platform does not accept a thread on a line, Vidoc cannot write the inline comment. The finding still shows in the summary comment. On Bitbucket Data Center, Vidoc writes inline comments only on added lines.

To reply to a finding or react to it, refer to [Feedback](/pull-requests/feedback).

## Automatic thread resolution

Vidoc resolves its thread for a finding when a later scan analyzed all changed files and the finding is gone. After a **Partial review**, Vidoc does not resolve threads. This applies to all platforms.

## Status check

Vidoc can also show a status on the head commit of the PR. It shows only when status reporting is on for your installation.

| Platform  | What Vidoc shows                                                                                                    |
| --------- | ------------------------------------------------------------------------------------------------------------------- |
| GitHub    | A check run with the name **Vidoc Security Scan**. When the scan is complete, the check has a **Run Vidoc** button. |
| GitLab    | A commit status.                                                                                                    |
| Bitbucket | A build status.                                                                                                     |

The status shows as running while the scan runs. It shows as failed when Vidoc reports findings, when Vidoc could not analyze any changed file, or when the scan fails. It shows as successful when Vidoc finds no issues. Your platform uses this status to block a merge only if your team rules require it.

On GitHub, select **Run Vidoc** on the check to scan the PR again. You must have the write, maintain, or admin permission on the repository.

## When a scan fails

**What to expect.** If a scan fails, Vidoc does not update the summary comment. The comment continues to show "Currently scanning commit ...". Your platform shows a failure status only when status reporting is on. If the summary comment still shows this text after 30 minutes, the scan probably failed.

**What to do:**

1. On GitHub and GitLab, write `@<handle> rescan` as a new PR comment. On Bitbucket, push a new commit. On all platforms, you can also click **Rerun scan** on the PR in the [Pull requests](/web-app/pull-requests) page of the web app. You need the **Developer** role or higher in Vidoc.
2. If the comment still does not change, ask your AppSec team to contact Vidoc support.

A **Partial review** is not a failed scan. It means that Vidoc could not analyze some changed files. Push a new commit or send `@<handle> rescan` (GitHub and GitLab) to try again.

## Limits

| Limit                                                                                                                                                | What you can do                                                                                                                    |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| On GitLab and Bitbucket, each change to the title, description, or labels starts a new scan and stops the running scan. Many edits delay the result. | Make your title, description, and label changes together.                                                                          |
| Vidoc shows a status or check only when status reporting is on.                                                                                      | Use the summary comment.                                                                                                           |
| On Bitbucket, Vidoc does not read PR comments: no commands, questions, "remember" requests, or replies on findings.                                  | Push a new commit, or click **Rerun scan** in the web app, to scan again. Use the Vidoc web app to change the status of a finding. |
| On Bitbucket Data Center, inline comments are only on added lines.                                                                                   | Use the location link in the summary comment.                                                                                      |
| PR scans skip some file types.                                                                                                                       | Ask your AppSec team for a full scan of the default branch.                                                                        |
| Results can vary between scans, because the analysis uses large language models.                                                                     | If you think that Vidoc missed or added a finding in error, send `@<handle> rescan` or reply in the thread (GitHub and GitLab).    |

## Common questions

<Accordion title="Why is there no Vidoc comment on my PR?">
  * The scan still runs. Wait some minutes.
  * The PR changes only files that Vidoc does not scan in PR scans.
  * **PR reviews** or **PR comments** is off for the repository. Ask your AppSec team.
  * On Bitbucket, the repository has no Vidoc webhook. Ask your admin.
  * The scan failed. Send `@<handle> rescan` (GitHub and GitLab) or push a new commit (Bitbucket).
</Accordion>

<Accordion title="Why did my scan restart?">
  Each new commit starts a new scan and stops the old scan. On GitLab and Bitbucket, a change to the title, description, or labels also starts a new scan. A `restart` command (GitHub and GitLab) also starts a new scan.
</Accordion>

<Accordion title="Why is a finding in the summary but without an inline comment?">
  Your platform did not accept a thread on that line. On Bitbucket Data Center, this occurs when the finding is not on an added line. Use the location link in the summary.
</Accordion>

<Accordion title="Can I ignore a finding and merge?">
  Vidoc does not block the merge. Your team rules decide if you can merge. To tell Vidoc that a finding is wrong, refer to [Feedback](/pull-requests/feedback).
</Accordion>