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

# Bitrise

> Connect Bitrise for enhanced failure analysis and automatic fixes

export const ThemeImage = ({src, alt}) => {
  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;
  }
  return <span>
      <img className="block dark:hidden rounded-lg border" src={lightSrc} alt={alt} />
      <img className="hidden dark:block rounded-lg border" src={darkSrc} alt={alt} />
    </span>;
};

Gitar automatically integrates with **GitHub Actions** and **GitLab Pipelines** -- no setup required. If you use Bitrise as an external CI platform, connect it here so Gitar can read build logs, analyze failures, and push fixes.

## Prerequisites

* Access to your Bitrise workspace
* Admin permissions to create workspace tokens

## Why Workspace Tokens?

Bitrise recommends **Workspace API tokens** for integrations because they provide centralized management, simplified setup, and better security -- token access isn't tied to individual user accounts, preventing disruption when team members leave.

## Setup

<Steps>
  <Step title="Create a Bitrise Workspace Token">
    1. Log into your Bitrise account
    2. Navigate to your **Workspace Settings**
    3. Go to the **Security** tab
    4. Click **"Create token"**
    5. Configure the token:
       * **Name**: "Gitar Integration"
       * **Expiration**: Set according to your security policy (or no expiration)
       * **Role access**: Choose "All apps" and set role to **Developer** or higher
    6. Click **"Create"** and copy the token immediately (you won't be able to see it again)

    <Note>
      For Gitar to monitor builds and access logs, the workspace token needs at least **Developer** role access to your apps.
    </Note>
  </Step>

  <Step title="Access Gitar Integrations">
    1. Navigate to your Gitar organization settings
    2. Go to the **Integrations** section
    3. Find the **Bitrise** integration
    4. Click **"Connect"** to begin the setup process
  </Step>

  <Step title="Configure and Connect">
    Enter your Bitrise Workspace API Token. The token will be securely stored and encrypted.

    <ThemeImage src="/assets/images/conn-bitrise-dark.png" alt="Bitrise integration form" />

    1. Fill in the required workspace token field
    2. Click **"Connect Bitrise"** to establish the connection
    3. If successful, the integration status will show as connected
    4. If the connection fails, verify your token is valid and has sufficient permissions
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Failed">
    If your connection fails, verify:

    * Workspace API token is correct and valid
    * Token has at least **Developer** role access to your apps
    * Token has not expired
    * You have admin permissions to create workspace tokens
    * Bitrise service is accessible
  </Accordion>

  <Accordion title="Invalid Token Error">
    If you receive an "Invalid Bitrise API token or insufficient permissions" error:

    * Check that you've copied the workspace token correctly
    * Verify the token has **Developer** or higher role for the apps you want to monitor
    * Ensure the token hasn't expired
    * Confirm you created a Workspace API token (not a Personal Access Token)
    * Try creating a new workspace token if the issue persists
  </Accordion>

  <Accordion title="Missing Build Data">
    If Gitar isn't detecting your builds:

    * Ensure your repositories are connected to both your Git provider and Bitrise
    * Verify your Bitrise apps are properly configured
    * Check that status checks are enabled in your Git provider for Bitrise
    * Confirm the workspace token has access to the relevant apps
  </Accordion>
</AccordionGroup>

## Security Notes

* API tokens are encrypted and securely stored using AWS Secrets Manager
* Tokens can be revoked at any time from your Bitrise account settings
* We recommend rotating tokens regularly for enhanced security
* Use service accounts for production environments to avoid disruption when team members leave
* Only grant the minimum required scopes for your use case