🛠️ Infinito.Nexus CI/CD Debugging Guide

Development
1

This guide describes the standard workflow for debugging CI/CD failures in Infinito.Nexus. Following this process ensures efficient troubleshooting, proper documentation, and optimal usage of GitHub Action runner resources.

:police_car_light: 1. Identify and Export Failing Job Logs

When a deployment job fails:

:backhand_index_pointing_right: Always export the full logs

  • Open the failed job in GitHub Actions
  • Click “View raw logs”
  • Download and save the file as:
job-logs.txt

:light_bulb: This step is mandatory — debugging without raw logs leads to incomplete analysis.

:magnifying_glass_tilted_left: 2. Determine Scope of the Error

:white_check_mark: Case A: Error belongs to your current development (same branch / related app)

If the error:

  • Occurs in an app you are working on
  • Is related to your current branch

:backhand_index_pointing_right: Then:

  1. Place job-logs.txt inside the affected repository
  2. Commit it to the same branch where the error occurred

:robot: 3. Use AI Agent for Debugging

Open your IDE with the repository and ask the AI Agent:

Where does the error from the job-logs.txt come from? Debug the error and implement a solution.

:backhand_index_pointing_right: Expected outcome:

  • Root cause is identified
  • Fix is implemented directly in code
  • Solution is validated locally (if possible)

:floppy_disk: 4. Commit the Fix

After resolving the issue:

  • Remove or keep job-logs.txt depending on usefulness
  • Commit the fix to the same branch

:high_voltage: 5. Optimize CI Usage (Best Practice)

To save GitHub Actions runner resources, avoid triggering full pipelines unnecessarily.

:backhand_index_pointing_right: Instead, run a targeted manual workflow:

:white_check_mark: This ensures:

  • Faster feedback
  • Lower CI cost
  • Reduced system load

:prohibited: 6. Case B: Error is NOT related to your branch

If the error:

  • Comes from an unrelated app
  • Is not caused by your current changes

:backhand_index_pointing_right: Then DO NOT fix it in your branch.

:memo: 7. Create an Issue

Create an issue here:

:backhand_index_pointing_right: https://s.infinito.nexus/issues

Include:

  • Upload job-logs.txt
  • Clear description of the failure

:white_check_mark: Important:

  • :check_mark: Check: “explored during CI/CD run”

:herb: 8. Fixing Unrelated Issues

If you want to fix the unrelated issue:

  1. Follow the official forking process:
    :backhand_index_pointing_right: https://s.infinito.nexus/forking

  2. Create a new branch

  3. Implement the fix there

  4. Open a pull request

:compass: Summary Workflow

CI fails → Export logs → Analyze scope

IF related:
    → Add logs to branch
    → Ask AI agent
    → Fix + commit
    → Run manual workflow (debian + app)

ELSE:
    → Create issue
    → Upload logs
    → Mark as "explored during CI/CD run"
    → Fix via new branch (forking process)

:light_bulb: Key Principles

  • :page_facing_up: Logs are the single source of truth
  • :robot: AI-assisted debugging is mandatory workflow
  • :high_voltage: Use manual workflows to save CI resources
  • :puzzle_piece: Keep fixes scoped and clean
  • :globe_showing_europe_africa: Separate concerns via issues and branches

If you follow this process consistently, CI/CD debugging becomes fast, reproducible, and scalable :rocket: