CI/CD Pipeline Integrations

Overview

Validatar's Authoring API supports exporting tests and jobs from one project and importing them into another. This enables CI/CD workflows where test content is promoted across environments (e.g., development to staging to production) as part of your deployment pipeline.

The export produces an XML file (base64-encoded) containing the full definition of selected tests, jobs, and their folder structure. The import endpoint accepts this file and creates or updates the content in the target project.

Authentication

All CI/CD API calls use a custom header:

x-val-api-token: {your_api_token}

Create an API token with the Authoring scope (and Execution scope if you plan to run tests after import). A single token can have multiple scopes. See User Tokens for setup instructions.

Base URL

{VALIDATAR_API_URL}/core/api/v1/{endpoint}

Replace {VALIDATAR_API_URL} with your Validatar instance URL (e.g., https://mycompany.cloud.validatar.com).

Common Pattern

1. Export — POST to the export endpoint on the source project with the tests, jobs, or folders to include
2. Transfer — POST the export payload (base64 XML) to the import endpoint on the target project with data source mappings
3. Validate — optionally execute the imported tests or jobs to verify they work in the target environment
4. Report — surface import and execution results in the pipeline output

Key API Endpoints

Export Request

{
  "name": "my-export-2026-04-02",
  "description": "Weekly promotion from dev to staging",
  "testFolderIds": [101, 102],
  "jobFolderIds": [201],
  "testIds": [5001, 5002],
  "jobIds": [3001],
  "includeCustomFields": true,
  "includeJobSchedules": false
}

Tip: You can export by folder or by individual test/job. For CI/CD, organizing tests into promotion-ready folders makes export simpler — export the entire folder rather than tracking individual IDs.

Export Response

{
  "fileName": "my-export-2026-04-02.xml",
  "mimeType": "application/xml",
  "contentBase64": "PFZhbGlkYXRhckV4cG9ydD4..."
}

The contentBase64 field contains the full export file as a base64-encoded XML string. This is the payload you pass to the import endpoint.

Tip: For troubleshooting, decode the base64 content and save it as a local .xml file. The XML format is human-readable and can help you verify what was exported.

Import Request

{
  "mimeType": "application/xml",
  "contentBase64": "PFZhbGlkYXRhckV4cG9ydD4...",
  "targetTestFolderId": 301,
  "targetJobFolderId": 401,
  "dataSourceMappings": [
    {
      "sourceFileKey": "42",
      "targetId": 87
    }
  ],
  "includeJobSchedules": false,
  "conflictResolution": "Overwrite"
}

Data Source Mappings

When tests reference data sources in the source project, those data sources may have different IDs in the target project. The dataSourceMappings array tells Validatar how to remap them.

The sourceFileKey is the data source ID from the source project (visible in the export file or discoverable via GET /core/api/v1/data-sources). The targetId is the corresponding data source ID in the target project.

"dataSourceMappings": [
  { "sourceFileKey": "42", "targetId": 87 },
  { "sourceFileKey": "43", "targetId": 88 }
]

Tip: Use the GET /core/api/v1/data-sources endpoint on both the source and target instances to list data sources with their IDs and names, then build the mapping by matching names.

Conflict Resolution

For CI/CD pipelines, Overwrite is the recommended default. Running the same import repeatedly with Overwrite is safe and idempotent.

Import Response

A successful import returns 200 OK with no body.

A failed import returns 400 Bad Request with details:

{
  "validationErrors": ["Error description"],
  "invalidDataSources": [
    {
      "sourceFileKey": "42",
      "message": "Data source not found"
    }
  ],
  "invalidMacros": [],
  "commitErrors": ["Error description"]
}

Finding IDs

Project, test, job, and folder IDs are visible in the Validatar UI URL:

https://mycompany.cloud.validatar.com/projects/43/folders/1408/tests/57878

You can also discover IDs programmatically:

GET /core/api/v1/projects                    → list projects with IDs
GET /core/api/v1/data-sources                → list data sources with IDs and names
GET /core/api/v1/projects/{id}/folders/{id}  → get folder details

Guides in This Section

• GitHub Actions — highly requested; includes both CI/CD and orchestration examples
• Bitbucket Pipelines — full standalone pipeline definitions
• Azure DevOps Pipelines
• Generic CI/CD (Other Tools) — portable Python, PowerShell, and Bash scripts for any CI/CD platform