Fix Failing GitHub Actions

When to Use

• A CI run on main or a PR is red
• The release workflow failed
• A security hygiene, repo-guard, or labeler job failed
• You see a failed status check in a pull request
• gh run list shows failed runs

Drift-Specific Context

All workflows in this repo run on Windows runners (windows-latest) with PowerShell. Python is resolved dynamically via $env:PYTHON_BIN (set by a resolver step). CI steps use make check equivalents split into: ruff → mypy → pytest → drift analyze.

Key workflows and their failure modes:

Step 1: Identify the Failing Run

# List recent failed runs
gh run list --repo mick-gsk/drift --status failure --limit 10

# Or watch a specific run
gh run view <run-id> --repo mick-gsk/drift

If you have a URL like https://github.com/mick-gsk/drift/actions/runs/12345678, extract the run ID (12345678) and use it below.

Step 2: Fetch the Failure Logs

# Show only the failing steps
gh run view <run-id> --repo mick-gsk/drift --log-failed

# Or full log for a specific job
gh run view <run-id> --repo mick-gsk/drift --log

Parse the log output: Look for the first ##[error] or FAILED line — that is the root cause. Ignore everything after the first failure unless it looks like a separate independent failure.

Step 3: Classify the Failure

Match the error to one of these categories, then jump to the fix section:

§A — Lint Failure (ruff)

# Reproduce locally
.venv\Scripts\ruff check src/ tests/

# Auto-fix safe issues
.venv\Scripts\ruff check src/ tests/ --fix

If auto-fix is not enough, inspect the flagged file and fix manually. Do not add # noqa without a comment explaining why the rule is suppressed.

§B — Type Error (mypy)

# Reproduce locally
.venv\Scripts\python -m mypy src/drift

Typical fixes:

• Missing return type annotation → add return type
• None not handled → add if x is None: return guard
• Import not found → add to mypy ignore_missing_imports or install the stub package (types-*)
• # type: ignore is acceptable only when the upstream stub is missing and documented in a comment

§C — Test Failure (pytest)

# Reproduce the failing test locally
.venv\Scripts\python -m pytest tests/<failing_test_file>.py::test_name -v --tb=long

Checklist:

• Is the failure a genuine regression introduced by the last commit?
• Is it a flaky test (timing, randomness, git state dependency)?
• Is a fixture broken? Run tests/fixtures/ inspection.
• Did a signal or scoring change invalidate expected values?

For signal/scoring regressions: update the expected values in the fixture file or ground-truth fixture (tests/fixtures/ground_truth.py) if the change is intentional, and document in CHANGELOG.md.

For flaky tests: add @pytest.mark.flaky(reruns=2) only as a last resort; prefer fixing the root cause.

§D — Secret Scan Failure (detect-secrets)

This repo carries intentional test-fixture secrets (non-real values used in tests). Each such literal must have # pragma: allowlist secret on the same line.

# Reproduce locally
pre-commit run --all-files detect-secrets

Fix:

1. Open the flagged file and line
2. If the value is a real credential → remove it immediately, rotate the credential, and treat this as a security incident
3. If the value is a test fixture → add # pragma: allowlist secret on that exact line
4. If it was already annotated but the baseline is stale → update baseline: detect-secrets scan > .secrets.baseline

See SECURITY.md for incident escalation steps.

§E — Workflow Lint Failure (actionlint/zizmor)

# Reproduce locally (requires actionlint in PATH or pre-commit)
pre-commit run --all-files actionlint
pre-commit run --all-files zizmor

Common issues:

• Unquoted expression ${{ env.VAR }} without quotes in shell run step → wrap in "${{ env.VAR }}"
• Using set-output (deprecated) → replace with echo "name=value" >> $GITHUB_OUTPUT
• Missing permissions: block → add least-privilege permissions
• continue-on-error masking real failures → evaluate whether the step should actually fail

§F — Version Format Failure

The version in pyproject.toml must be valid SemVer (MAJOR.MINOR.PATCH). Do not manually edit pyproject.toml version — it is managed by PSR (python-semantic-release) in CI.

If the check fails on a branch:

1. Verify the version is a clean SemVer string (no .dev, no extra suffixes unless intentional)
2. If pyproject.toml was manually edited → revert the version field
3. If PSR left a malformed version → check the release workflow logs for the error

.venv\Scripts\python scripts/check_version.py --check-semver

§G — Model Consistency Failure

.venv\Scripts\python scripts/check_model_consistency.py

This script checks that Pydantic models and CLI/output schemas are in sync. Fix: update the model, schema, or the consistency script to reflect intentional changes. If a field was added to a model, ensure it is present in drift.output.schema.json or drift.schema.json.

§H — Repo Hygiene Failure

.venv\Scripts\python scripts/check_repo_hygiene.py --config .github/repo-guard.blocklist --root-allowlist .github/repo-root-allowlist

Common causes:

• A blocked file path was accidentally committed (e.g., tagesplanung/, temp files)
• A new root-level file was added that is not in the allowlist → add to .github/repo-root-allowlist
• A blocklist pattern now matches a legitimate file → review the blocklist before removing the entry

§I — Docs Build Failure (mkdocs)

.venv\Scripts\python -m mkdocs build --strict 2>&1

Common issues:

• Broken internal link → fix the [text](path) reference
• Missing nav entry in mkdocs.yml → add the page
• Jinja2 template error in overrides/ → check the template syntax
• mkdocs-material version incompatibility → check pyproject.toml constraint

§J — Release Pipeline Failure

Do not run PSR manually unless CI is unavailable and the maintainer requests it. CI release is triggered on push to main via .github/workflows/release.yml.

Diagnostic steps:

gh run view <release-run-id> --repo mick-gsk/drift --log-failed

Common issues:

• No releasable commits since last tag → PSR skips without error; verify with semantic-release version --print
• PyPI token expired or missing → secret PYPI_API_TOKEN must be rotated in repo Settings → Secrets
• Tag conflict → a tag already exists for the computed version; check with git tag -l | sort -V | tail -5
• Merge conflict in PSR's own release commit → rebase and retry the push

Local fallback (only on maintainer request):

python scripts/release_automation.py --full-release

§K — Dependency / Install Failure

# Reproduce locally
pip install -e ".[dev]"

Common issues:

• New dependency added to pyproject.toml but not yet in uv.lock → run uv lock and commit the lockfile
• Transitive dependency yanked on PyPI → pin to last working version + add comment
• No module named 'X' during tests → add X to [project.optional-dependencies.dev]

Step 4: Verify the Fix Locally

Before committing, run the equivalent of the failing CI step locally:

# For most CI failures
make check

# Or targeted:
.venv\Scripts\ruff check src/ tests/           # lint
.venv\Scripts\python -m mypy src/drift         # types
make test-fast                                  # tests (schnell, ohne @pytest.mark.slow)

Step 5: Commit and Report

Use the appropriate conventional commit type:

• fix: resolve <failing-workflow> failure: <root cause summary>

Update CHANGELOG.md under ### Fixed if this was a user-visible or CI-blocking bug.

Do not push autonomously. Present the fix and wait for maintainer approval. See the drift-commit-push skill for the full push gate checklist.

Quick Triage Cheat Sheet

gh run list --status failure --limit 5         → find the run
gh run view <id> --log-failed                  → read the error
                                               → classify (§A–§K)
make check                                     → verify fix locally
git add + git commit -m "fix: ..."            → stage fix