Troubleshooting

Common issues and solutions when using Unfold CI.

Installation & Setup

GitHub App Installation Failed

Problem: Error message when installing the GitHub App

Solutions:

Check Permissions
- Verify you have admin access to the repository or organization
- Organization owners must approve GitHub Apps
Organization Restrictions
- Go to Organization Settings → Third-party access
- Ensure GitHub Apps are not blocked
- Check OAuth App policies
Try Different Browser
- Clear browser cache and cookies
- Try incognito/private mode
- Use a different browser
Personal Account First
- Try installing on a personal repository first
- Then add to organization repositories

Repositories Not Showing in Dashboard

Problem: Dashboard shows "No repositories" after installation

Solutions:

Click "Sync Repos" Button
- Top-right of dashboard
- Wait 10-30 seconds for sync
- Refresh the page
Verify Installation
- Go to GitHub Settings → Applications
- Find "Unfold CI" in Installed GitHub Apps
- Click "Configure"
- Ensure repositories are selected
Check Repository Access
- You must have at least read access to repos
- Private repos require the app to be installed
- Organization repos may need additional permissions
Wait for Initial Sync
- First sync can take up to 1 minute
- Check back after a short wait
- Contact support if still not appearing after 5 minutes

Can't Access Dashboard

Problem: Unable to login to app.unfoldci.com

Solutions:

Use GitHub Sign-In
- Click "Sign in with GitHub" (not email/password)
- Must have GitHub App installed first
Check GitHub Authorization
- Go to GitHub Settings → Applications → Authorized OAuth Apps
- Unfold CI should be listed
- Revoke and re-authorize if needed
Browser Issues
- Clear cookies for app.unfoldci.com
- Disable ad blockers
- Try incognito mode
Account Issues
- Ensure GitHub account is active
- Check if you have 2FA enabled (should work, but verify)
- Try logging out of GitHub and back in

Configuration Issues

API Key Not Working

Problem: 401 Unauthorized errors when running workflow

Solutions:

Verify Secret in GitHub
```
Repository → Settings → Secrets and variables → Actions
```
- Check UNFOLD_API_KEY exists
- Name must be exact: UNFOLD_API_KEY (case-sensitive)
Test API Key Manually
```
curl https://api.unfoldci.com/api/repos \
  -H "Authorization: Bearer YOUR_API_KEY"
```
- Should return 200 OK with repo list
- 401 = invalid key, regenerate it
Regenerate Key
- Dashboard → Settings → API Keys
- "Revoke" old key
- "Generate New API Key"
- Update GitHub secret with new key
Check Key Scope
- Ensure key has access to the repository
- Organization-wide keys work for all org repos
- Repository-specific keys only work for that repo

Workflow Not Uploading Results

Problem: Workflow completes but no data appears in dashboard

Solutions:

Check Upload Step Status
- Go to Actions tab → Select workflow run
- Scroll to "Upload to Unfold CI" step
- Should show green checkmark
- If red X, click to view error

Verify Test File Exists Add debug step before upload:

- name: Debug test file
  run: |
    ls -la test-results.json
    cat test-results.json | head -n 20

Check API Response Add -v flag to curl:

- name: Upload with debug
  run: |
    curl -v -X POST https://api.unfoldci.com/api/test-results \
      -H "Authorization: Bearer ${{ secrets.UNFOLD_API_KEY }}" \
      -F "file=@test-results.json" \
      -F "repo=${{ github.repository }}" \
      -F "branch=${{ github.ref_name }}" \
      -F "commit=${{ github.sha }}" \
      -F "framework=jest"

Ensure if: always()

- name: Upload to Unfold CI
  if: always()  # CRITICAL! Runs even if tests fail
  run: curl ...

Check Network Access
- Verify api.unfoldci.com is accessible
- If using self-hosted runners, check firewall rules

Test Results Not Parsing

Problem: Upload succeeds but tests show as "0 processed"

Solutions:

