Interactive Debugging Capabilities
A Terminal on the Failed Runner
The job pauses right after the failing step, with its workspace, tools and environment intact. Inspect files, re-run the failing command and try a fix where it broke.
Secure by Default
Outbound HTTPS only, authenticated with the job’s GitHub OIDC token. Every secret you pass is masked, protected branches are refused, and only repo writers or the PR author can join.
Generate Fix Diff
Collect every change you made on the runner into one patch. Copy it or download it and run git apply locally. Nothing is committed or pushed for you.
Debug on Re-run or From a PR
Arm a session from the workflow run page, or comment /gitera debug on the pull request. Gitera re-runs the failed jobs and the terminal opens when they reach the step.
Add One Step
No Gitera secret in your repository. The job’s OIDC token is the only credential.
permissions:
contents: read
id-token: write # the runner proves its repo, run and branch to Gitera
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm test
# Pause on failure, or when armed from Gitera or /gitera debug
- uses: gitera-io/gitera-debug-action@v1
if: ${{ !cancelled() && (failure() || github.run_attempt > 1) }}
with:
mode: ${{ job.status == 'failure' && 'failure' || 'armed' }}
secrets: ${{ toJSON(secrets) }}How Debug Sessions Work
From a red job to a tested fix, without another round of push and wait.
A Step Fails and the Runner Pauses
The debug step runs on failure, proves which repo, run and branch it is with OIDC, and connects outbound to Gitera. The job summary links to the session.
Gitera Checks Policy and Access
Sessions on main, master and release branches are refused by the block-interactive-debug policy. Joining needs an active org membership plus repo write access or PR authorship.
Debug in the Browser
Open the terminal from the job summary or the Debug Sessions page. Output is masked as it streams, and the terminal follows your window size.
Export the Fix and Let the Job Finish
Generate Fix Diff, then end the session or let the 15-minute limit run out. The step exits successfully, so the job keeps its original result.
Key Benefits
Stop debugging CI by commit message
Fewer Push-and-Wait Loops
Try a fix on the runner in seconds instead of pushing a commit and waiting for a full run each time
No Tunnels or SSH Keys
Nothing listens for inbound connections, and no third-party tunnel or long-lived credential is involved
Every Action Audited
Joins, refused joins, submitted commands and diff exports are logged, with credentials redacted
Debug a failed GitHub Actions job on the runner itself
Most CI failures are fixed by guessing: change the YAML, push, wait, repeat. Gitera debug sessions pause the failed job and open a terminal on the runner in your browser, so you can inspect files, re-run the failing command and try a fix in the exact environment that broke.
The `gitera-io/gitera-debug-action` step connects outbound over HTTPS and proves which repository, run and branch it is with the job’s GitHub OIDC token. There are no open ports, no third-party tunnels and no Gitera secret in your repository. Every secret you pass is masked in the terminal and in fix diffs, sessions are refused on protected branches by the `block-interactive-debug` policy, and only repo write collaborators or the PR author can join.
When the fix works, Generate Fix Diff collects every change you made on the runner into one patch to apply locally. Start from failure analysis or log search to find the failing step, and use flaky tests detection when the failure does not reproduce.
Debug Sessions FAQ
How do I debug a failed GitHub Actions job interactively?
Add the `gitera-io/gitera-debug-action@v1` step after your other steps with `if: failure()` and give the job `permissions: id-token: write`. When a step fails, the job pauses for up to 15 minutes and the job summary links to a terminal on the runner in Gitera. You can also arm a session for the next re-run from the workflow run page or by commenting `/gitera debug` on the pull request.
Is it safe to open a terminal on a GitHub Actions runner?
The runner only makes outbound HTTPS calls to Gitera and authenticates with the job’s short-lived OIDC token, so nothing listens for inbound connections. Secret values passed to the action are masked, including base64 and URL-encoded forms, the shell never receives the OIDC request credentials, and every join, submitted command and diff export is written to an audit log. Sessions on main, master and release branches are refused by default through security policies.
Who can join a GitHub Actions debug session?
You must sign in to Gitera with GitHub and be an active member of the organization. On top of that you need write access to the repository, or you must be the author of the pull request the run belongs to. Read-only members are refused. Each organization can have five live sessions at a time, and debug sessions need a paid Gitera plan.
Does a debug session change my workflow result or commit anything?
No. The debug step always exits successfully, so the job keeps the result it had, and nothing is committed or pushed from the runner. Generate Fix Diff shows `git diff HEAD` plus new files as a patch you copy or download and apply yourself.
Related Gitera capabilities
Explore all features on the Gitera homepage or read insights on the blog.