Quick Start¶
1. Create the configuration file¶
Create .github/biotrace.yml in your repository:
version: 1
files:
metadata:
- path: data/sample_metadata.csv
required_columns:
- sample_id
- condition
unique:
- sample_id
allowed_values:
condition:
- control
- treatment
2. Add the workflow¶
Create .github/workflows/biotrace.yml:
name: BioTrace
on:
pull_request:
types: [opened, synchronize, reopened, ready_for_review]
permissions:
contents: read
pull-requests: write
issues: write
checks: write
jobs:
biotrace:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
- id: biotrace
uses: rotsl/biotrace@v1
with:
config: .github/biotrace.yml
github-token: ${{ github.token }}
fail-on: error
ai-enabled: "false"
- if: always()
uses: actions/upload-artifact@v7
with:
name: biotrace-report
path: ${{ steps.biotrace.outputs.report-path }}
3. Open a pull request¶
BioTrace runs automatically and posts a report comment on your PR.
No-AI example¶
The simplest configuration. No API keys, no AI, fully deterministic:
name: BioTrace
on: pull_request
permissions:
contents: read
pull-requests: write
issues: write
jobs:
biotrace:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
- uses: rotsl/biotrace@v1
with:
config: .github/biotrace.yml
ai-enabled: "false"
Optional AI example¶
Bring-your-own-key. AI observations are advisory only and never override
deterministic checks. ai-model is optional — leave it blank and BioTrace
picks a current model automatically:
name: BioTrace
on:
pull_request:
types: [opened, synchronize, reopened, ready_for_review]
permissions:
contents: read
pull-requests: write
issues: write
checks: write
jobs:
biotrace:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
- id: biotrace
uses: rotsl/biotrace@v1
with:
config: .github/biotrace.yml
github-token: ${{ github.token }}
ai-enabled: auto
ai-provider: openai-compatible
env:
BIOTRACE_AI_API_KEY: ${{ secrets.BIOTRACE_AI_API_KEY }}
- if: always()
uses: actions/upload-artifact@v7
with:
name: biotrace-report
path: ${{ steps.biotrace.outputs.report-path }}
ai-provider also accepts a comma-separated priority list (Claude and Gemini are supported too)
so BioTrace falls through to a backup provider if the first one fails — see
AI configuration for multi-provider setup.
What a report looks like¶
## BioTrace report
**Status:** ⚠️ warning
**Reproducibility:** 82/100
**Files checked:** 4 | **Claims:** 2 | **Figures:** 3
### Blocking findings
(None)
### Warnings
- ⚠️ **Possible stale output** `results/de_results.csv`: input changed but output did not
- ⚠️ **Figure may be stale** `figures/figure_2.png`: upstream dependency changed
### Verified checks
- ✅ **Metadata valid** `data/sample_metadata.csv`: 6 rows, 3 columns
- ✅ **Claim verified** "il6-treatment-effect" passed
- ✅ **FASTA valid** `references/genome.fa`: 25 records
### AI-assisted observations
> **Advisory only** — AI does not override deterministic checks.
- **Possible methods drift** (conf: 88%, verify): The filtering threshold appears
to change from 10 to 20 detected cells.
- Files: `analysis/filtering.R`, `manuscript/methods.md`
<details>
<summary>Reproducibility breakdown</summary>
| Component | Weight | Result |
|---|---|---|
| environment_definition | 15 | ✅ |
| dependency_lock | 15 | ✅ |
| dependency_constraints | 10 | ✅ |
| random_seed | 10 | ❌ |
| documented_entrypoint | 15 | ✅ |
| output_manifest | 15 | ✅ |
| figure_provenance | 10 | ✅ |
| data_checksums | 5 | ✅ |
| session_information | 5 | — |
</details>
Next: see the full Configuration Reference for every available field.