Troubleshooting¶
| Symptom | Cause | Fix |
|---|---|---|
Resource not accessible by integration |
Workflow token lacks write permissions | Add permissions: pull-requests: write, issues: write to the workflow, or enable "Read and write permissions" in Settings → Actions → General. BioTrace degrades gracefully and continues without labels/comments either way. |
| No labels appear on the PR | Missing issues: write permission, or create-labels: "false" |
Verify the permission and the create-labels input; check the Action logs for permission errors. |
| No PR comment appears | Missing pull-requests: write permission, or comment-mode: disabled |
Verify the permission and the comment-mode input. |
fetch-depth error / missing base commit |
Checkout used the default shallow clone | Add fetch-depth: 0 to the actions/checkout step. |
AI status: no-key in the report |
None of the configured ai-provider entries have a resolvable key, or the workflow ran from a fork |
Expected for fork PRs (forks can't access parent secrets). For same-repo PRs, verify ai-key-env's secret (primary) or the conventional BIOTRACE_<PROVIDER>_API_KEY secrets (fallback providers) exist. |
AI status: failed in the report |
Every configured provider had a key but every call failed (invalid JSON, schema mismatch, timeout, etc.) | Non-blocking by default (fail_open: true). Check the Action logs for a per-provider warning, then verify the model identifier(s) and API key validity for each configured provider. |
| AI and labels don't work on a fork PR | Expected — fork PRs can't access secrets and pull_request has a read-only token |
BioTrace automatically skips AI; labels/comments may need maintainer approval to run at all. |
| Branch protection doesn't list the BioTrace check | Required status checks use the workflow job name | Use the job name (e.g. biotrace) from your workflow file, not the Action name. |
Still stuck? Open a GitHub Discussion or an issue on the repository.