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

# Review code with Otto

<Info>
  **Labs**

  This feature is in [Labs](/docs/astro/feature-previews).
</Info>

Otto reviews your Airflow code automatically when you open a pull request or merge request. The Otto review action runs Otto with a dedicated reviewer persona, posts inline review comments where the code has issues, and offers commit suggestions where a concrete fix is available.

The review runs Otto with `--persona reviewer`. The persona bundles the Astro and Airflow review prompt, a read-only tool allowlist, plan-mode permissions, and a structured verdict schema, so Otto returns review results tuned for Airflow projects rather than generic code review. See [Personas](/docs/cli/v1.43/astro-otto#personas).

The action supports both GitHub and GitLab:

* **GitHub**: A composite GitHub Action that runs on `pull_request` and posts the review to the pull request.
* **GitLab**: A CI/CD template and Docker image that run on merge request events and post the review to the merge request.

## What Otto reviews

Otto reviews changes against three layers of knowledge, so it catches issues that generic code review misses:

* **Astronomer compatibility knowledge**: Version-specific operator behavior, provider compatibility, deprecated patterns, and failure signatures drawn from the Astronomer compatibility knowledge base. This is the same knowledge base that powers [Airflow upgrades with Otto](/docs/astro/otto-upgrades).
* **Airflow community standards**: Current Dag patterns, testing approaches, and structure recommendations from the Apache Airflow community.
* **Your team's conventions**: Standards, retry policies, approved operators, and patterns captured in [Otto Memory](/docs/astro/otto-memory). Otto surfaces deviations from your conventions before they reach a human reviewer.

## How it works

On each run, the action:

1. Checks out the changed code and gathers the pull request or merge request metadata, the diff, and the prior review conversation.
2. Runs `astro otto --mode json --persona reviewer` against the gathered context.
3. Posts the result back to the pull request or merge request.

The reviewer persona returns a structured verdict with these fields:

* **`verdict`**: `approve`, `comment`, or `request_changes`.
* **`summary`**: A one-sentence summary of the change.
* **`reasoning`**: One to three sentences on the change as a whole.
* **`comments`**: Line-anchored findings, each with a severity of `high`, `medium`, or `low` and an optional commit suggestion.

On re-runs, the action edits its existing comments in place rather than re-posting. It keeps one sticky summary comment, updates or leaves its prior inline comments instead of duplicating them, and only re-posts the merge-gating review when the verdict changes.

## Prerequisites

* An Astro [Organization API token](/docs/astro/organization-api-tokens). The token only needs the Organization member permission.
* A GitHub repository or GitLab project that contains an Airflow project.

## Set up the review action

<Tabs>
  <Tab title="GitHub">
    On GitHub, the review runs as the [Otto Review](https://github.com/marketplace/actions/otto-review) action from the GitHub Marketplace. Add it to a workflow that runs on pull requests. To get the latest version, click **Use latest version** on the Marketplace listing.

    <Steps>
      <Step title="Add the workflow">
        In your repository, create a workflow file at `.github/workflows/otto-review.yml` with the following content:

        ```yaml title=".github/workflows/otto-review.yml" wrap theme={null}
        name: Astronomer CI - Review Code
        on:
          pull_request:
            branches:
              - main

        permissions:
          contents: read
          pull-requests: write

        env:
          ASTRO_API_TOKEN: ${{ secrets.ASTRO_API_TOKEN }}
          ASTRO_ORGANIZATION: ${{ secrets.ASTRO_ORGANIZATION }}

        jobs:
          review:
            runs-on: ubuntu-latest
            steps:
              - name: Otto Review
                uses: astronomer/otto-review-action@v0.2.0
        ```
      </Step>

      <Step title="Add the required secrets">
        In your repository, go to **Settings** > **Secrets and variables** > **Actions** and add the following repository secrets:

        * `ASTRO_API_TOKEN`: Your Astro Organization API token.
        * `ASTRO_ORGANIZATION`: Your Astronomer Organization ID.
      </Step>

      <Step title="Open a pull request">
        Open a pull request against the `main` branch. The action runs Otto, posts a sticky summary comment, and adds inline comments where it finds issues.
      </Step>
    </Steps>
  </Tab>

  <Tab title="GitLab">
    GitLab has no marketplace for the action. Copy the CI/CD template into your project, or point your agent to the [otto-review-action repository](https://github.com/astronomer/otto-review-action).

    <Steps>
      <Step title="Add the CI/CD job">
        In your project's `.gitlab-ci.yml`, add the `otto_review` job:

        ```yaml title=".gitlab-ci.yml" wrap theme={null}
        otto_review:
          image: ghcr.io/astronomer/otto-review:v0
          rules:
            - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
          variables:
            OTTO_MAX_DIFF_LINES: "50000"
            OTTO_DRY_RUN: "false"
          script:
            - bash /opt/otto-review/gitlab/run-review.sh
        ```

        The image bakes the Astro CLI and the review scripts, so the job needs no repository clone and no per-run install. Pin the image tag to `:v0` to track the latest `v0.x` release, or use `:vX.Y.Z` to pin an exact version.
      </Step>

      <Step title="Add the required variables">
        In your project, go to **Settings** > **CI/CD** > **Variables** and add the following masked variables:

        * `ASTRO_API_TOKEN`: Your Astro Organization API token.
        * `ASTRO_ORGANIZATION`: Your Astronomer Organization ID.
        * `GITLAB_TOKEN`: A personal access token or project access token with the `api` scope. The `CI_JOB_TOKEN` isn't sufficient for the notes and discussions API.
      </Step>

      <Step title="Open a merge request">
        Open a merge request. The job runs Otto, posts a sticky summary note, and adds inline comments where it finds issues.
      </Step>
    </Steps>

    <Note>
      On GitLab, the action posts the verdict through the sticky summary and inline notes. It never approves or blocks the merge request, because GitLab has no native request-changes review event.
    </Note>
  </Tab>
</Tabs>

## Run a review on demand

Code review also works outside a CI/CD pipeline. Run the reviewer persona from your terminal to review changes before you push, or to audit existing pipelines that haven't been through a structured review:

```sh wrap theme={null}
astro otto --persona reviewer "review the Dags in this project"
```

See [`astro otto`](/docs/cli/v1.43/astro-otto#personas) for the full persona reference.

## Configure the review

Both platforms accept settings that change how the review runs. On GitHub, pass them as action inputs under `with:`. On GitLab, set them as CI/CD variables. The most common settings are:

| GitHub input     | GitLab variable       | Description                                                                                        |
| ---------------- | --------------------- | -------------------------------------------------------------------------------------------------- |
| `model`          | `OTTO_MODEL`          | Override the model Otto uses. The default uses the model that the reviewer persona's tier maps to. |
| `allowed-tools`  | `OTTO_ALLOWED_TOOLS`  | Override the reviewer persona's read-only tool allowlist (`read`, `grep`, `find`, `ls`, `bash`).   |
| `max-diff-lines` | `OTTO_MAX_DIFF_LINES` | Truncate diffs longer than this value. The default is `50000`.                                     |
| `dry-run`        | `OTTO_DRY_RUN`        | When `true`, post the summary and inline comments but no merge-gating review.                      |

For the complete list of inputs, variables, and outputs, see the [otto-review-action repository](https://github.com/astronomer/otto-review-action).

## Related

* [Otto overview](/docs/astro/otto-overview)
* [Investigate with Otto](/docs/astro/otto-investigate)
* [`astro otto`](/docs/cli/v1.43/astro-otto)
* [Deploy code with the Astro GitHub integration](/docs/astro/deploy-github-integration)
* [Skills](/docs/astro/otto-skills)