Troubleshooting
Diagnose common GHAS setup and pipeline issues with practical, repeatable fixes.
Troubleshooting Checklist
- Confirm repository has GHAS features enabled.
- Validate workflow permissions include security-events: write for code scanning.
- Ensure lockfiles/manifests are committed for dependency alerts.
- Review branch protection check names and required status alignment.
- Inspect Actions logs for language/build detection errors.
Common Error 1: CodeQL Action Fails During Build
Root cause: Missing build dependencies or unsupported build command in CI runner.
Fix: Add prerequisite install/build steps before analyze and verify runner image.
Common Error 2: Secret Scanning Alerts Not Appearing
Root cause: Feature disabled, unsupported token pattern, or private context mismatch.
Fix: Enable secret scanning and add custom patterns where needed.
Common Error 3: Dependabot Not Opening PRs
Root cause: Missing .github/dependabot.yml or incorrect ecosystem/directory config.
Fix: Correct configuration and check repository access/policy restrictions.
Common Error 4: Security Checks Pass But Merge Still Allowed with High Alert
Root cause: Branch protection not configured to require security gate checks.
Fix: Add required status checks and restrict bypass permissions.
Hands-on Diagnostics
# check workflow files ls .github/workflows # verify dependabot config cat .github/dependabot.yml # inspect lockfile exists test -f package-lock.json && echo "lockfile present" || echo "missing lockfile"
Debugging Scenarios
- Intermittent scan failures: Pin action versions and reduce runner variability.
- Alerts appear only after merge: Ensure PR trigger includes pull_request events.
- Huge monorepo scan times: Apply path filters and split workflows.
- Security team cannot see alerts: Validate repository and org permission scopes.
Interview Questions
Beginner
GitHub Actions logs and Security tab alert details.
Insufficient permissions prevent uploading security results.
Missing lockfiles or incorrect Dependabot config.
Inspect branch protection rules in repository settings.
Investigate, document rationale, then resolve with proper reason.
Intermediate
Stabilize dependencies, isolate jobs, and collect failure patterns.
Use matrix/path segmentation and scheduled deep scans.
Link alerts to PRs, tests, deployment IDs, and closure notes.
Tune rules and establish standardized suppression criteria.
Temporary risk exception process with manual review controls.
Scenario-based
Compare branch-specific workflow filters and protection settings.
Whitelist trusted bot conditions and enforce signed updates.
Reproduce path, consult secure pattern docs, and escalate for design change.
Proceed with documented acceptance if policy allows; schedule debt window.
Restrict admin bypass and add audit monitoring with alerts.
Summary
Troubleshooting GHAS effectively means debugging policy, pipeline, and configuration together, not in isolation.