> ## 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 integrates with **GitHub Actions** and **GitLab Pipelines** with no setup. Harness (Cloud or Self-Managed) needs one thing from you: a token that can read pipeline executions.

Harness posts build results to the pull request as a commit status, and that status links to the execution. Gitar reads the link, pulls the logs for the steps that failed, and analyzes from there. How you shape connectors and triggers is yours, we only need the status to show up.

## Prerequisites

* 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" />

    <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. If Account Viewer grants more than you want, build a [custom role](https://developer.harness.io/docs/platform/role-based-access-control/add-manage-roles) holding only that permission and bind it instead.
    </Note>

    <Note>
      **Granting a subset of projects.** Create a custom resource group that lists the orgs or projects Gitar should read, then bind the role with that group instead. The group has to reach into projects. One covering account-level resources only leaves the token reading as unpermitted.
    </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 it immediately, it starts with `sat.` and Harness does not show it again.

    <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. Navigate to your Gitar organization settings
    2. Go to the **Integrations** section
    3. Find the **Harness** integration 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 (e.g. `harness.mycompany.com`)

    Gitar checks the token against Harness as you paste it and shows the answer as a checklist. **Connect** stays disabled while a check is running and when Harness answers that the token cannot read pipelines. If we cannot get an answer at all (an instance we cannot reach, or an error on our end), **Connect** stays enabled, since that says nothing about your token:

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

    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-dark.png" alt="Harness integration form with both token checks passing" />
  </Step>
</Steps>

## What Gitar reads

On a failing execution, Gitar pulls the logs for the steps that failed and hands them to CI failure analysis. A green execution is left alone. Nothing is written back to Harness, Gitar comments on the pull request instead.

See [CI failure analysis](/features/ci-failure-analysis) for what happens with those logs.

## 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** (or a custom role holding only the Pipelines view permission) to the service account, with **All Resources Including Child Scopes** or a custom group listing the projects Gitar should read. A group covering account-level resources only does not reach into projects.

    Role bindings are evaluated per request, so a binding you add now starts working immediately. Clear the token field and the check re-runs against the stored token. You do not need to mint a new one.
  </Accordion>

  <Accordion title="Harness connectivity fails">
    * Confirm the token was copied whole, including the `sat.` prefix
    * Check 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 says nothing about a failed build">
    Open the pull request and look for a Harness status check. No status means Harness never told your Git provider the build ran, which is Harness-side configuration: 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) are where to look.

    If the status is there and Gitar still stayed quiet, check that **Harness Host** either is blank or matches the host in the execution URL. A mismatch drops the event.
  </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, since a host we cannot reach says nothing about your token. Reach out and we will wire up network access.

    See [Network access](/connecting-code/network-access) for the general shape of this.
  </Accordion>
</AccordionGroup>

## Security notes

* Tokens are encrypted and stored 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, and Gitar writes nothing to Harness. Grant nothing wider
* Scope the resource group to the projects Gitar should read if account-wide is more than you want to grant
* Revoke the token from Harness at any time to cut off access

## Harness references

| Topic                                       | Harness docs                                                                                                                   |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 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, e.g. `core_pipeline_view` | [Permissions reference](https://developer.harness.io/docs/platform/role-based-access-control/permissions-reference)            |