Verify Test Format
- Check test results file is valid JSON/XML
- Run cat test-results.json | jq '.' to validate JSON
- Ensure framework matches actual output format
Check Framework Compatibility Supported formats:
- Jest: JSON output with --json flag
- pytest: JSON with pytest-json-report plugin
- NUnit: JSON logger
- JUnit: XML format

Validate Test File Content

# Should contain test results, not error messages
head -n 50 test-results.json

Use Correct Test Command

# Jest
npm test -- --json --outputFile=test-results.json

# pytest
pytest --json-report --json-report-file=test-results.json

# .NET
dotnet test --logger "json;LogFileName=test-results.json"

Flake Detection Issues

No Flaky Tests Detected

Problem: Obviously flaky tests not being flagged

Solutions:

Check Minimum Runs
- Flake detection requires 3-5 runs minimum
- Push multiple commits or rerun workflow
- View test details to see run count
Verify Failure Pattern
- Test must fail sometimes but not always
- 100% passing = not flaky
- 100% failing = consistently broken
- Flaky = intermittent failures
Check Flake Score Threshold
- Default threshold: 5% failure rate
- Test failing 1 out of 20 runs = 5% flaky
- Lower failure rates may not trigger detection
Wait for Analysis
- Analysis runs after each test submission
- Can take 1-2 minutes for AI to process
- Check back after a few workflow runs

PR Not Created for Flaky Test

Problem: Flaky test detected but no PR generated

Reasons & Solutions:

AI Confidence Too Low
- PR only created if confidence >70%
- Check test details for confidence score
- May need more data or clearer failure pattern
Root Cause Analysis Pending
- AI analysis takes 1-2 minutes
- Refresh dashboard to see latest status
- Check "Recent AI Fixes" section
PR Already Exists
- Only one PR per test at a time
- Check GitHub for existing Unfold CI PRs
- Close old PR if you want a new one
Rate Limiting
- Free tier: 5 PRs per month
- Check your plan limits in dashboard
- Upgrade if needed
Repository Permissions
- Verify app has write access
- Check Installation Settings
- Permissions → Contents & Pull requests = Read & Write

Dashboard Issues

Data Not Updating

Problem: Dashboard shows stale data

Solutions:

Hard Refresh
- Windows/Linux: Ctrl + Shift + R
- Mac: Cmd + Shift + R
- Or click browser refresh button
Click "Sync Repos"
- Force refresh repository list
- Updates monitoring status
Check Last Run Time
- Repository card shows "Last run: X minutes ago"
- If outdated, verify workflows are running
Clear Browser Cache
- Clear cache for app.unfoldci.com
- Log out and log back in

PRs Not Clickable/Missing

Problem: "Recent AI Fixes" shows PRs but links don't work

Solutions:

Check PR Status
- PR may have been closed/merged
- Refresh dashboard to update status
Verify Repository Access
- You need read access to the repository
- Private repo PRs require installation
GitHub Connectivity
- PR link redirects to GitHub
- Ensure you're logged into GitHub
- Check GitHub isn't down (status.github.com)

Performance Issues

Slow Workflow Execution

Problem: Workflow takes longer than expected

Solutions:

Optimize Test Execution
- Run tests in parallel if possible
- Use caching for dependencies
- Skip unnecessary steps
Reduce Test File Size
- Only upload essential test results
- Remove verbose output if possible
- Compress large files
Check Network Speed
- Large test files take longer to upload
- Consider splitting into multiple uploads

API Rate Limiting

Problem: "429 Too Many Requests" error

Solutions:

Check Rate Limits
- Test results: 100/min per repo
- API calls: 60/min per key
- View limits in dashboard
Reduce Upload Frequency
- Don't upload on every commit if running frequently
- Use workflow triggers wisely
Upgrade Plan
- Higher rate limits on paid plans
- Contact support for enterprise needs

GitHub Actions Issues

Workflow Not Triggering

Problem: Pushing code doesn't trigger workflow

Solutions:

