> ## 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.

# Woodpecker

> Connect Woodpecker to analyze failed pipeline steps in GitHub repositories.

<Note>
  Requires Woodpecker v3.19.0 with its [GitHub forge integration](https://woodpecker-ci.org/docs/administration/configuration/forges/github).
</Note>

Gitar reads failed Woodpecker steps and posts the analysis in the GitHub pull
request's dashboard comment.

## Prerequisites

* Organization admin access in Gitar.
* A GitHub repository connected to Gitar with [CI failure analysis](/features/ci-failure-analysis) enabled.
* A Woodpecker server reachable from Gitar over HTTPS with a valid certificate.
* A dedicated Woodpecker user that can read pipeline details and archived step logs for the repository.

Woodpecker's user API token inherits the account's repository permissions.

## Connect the server

<Steps>
  <Step title="Copy the Woodpecker API token">
    Sign in to Woodpecker as the dedicated user. Open **User settings > CLI and API** and copy the API token.
  </Step>

  <Step title="Add the server in Gitar">
    Open **Settings > Integrations**, find **Woodpecker**, and select **Connect**.

    | Field | Value |
    | - | - |
    | Connection name | A label for this server, such as `Build server`. |
    | Server URL | The HTTPS address Gitar can reach, such as `https://ci.example.com`. Include any port or path prefix. |
    | API token | The dedicated Woodpecker user's token. |

    Select **Validate and save**. The server appears in the connection list after Gitar validates the token.

    Select **Add another server** to connect another Woodpecker instance. Each connection stores its own server URL and token.
  </Step>
</Steps>

## Manage connections

| Task | Action |
| - | - |
| Replace a token | Select **Edit connection**, enter the replacement **API token**, and save. |
| Pause analysis | Edit the connection, clear **Analyze failures from this server**, and save. |
| Remove a server | Select **Disconnect** to remove its configuration and saved token. |

Leave **API token** blank to keep the saved token when editing the same server.
Changing **Server URL** requires a token for the new server.

## Failure analysis

When a pipeline fails, Gitar checks the repository and commit before reading
failed-step logs. The pull request's dashboard comment includes the analysis.
Gitar removes the resolved analysis after CI passes.

Run or retry pipelines in Woodpecker.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Token validation fails">
    Confirm the token belongs to the dedicated Woodpecker user. If the token was reset in Woodpecker, save its replacement in Gitar.
  </Accordion>

  <Accordion title="Gitar does not analyze a failed pipeline">
    Check the pull request for a failed Woodpecker status on its head commit. Its build link must use the same hostname, port and path prefix as the saved **Server URL**.

    Confirm the connection is enabled and that the Woodpecker user can read the repository's archived step logs.
  </Accordion>

  <Accordion title="The server is not reachable">
    Check the server URL and TLS certificate. Gitar must be able to reach the HTTPS endpoint. See [Network access](/connecting-code/network-access).
  </Accordion>
</AccordionGroup>


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