Live Terminal in GitHub Actions met ttyd

Een falende CI-job debuggen vanuit logoutput alleen kost uren. ASD biedt een ingebouwde workflow die je een live browser terminal geeft binnenin je GitHub Actions runner — opgezet met een commando en interactief getriggerd vanuit je terminal.

Het probleem

Je CI-pipeline faalt. De logs zeggen "module not found" maar hetzelfde commando werkt lokaal. Je pusht weer een commit om debug output toe te voegen. Wacht 5 minuten. Nog steeds onduidelijk. Push opnieuw. Deze cyclus herhaalt zich totdat je opgeeft of geluk hebt.

Met ASD krijg je een live terminal-sessie binnenin de runner. Inspecteer het bestandssysteem, draai commando's interactief, los het probleem op bij de eerste poging.

Vereisten

• ASD CLI geinstalleerd en geauthenticeerd (asd login)
• Een GitHub repository met Actions ingeschakeld en gh CLI geauthenticeerd

Stap 1: Installeer de terminal workflow

asd gh setup

Dit maakt .github/workflows/terminal.yml aan met de ASD terminal workflow voorgeconfigureerd. De workflow gebruikt workflow_dispatch dus draait alleen wanneer jij het triggert.

Commit en push het:

git add .github/workflows/terminal.yml
git commit -m "Add ASD terminal workflow"
git push

Stap 2: Start een terminal-sessie

asd gh terminal

ASD leidt je door de configuratie: project, OS, shell, en credentials.

Zodra alles klaar is zie je de URL:

TUNNEL URL AVAILABLE
https://admin:mypass123@a1b2c3d.cicd.eu1.asd.engineer/

Terminal session is ready!

Stap 3: Open in je browser

Klik op de URL of plak het in je browser. Je hebt nu een volledige shell-sessie binnenin de GitHub Actions runner.

Vanuit deze terminal kun je:

• Het bestandssysteem en omgevingsvariabelen inspecteren
• Build-commando's interactief draaien om fouten te reproduceren
• Tools installeren en fixes testen voor je commit
• Netwerkconnectiviteit en DNS-resolutie controleren

Stap 4: Beheer actieve sessies

# Toon alle actieve terminal-sessies
asd gh active

# Stop een sessie wanneer je klaar bent
asd gh stop

Andere handige commando's

Hoe het werkt

1. Download ASD CLI binaries voor het runner OS
2. Maakt tijdelijke tunnel credentials aan
3. Start ttyd gekoppeld aan je gekozen shell
4. Verbindt een ASD tunnel met basic auth bescherming
5. Toont de tunnel URL met ingebedde credentials

Alles is tijdelijk — credentials verlopen wanneer de workflow eindigt, en de runner wordt automatisch opgeruimd door GitHub.

Beveiligingsoverwegingen

• Tijdelijke credentials: Elke sessie krijgt unieke credentials die verlopen bij het einde van de workflow
• Basic auth: Het tunnel-endpoint is beschermd met het gekozen gebruikersnaam en wachtwoord
• Handmatige trigger: De workflow draait alleen wanneer jij het triggert — nooit bij push of PR
• Timeout: Sessies hebben een configureerbare timeout. GitHub termineert de runner na 6 uur

Samenvatting

In plaats van raden via logoutput, stap je in je CI-runner met een live terminal. Een commando om op te zetten (asd gh setup), een commando om te verbinden (asd gh terminal), een commando om te beheren (asd gh active/asd gh stop).