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

# Harness

> Connect Harness CI so Gitar can read execution logs and analyze failures

export const ThemeImage = ({src, alt, width}) => {
  let lightSrc, darkSrc;
  if (src.includes("-light.")) {
    lightSrc = src;
    darkSrc = src.replace("-light.", "-dark.");
  } else if (src.includes("-dark.")) {
    darkSrc = src;
    lightSrc = src.replace("-dark.", "-light.");
  } else {
    lightSrc = src;
    darkSrc = src;
  }
  const style = width ? {
    maxWidth: width,
    marginInline: "auto"
  } : undefined;
  return <span>
      <img className="block dark:hidden rounded-lg border" src={lightSrc} alt={alt} style={style} />
      <img className="hidden dark:block rounded-lg border" src={darkSrc} alt={alt} style={style} />
    </span>;
};

Gitar reads the logs of every failing Harness execution and analyzes them. Cloud and Self-Managed both need one thing from you: a token that can read pipeline executions.

Harness reports an execution to the pull request as a commit status. That status links to the execution, and Gitar fetches the logs of the failed steps from the link. How you shape connectors and triggers is yours.

## Prerequisites

* Get permission to create a [service account](https://developer.harness.io/docs/platform/role-based-access-control/add-and-manage-service-account) under Account Settings in Harness.

## Setup

<Steps>
  <Step title="Create an account-level service account">
    In Harness, go to **Account Settings > Access Control > Service Accounts** and create one. The email fills itself in.

    <ThemeImage src="/assets/images/harness-service-account.png" alt="New Service Account in Harness" />

    One account-level service account covers every project you grant it, so onboarding a new repo later needs no new credential.
  </Step>

  <Step title="Bind Account Viewer to it">
    Click **Manage Role Bindings** and add **Account Viewer** with the **All Resources Including Child Scopes** [resource group](https://developer.harness.io/docs/platform/role-based-access-control/manage-resource-groups), which is the built-in group that reaches into orgs and projects.

    <ThemeImage src="/assets/images/harness-role-bindings.png" alt="Account Viewer bound with All Resources Including Child Scopes" />

    Wider than you can grant? See [Narrowing the grant](#narrowing-the-grant).

    <Note>
      Pipeline view (`core_pipeline_view` in Harness's [permissions reference](https://developer.harness.io/docs/platform/role-based-access-control/permissions-reference)) is the whole permission set Gitar needs. Reading logs has no permission of its own, it rides on pipeline view.
    </Note>
  </Step>

  <Step title="Add an API key, then a token under it">
    Under **API Keys**, add an [**API Key**](https://developer.harness.io/docs/platform/automation/api/add-and-manage-api-keys).

    <ThemeImage src="/assets/images/harness-api-key.png" alt="New API Key in Harness" />

    Then add a **Token** under that key and click **Generate Token**. Copy the token. It starts with `sat.`, and Harness shows it once.

    <ThemeImage src="/assets/images/harness-token.png" alt="New Token in Harness" />

    <Note>
      Leave **Expiration** at No Expiration, or note the date somewhere. An expired token stops log fetching, and the first sign of it is a red build Gitar says nothing about.
    </Note>
  </Step>

  <Step title="Connect Harness in Gitar">
    1. Go to your Gitar organization settings.
    2. Open **Integrations**.
    3. Find **Harness** and click **Connect**.
    4. Paste the service account token into **Harness API Token**.
    5. Leave **Harness Host** blank for Harness Cloud. For Self-Managed, set it to your server, for example `harness.mycompany.com`.

    Gitar checks the token against Harness as you paste it and shows the answer as a checklist:

    | Check | What it means |
    | - | - |
    | Harness connectivity | The token resolves to a Harness principal, and Gitar reached your instance |
    | Pipeline view permission | That principal can read executions and download step logs |

    **Connect** stays disabled while a check is running, and while Harness answers that the token cannot read pipelines. An instance Gitar cannot reach leaves **Connect** enabled, since no answer says nothing about your token.

    Leave the token field blank on a connected org to re-check the token already stored, which is the flow after fixing a role binding.

    <Note>
      Log fetching reads the server from the execution URL Harness posts, so the Host field only matters for checking a token before your first build has run. If you do set it, Gitar processes executions from that host only.
    </Note>

    <ThemeImage src="/assets/images/conn-harness-light.png" alt="Harness integration form with both token checks passing" />
  </Step>
</Steps>

## Narrowing the grant

Account Viewer with **All Resources Including Child Scopes** is the shortest path. Two ways to grant less:

* Build a [custom role](https://developer.harness.io/docs/platform/role-based-access-control/add-manage-roles) holding only the pipeline view permission, and bind that instead of Account Viewer.
* Create a custom [resource group](https://developer.harness.io/docs/platform/role-based-access-control/manage-resource-groups) listing the orgs or projects Gitar should read, and bind the role with that group. The group has to reach into projects. One covering account-level resources only leaves the token reading as unpermitted.

## What Gitar reads

Gitar reads the logs of the failed steps and passes them to CI failure analysis. It ignores a passing execution, and writes nothing back to Harness. Results appear as a comment on the pull request.

See [CI failure analysis](/features/ci-failure-analysis).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Pipeline view permission fails">
    The token is real but carries no usable role binding. In **Account Settings > Access Control**, bind **Account Viewer** to the service account with the **All Resources Including Child Scopes** resource group, or one of the narrower grants in [Narrowing the grant](#narrowing-the-grant).

    Harness evaluates role bindings per request, so a binding you add now starts working immediately. Clear the token field and the check re-runs against the stored token, so you do not need a new one.
  </Accordion>

  <Accordion title="Harness connectivity fails">
    * Confirm the token was copied whole, including the `sat.` prefix.
    * Check that the token has not expired or been revoked.
    * For Self-Managed, confirm **Harness Host** names the server your pipelines run on.
  </Accordion>

  <Accordion title="Gitar does not comment on a failed build">
    Check the pull request for a Harness status check.

    If there is no status, Harness is not reporting to your Git provider. Check its [connector API access](https://developer.harness.io/docs/platform/connectors/code-repositories/ref-source-repo-provider/git-hub-connector-settings-reference/) and [Git event triggers](https://developer.harness.io/docs/platform/triggers/triggering-pipelines).

    If the status is there, check that **Harness Host** is either blank or the host in the execution URL. Gitar drops the event on a mismatch.
  </Accordion>

  <Accordion title="Self-Managed on a private network">
    The token check runs from Gitar's API, so an instance reachable only over PrivateLink or an internal-only domain cannot be validated from the dialog. That shows as connectivity failing, and **Connect** stays enabled. Contact Gitar to arrange network access.

    See [Network access](/connecting-code/network-access).
  </Accordion>
</AccordionGroup>

## Security notes

* Gitar encrypts credentials and stores them in AWS Secrets Manager.
* Prefer a service account token (`sat.`) over a personal access token, so access survives people leaving.
* Pipeline view is read-only. Gitar writes nothing to Harness.
* Scope the resource group to the projects Gitar should read, if account-wide is more than you want to grant.
* To revoke access, delete the token from the API key it sits under.

## Harness references

| Topic | Harness documentation |
| - | - |
| Service accounts | [Manage service accounts](https://developer.harness.io/docs/platform/role-based-access-control/add-and-manage-service-account) |
| API keys and tokens | [Manage API keys](https://developer.harness.io/docs/platform/automation/api/add-and-manage-api-keys) |
| Roles and role bindings | [Manage roles](https://developer.harness.io/docs/platform/role-based-access-control/add-manage-roles) |
| Resource groups, including child scopes | [Manage resource groups](https://developer.harness.io/docs/platform/role-based-access-control/manage-resource-groups) |
| Permission names such as `core_pipeline_view` | [Permissions reference](https://developer.harness.io/docs/platform/role-based-access-control/permissions-reference) |


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