---
title: "Create a dry-run validation task"
method: POST
path: "/admin/gitops/validate"
tags: ["GitOps", "Admin"]
---

# Create a dry-run validation task

`POST /admin/gitops/validate`

**Experimental.** Creates a dry-run validation task that fetches a git ref and validates the data without affecting the live registry. The sidecar fetches the ref, and the registry loads and validates the data in the inactive storage (no swap).

Returns a task object with a `taskId` that can be used to poll for results.

This endpoint is only available when GitOps storage is enabled.

This operation can fail for the following reasons:

* GitOps storage is not enabled (HTTP error `409`)
* Dry-run validation is disabled (HTTP error `503`)
* A server error occurred (HTTP error `500`)

## Request body

- GitOpsValidateRequest — Request body for creating a dry-run validation task.
  - `type` 'pull' — Validation type. Currently only `pull` is supported.
  - `repoId` string, required — Repository ID to validate against. Must match a configured repository.
  - `ref` string, required — Git ref to validate (branch name, tag, or PR ref like `refs/pull/42/head`).

## Response `202`

Validation task created. Poll the task status to get the result.

- GitOpsValidateTask — Represents a dry-run validation task with its current state and results.
  - `taskId` string, required — Unique identifier for the validation task.
  - `type` string — Validation type (`pull` or `push`).
  - `repoId` string — Repository ID being validated.
  - `ref` string — Git ref being validated.
  - `state` 'pending' | 'submitted' | 'fetching' | 'validating' | 'completed' | 'failed', required — Current task state: `pending` (queued, waiting for capacity), `submitted` (request sent to sidecar), `fetching` (sidecar is cloning), `validating` (registry is loading and validating), `completed` (finished with results), `failed` (an error occurred).
  - `result` 'success' | 'failure' — Validation result: `success` (all checks passed) or `failure` (validation errors found). Only present when state is `completed`.
  - `createdAt` string, date-time — ISO 8601 timestamp of when the task was created.
  - `completedAt` string, date-time — ISO 8601 timestamp of when the task completed. Only present when state is `completed` or `failed`.
  - `groupCount` integer — Number of groups loaded during validation. Only present when state is `completed`.
  - `artifactCount` integer — Number of artifacts loaded during validation. Only present when state is `completed`.
  - `versionCount` integer — Number of artifact versions loaded during validation. Only present when state is `completed`.
  - `errors` GitOpsError[] — Validation errors. Empty if validation passed.
    - `detail` string, required — A human-readable description of the error.
    - `source` string — The source ID (e.g., repository ID) where the error occurred. Absent for global errors not tied to a specific source.
    - `context` string — The file path or location where the error occurred. Absent if the error is not file-specific.

## Other responses

- `401` — Common response for all operations that can return a `401` error indicating authentication is required.
- `403` — Common response for all operations that can return a `403` error indicating the user is authenticated but not authorized.
- `409` — Common response used when an input conflicts with existing data.
- `500` — Common response for all operations that can fail with an unexpected server error.
- `503` — Dry-run validation is disabled. Enable it by setting `apicurio.gitops.validate.enabled=true`.

---

[API](https://skmtc.net/apicurio/apis/apicurio-registry-api-v3.md) · [All operations](https://skmtc.net/apicurio/apis/apicurio-registry-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/apicurio/apicurio-registry-api-v3/revisions/c39cb56d7dbc/schema)