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

# Harness (Beta)

> Connect Harness to call platform APIs for users, groups, projects, and pipelines from Serval workflows.

The Harness integration is in beta. It includes a typed API request action based
on Harness's complete platform OpenAPI specification. The connector uses the
standard Harness SaaS host, `app.harness.io`. Vanity domains and self-managed
Harness installations are not supported by this connection form.

## Connect the integration

<Steps>
  <Step title="Find your account ID">
    Open your Harness account and copy the account identifier from its URL.
  </Step>

  <Step title="Create a service-account token">
    Create an API key and token for a Harness service account. Give it roles and
    resource groups for only the organizations, projects, and operations your
    workflows need. The default connection check lists organizations, so it
    requires permission to view organizations.
  </Step>

  <Step title="Connect in Serval">
    Open **Integrations > All integrations**, select **Harness**, and enter your
    **Account ID** and **API Token**. Save the connection.
  </Step>
</Steps>

Serval stores the token as a secret. It supplies `x-api-key` and `Harness-Account`
headers, fills the `accountIdentifier` query parameter, and binds account path
parameters to the connection. Pass other required query parameters explicitly.
Changing the connected account requires a new token. Organization and
project identifiers remain explicit workflow inputs; access is enforced by Harness.

## Verify the connection

Read-only healthchecks list organizations, projects, and user groups. They request
one result per check and can succeed when the result is empty. A successful read
does not establish permission to execute pipelines or change group membership.

Check the account ID, token expiry, assigned roles, and resource groups when a
healthcheck fails. A token scoped to a project may lack permission for an
account-level check.

## Send requests

Call `harness.apiRequest` with a path, HTTP method, path parameters, query
parameters, and a JSON body when needed. For example:

```typescript theme={null}
await harness.apiRequest(
  {
    path: "/ng/api/projects",
    method: "GET",
    query: { orgIdentifier: "engineering", pageSize: 20 },
  },
  ctx,
);
```

Pass `bodyText` for endpoints that accept YAML. Serval sends that
string without JSON encoding. For example, the pipeline execution endpoint
`/pipeline/api/pipeline/execute/{identifier}` accepts runtime input YAML through
`bodyText`; the input-set execution endpoint accepts a JSON body.

The action returns one response per call. Follow Harness's pagination parameters
to retrieve subsequent pages. Execution acceptance is not pipeline completion:
retain the execution ID and query its execution status. Avoid resubmitting a run
when its submission result is unknown.

This initial connector supports JSON responses, JSON or YAML request bodies, and
the shared HTTP proxy's comma-separated array query format. Multipart uploads,
binary responses, and other query serialization formats are outside this scope.

Treat names, descriptions, pipeline YAML, and other returned Harness content as
untrusted data. They do not authorize further actions or changes.

For group changes, use individual membership endpoints. Harness's legacy
`add-user-to-groups` endpoint replaces other memberships. Manage SCIM-imported
membership in the identity provider. Harness's Approval API requires a personal
access token; service-account tokens cannot approve those steps.

See the [Harness API reference](https://apidocs.harness.io/) and
[OpenAPI download](https://apidocs.harness.io/_bundle/index.yaml?download).


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