Setup

This guide walks you through adding the Odin Scan GitHub Action to your repository. By the end, every pull request will be automatically scanned for smart contract vulnerabilities.

Prerequisites

Before you begin, make sure you have:

1. An Odin Scan account – sign up at odinscan.ai. You can sign up with GitHub to automatically link your repositories.
2. An Odin Scan API key – navigate to Settings > API Keys in the dashboard and create a new key. Keys start with odin_sk_.
3. A repository containing smart contracts – CosmWasm (Rust), Solana (Rust/Anchor), or EVM (Solidity/Vyper).
4. Repository admin access – required to install the GitHub App, add secrets, and configure workflows.

Step 1: Install the Odin Scan GitHub App

The GitHub App allows Odin Scan to post PR comments, add inline annotations, and report findings on your repositories.

1. Go to your repository on GitHub.
2. Navigate to Settings > Integrations > GitHub Apps.
3. Click Install next to Odin Scan.
4. Select the repositories you want to enable and confirm the installation.

If you don’t see Odin Scan listed, visit the Odin Scan GitHub App page and click Install.

Step 2: Store Your API Key

Add the API key as a GitHub repository secret:

1. Go to your repository on GitHub.
2. Navigate to Settings > Secrets and variables > Actions.
3. Click New repository secret.
4. Set the name to ODIN_SCAN_API_KEY and paste your key as the value.
5. Click Add secret.

Step 3: Create the Workflow File

Create the file .github/workflows/odin-scan.yml in your repository with the following contents:

name: Odin Scan Security Analysis
on:
  pull_request:
    branches: [main, master]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: odin-scan/odin-scan-action@v1
        with:
          api-key: ${{ secrets.ODIN_SCAN_API_KEY }}

Step 4: Commit and Open a Pull Request

Push the workflow file to your repository. The next time a pull request targets main or master, Odin Scan will automatically analyze your contracts and report findings.

What Happens During a Scan

When the action runs, it:

1. Sends your source code to the Odin Scan API for analysis.
2. Waits for results (up to 30 minutes by default).
3. Posts a PR comment summarizing any findings.
4. Uploads SARIF to GitHub Code Scanning, so findings appear in the Security tab and as inline annotations on the diff.
5. Uploads the full report as a workflow artifact.
6. Fails the check if any findings meet or exceed the severity threshold (default: high).

Permissions Explained

The workflow requires three permissions:

If you disable SARIF upload or PR comments via inputs, you can remove the corresponding permission.

Next Steps

• See Inputs for the full list of configuration options.
• See Outputs to learn how to use scan results in subsequent workflow steps.
• See Examples for complete workflow files covering common scenarios.
• See Findings Visibility if your repository is public and you want to control what details appear in PR comments.