# GitHub Integration

The **Line of Code Insights (LOCI) Agentic AI** is a powerful tool designed to predict performance inefficiencies and power spikes in your compiled binaries *before* testing or inference. It autonomously optimizes code, configurations, and serving mechanisms. By integrating the LOCI GitHub Action into your workflow, you can shift observability left, reduce resolution time, and lower costs associated with hardware and software reliability issues.

### Key Capabilities

The LOCI GitHub Action allows you to:

* **Upload** compiled binaries for in-depth performance analysis.
* View a comprehensive **Agent Report** and insights directly in your workflow summary.
* Automatically receive **Pull Request (PR) comments** with analysis results (requires the GitHub App).

### Action Modes

The action operates in two primary modes via the `mode` input:

| Mode      | Description                                                                                                                                   | Required Inputs       |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `upload`  | Uploads compiled binaries to the LOCI backend for analysis.                                                                                   | `project`, `binaries` |
| `summary` | Waits for the analysis to complete and attaches the **Agent Report** (in Agentic Mode) and **Function Insights** to the workflow run summary. | `project`             |

### Prerequisites and Setup

Before using the action, ensure the following are configured in your repository:

#### Required Configuration

1. **GitHub Variable**: Add `LOCI_BACKEND_URL` as a GitHub Variable.
2. **GitHub Secret**: Add `LOCI_API_KEY` as a GitHub Secret.

#### Optional Configuration

1. **LOCI GitHub App**: **Install the LOCI GitHub App** on your repository to enable automatic PR comments with results and overall Performance Reviews.
2. **Agentic Summary Token**: If you are using **Agentic Mode** and want the `summary` step to display the full report in the job UI, you must provide a Personal Access Token (PAT) as a GitHub Secret (for example `LOCI_GITHUB_TOKEN`) and pass it to the action via an environment variable:

{% code title="Workflow snippet" %}

```yaml
env:
     LOCI_GITHUB_TOKEN: ${{ secrets.LOCI_GITHUB_TOKEN }} # required only for agentic summary
```

{% endcode %}

### Usage Examples

The action is sourced from `auroralabs-loci/loci-action@v1`.

#### Example 1: Build + Upload

This minimal example checks out code, builds a binary, and uploads it to LOCI for analysis.

{% code title=".github/workflows/loci-build-upload.yml" %}

```yaml
name: LOCI Integration
on:
  pull_request:
    types: [opened, synchronize, reopened]

env:
  LOCI_PROJECT: GHDemo

jobs:
  build-and-upload:
    runs-on: ubuntu-latest
    steps:
      - name: Prepare environment
        run: |
          sudo apt-get update
          sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Build sample
        run: |
          mkdir -p samples/build/bin
          aarch64-linux-gnu-g++ -o samples/build/bin/sample_01 samples/sample_01.cpp

      - name: Upload Artifacts
        uses: auroralabs-loci/loci-action@v1
        env:
          LOCI_API_KEY: ${{ secrets.LOCI_API_KEY }}
          LOCI_BACKEND_URL: ${{ vars.LOCI_BACKEND_URL }}
        with:
          mode: upload
          project: ${{ env.LOCI_PROJECT }}
          binaries: samples/build/bin/
```

{% endcode %}

#### Example 2: Build + Upload + Summary

This example adds the `summary` step, which waits for the analysis to complete and embeds the report and insights directly into the workflow run summary.

{% code title=".github/workflows/loci-build-upload-summary.yml" %}

```yaml
jobs:
  build-upload-and-summary:
    runs-on: ubuntu-latest
    steps:
      # ... (Your build and checkout steps here) ...

      - name: LOCI Upload
        uses: auroralabs-loci/loci-action@v1
        env:
          LOCI_API_KEY: ${{ secrets.LOCI_API_KEY }}
          LOCI_BACKEND_URL: ${{ vars.LOCI_BACKEND_URL }}
        with:
          mode: upload
          project: ${{ env.LOCI_PROJECT }}
          binaries: samples/build/bin/

      - name: LOCI Summary
        uses: auroralabs-loci/loci-action@v1
        env:
          LOCI_API_KEY: ${{ secrets.LOCI_API_KEY }}
          LOCI_BACKEND_URL: ${{ vars.LOCI_BACKEND_URL }}
          LOCI_GITHUB_TOKEN: ${{ secrets.LOCI_GITHUB_TOKEN }} # Only needed for agentic summary in job summary
        with:
          mode: summary
          project: ${{ env.LOCI_PROJECT }}
          top-n-symbols: 10 # Optional: customize the number of functions shown
```

{% endcode %}

### Inputs

| Input           | Required                | Default               | Description                                                                                                          |
| --------------- | ----------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `mode`          | **Yes**                 | —                     | Operation to perform: `upload` or `summary`.                                                                         |
| `project`       | **Yes**                 | —                     | Project name to tag the analysis results.                                                                            |
| `binaries`      | **Yes** (for `upload`)  | —                     | Newline-separated list of binary paths, glob patterns, or a directory. Required for `upload`, ignored for `summary`. |
| `target`        | No                      | `<branch>@<shortSHA>` | Project version label. Auto-resolves if not set.                                                                     |
| `base`          | No                      | PR merge base         | Base version to compare against. Empty unless set or PR context is used.                                             |
| `top-n-symbols` | **Yes** (for `summary`) | `5`                   | Number of functions shown in function insights during the `summary` step.                                            |

### Outputs

| Output    | Description                                                          |
| --------- | -------------------------------------------------------------------- |
| `target`  | The resolved project version name for this run.                      |
| `base`    | The resolved base version name (may be empty).                       |
| `summary` | The LOCI Agent Summary Report (only available when `mode: summary`). |

### LOCI Features and Modes Overview

LOCI supports a **Standard Mode** and a more comprehensive **Agentic Mode**, which is generally enabled per company/configuration.

| Feature                       | Standard Mode              | Agentic Mode               | GitHub App Required? | Where it Appears                                           |
| ----------------------------- | -------------------------- | -------------------------- | -------------------- | ---------------------------------------------------------- |
| **Upload of binaries**        | ✅ Yes                      | ✅ Yes                      | ❌ No                 | LOCI Dashboard (always)                                    |
| **Function Insights**         | ✅ Yes (via `summary` step) | ✅ Yes (via `summary` step) | ❌ No                 | Workflow run summary (`summary` step)                      |
| **LOCI Agent Summary Report** | ❌ Not available            | ✅ Yes                      | ✅ For PR comment     | Workflow run summary (`summary` step\`) & PR comment (App) |
| **Performance Review Check**  | ❌ Not available            | ✅ Yes                      | ✅ Yes (App only)     | GitHub Checks tab (pass/fail based on `loci.yml` config)   |

Key Workflow Logic:

* The **`upload` step** is always required to send binaries to the LOCI backend.
* The **`summary` step** is optional and is only needed if you want the LOCI report and insights within the workflow run summary itself.
  * In **Standard Mode**, the summary step adds **Function Insights** only.
  * In **Agentic Mode**, the summary step adds the **Agent Summary Report** plus **Function Insights**.
* If the **GitHub App is installed** (and Agentic Mode is enabled), it automatically handles:
  * Posting the **LOCI Agent Summary Report as a PR comment**.
  * Enabling the **Performance Review Check Run** (pass/fail status based on configuration).