> For the complete documentation index, see [llms.txt](https://www.quillaudits.com/quillshield/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.quillaudits.com/quillshield/developers/ci-cd-checks.md).

# CI/CD Checks

Trigger CI scans, GitHub App automation, GitLab.com webhooks, and optional GitHub Actions.

PR and merge-request checks are **not** `POST /v1/audit/submit` (that path creates a paid full-audit quote).

Product walkthrough: [CI/CD Checks (Guides)](https://www.quillaudits.com/quillshield/guides/guides/ci-cd-checks).

## Prerequisites

1. Create a **git** project for the repository (GitHub `owner/repo` or GitLab.com, including subgroup paths).
2. Complete a **full** audit with a stored security graph on the CI base branch. The baseline must be an **ancestor** of the scan target (not necessarily the exact PR `base.sha`).
3. Settings → API keys → create a `qs_live_…` key (owner/admin). Spend uses the **org owner** wallet.
4. Note **org id** and **project id**.

## Dashboard / App / Actions trigger

The product path is:

```http
POST /v1/ci/scans/trigger
Authorization: Bearer qs_live_…
X-Org-Id: <org_ulid>
X-QuillShield-Client: ci
```

```json
{
  "project_id": "01…",
  "pull_request_number": 42,
  "fail_on": "high"
}
```

The server resolves the audited baseline, imports the target, and queues the scan. You can also pass `head_sha` / `branch` for commit scans. Admin+ required. The same trigger works for a GitLab.com project’s merge request number when that project is connected.

## Advanced two-commit API

```http
POST /v1/ci/scans
```

```json
{
  "project_version_id": "01…",
  "base_sha": "<audited ancestor SHA>",
  "head_sha": "<resolved version commit_sha>",
  "repository": "owner/repo",
  "pull_request_number": 42,
  "fail_on": "high",
  "changed_files": ["src/Vault.sol"],
  "mode": "light"
}
```

* `mode`: `light` (default) or `full` (starts a paid full-audit path from CI).
* Light scans **409** if there is no baseline graph. New `.sol` files or ΔSLOC **> 150** (or **> 5** changed Solidity files) still **run** and set `full_audit_recommended` — they are not a hard block.
* HTTP **402** if free light scans are used up and the wallet cannot cover `$5 + $0.10 × max(0, ΔSLOC − 50)`.

Poll `GET /v1/audits/:job_id`. For light scans, treat `security_conclusion` / the host check `fail_on` as the gate.

Related reads (JWT + connected host):

```http
GET /v1/ci/base?project_id=…
GET /v1/ci/pulls?project_id=…&state=open
GET /v1/ci/commits?project_id=…
PATCH /v1/ci/monitor
```

## GitHub App

Install from the dashboard Setup URL. Callback is `POST /v1/ci/github-app/callback` (user authorization during install is required). Webhook: `POST /v1/webhooks/github`.

Monitor flags: `monitor_pull_requests: off | anyone`, `monitor_commits`, optional `ci_base_branch`. Dashboard switches are the source of truth. Repository `.solidity-review.yml`, `@quillshield` commands, and merge-queue orchestration are **not** supported.

## Optional GitHub Actions

Copy the workflow from **CI/CD Checks → Setup**. Secrets: `QUILLAUDITS_API_KEY`, `QUILLAUDITS_ORG_ID`. The workflow calls `POST /v1/ci/scans/trigger` and waits. It does not check out repository code. Fork PR workflows do not receive secrets; use the App for forks.

Send `X-QuillShield-Client: ci`.

## GitHub Checks and comments

When a scan finishes, the API publishes a GitHub **Check**, commit status, and a sticky PR comment when the App or a connected OAuth token can write. Without credentials, the scan still completes in QuillAudits.

## GitLab.com

GitLab.com projects do not use a GitLab App. Connect the user (`GET /v1/auth/oauth/gitlab/url` or Continue with GitLab). Turning on **Scan Merge Requests** or **Scan Every Commit** registers a project hook delivered to `POST /v1/webhooks/gitlab`.

Finished scans post a commit status named **QuillShield Check** and a sticky merge-request note, using the user’s refreshed OAuth token. Self-managed GitLab is not supported. Browse repos with `GET /v1/git/gitlab/repos`.

## Full audits from the CLI (different path)

`qs audit … --yes` still creates a **full-audit** quote priced with `QS-PAYG-USD-V6`. See CLI: CI/CD.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.quillaudits.com/quillshield/developers/ci-cd-checks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