Check Workflow File Location
- Must be in .github/workflows/ directory
- File must have .yml or .yaml extension

Verify Trigger Configuration

on:
  push:
    branches: [ main ]  # Check branch name matches
  pull_request:

Check Actions Permissions
- Repository Settings → Actions → General
- Ensure "Allow all actions" is enabled
Manually Trigger
- Actions tab → Select workflow → "Run workflow"

Permission Denied Errors

Problem: Workflow fails with permission errors

Solutions:

Add Workflow Permissions

permissions:
  contents: read
  pull-requests: write  # If needed

Check Repository Settings
- Settings → Actions → General
- Workflow permissions → Read and write
Verify GITHUB_TOKEN
- Should be automatically available
- Don't need to add as secret

Common Error Messages

"Invalid test results format"

Solution: Ensure test output matches expected framework format

"Repository not found"

Solution: Verify repo name format is owner/repo, check installation

"Test run already processed"

Solution: Normal for re-runs, safely ignore if data is in dashboard

"Failed to create PR"

Solution: Check GitHub App permissions and repository access

Getting Help

Before Contacting Support

Please gather:

✅ Dashboard screenshot
✅ Workflow run logs (Actions tab)
✅ API key status (valid/expired)
✅ Test file sample (first 50 lines)
✅ Repository name
✅ Error messages

Support Channels

📖 Documentation
💬 Discord Community - Fastest response!
📧 Email Support
🐛 Bug Reports

Response Times

💬 Discord: Usually < 1 hour during business hours
📧 Email: Within 24 hours
🚨 Critical issues: < 2 hours

FAQ

Q: How long does flake detection take?
A: Typically 3-5 test runs. Detection is immediate once threshold is met.

Q: Can I adjust detection sensitivity?
A: Yes, in Dashboard → Repository Settings → Detection Threshold.

Q: Why was no PR created?
A: AI confidence must be >70%. Check test details for actual score.

Q: Can I manually trigger PR creation?
A: Yes, from test details page, click "Generate Fix Now".

Q: How do I delete old test data?
A: Dashboard → Repository → Settings → "Delete Test History".

Q: What if I disagree with the AI fix?
A: Close the PR with feedback, AI learns from your input.

Q: Can I use Unfold CI with private repos?
A: Yes! All plans support private repositories.

Q: Is my code sent to OpenAI?
A: Only test failure patterns and stack traces, never full codebase.

Still stuck? Join our Discord - we're here to help! 🚀

Installation & Setup​

GitHub App Installation Failed​

Repositories Not Showing in Dashboard​

Can't Access Dashboard​

Configuration Issues​

API Key Not Working​

Workflow Not Uploading Results​

Test Results Not Parsing​

Flake Detection Issues​

No Flaky Tests Detected​

PR Not Created for Flaky Test​

Dashboard Issues​

Data Not Updating​

PRs Not Clickable/Missing​

Performance Issues​

Slow Workflow Execution​

API Rate Limiting​

GitHub Actions Issues​

Workflow Not Triggering​

Permission Denied Errors​

Common Error Messages​

"Invalid test results format"​

"Repository not found"​

"Test run already processed"​

"Failed to create PR"​

Getting Help​

Before Contacting Support​

Support Channels​

Response Times​

FAQ​

Installation & Setup

GitHub App Installation Failed

Repositories Not Showing in Dashboard

Can't Access Dashboard

Configuration Issues

API Key Not Working

Workflow Not Uploading Results

Test Results Not Parsing

Flake Detection Issues

No Flaky Tests Detected

PR Not Created for Flaky Test

Dashboard Issues

Data Not Updating

PRs Not Clickable/Missing

Performance Issues

Slow Workflow Execution

API Rate Limiting

GitHub Actions Issues

Workflow Not Triggering

Permission Denied Errors

Common Error Messages

"Invalid test results format"

"Repository not found"

"Test run already processed"

"Failed to create PR"

Getting Help

Before Contacting Support

Support Channels

Response Times

FAQ