How to Get a Live Terminal in GitHub Actions with ttyd

Debugging a failing CI job from log output alone wastes hours. ASD provides a built-in workflow that gives you a live browser terminal inside your GitHub Actions runner — set up with one command and triggered interactively from your terminal.

The problem

Your CI pipeline fails. The logs say "module not found" but the same command works locally. You push another commit to add debug output. Wait 5 minutes. Still unclear. Push again. This cycle repeats until you give up or get lucky.

With ASD, you get a live terminal session inside the runner. Inspect the file system, run commands interactively, fix the issue on the first attempt.

Prerequisites

• ASD CLI installed and authenticated (asd login)
• A GitHub repository with Actions enabled and gh CLI authenticated (asd gh login if needed)

Step 1: Install the terminal workflow

ASD generates a GitHub Actions workflow template for your repository. Run from your project directory:

asd gh setup

This creates .github/workflows/terminal.yml in your repository with the ASD terminal workflow preconfigured. The workflow uses workflow_dispatch so it only runs when you explicitly trigger it — never on push or PR.

Commit and push it:

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

Step 2: Launch a terminal session

Trigger the workflow interactively from your terminal:

asd gh terminal

ASD walks you through the configuration:

Select project:
  1) my-project [terminal.yml] *
> [1]

Select OS:
  1) ubuntu-latest *
  2) macos-latest
  3) windows-latest
> [1]

Select shell:
  1) bash *
  2) zsh
> [1]

Username: admin
Password: mypass123
Tunnel name (Enter for auto): [auto]

ASD triggers the workflow, creates ephemeral credentials, starts ttyd with your chosen shell, and connects a tunnel. You see the URL as soon as it is ready:

Triggering workflow on user/my-project (branch: main)...

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

Terminal session is ready!

Step 3: Open in your browser

Click the URL or paste it in your browser. You now have a full shell session inside the GitHub Actions runner. The credentials are embedded in the URL so authentication happens automatically.

From this terminal you can:

• Inspect the file system and environment variables
• Run build commands interactively to reproduce failures
• Install tools and test fixes before committing
• Check network connectivity and DNS resolution

Step 4: Manage active sessions

List all active terminal sessions across your repositories:

asd gh active

Output:

Active Terminal Sessions

  Run #123456 - main, 15m
    Repo:    user/my-project
    Branch:  main
    Running: 15 minutes
    URL:     https://admin:mypass123@a1b2c3d.cicd.eu1.asd.engineer/

Stop a session when you are done:

asd gh stop

If you have multiple sessions, ASD lets you pick which one to stop.

Other useful commands

Command	Description
asd gh	Interactive GitHub integration menu
asd gh setup	Install workflow files
asd gh terminal	Start remote terminal session
asd gh list	List available workflows with triggers
asd gh runs	View recent workflow runs
asd gh active	Check active terminal sessions
asd gh stop	Stop a running session
asd gh login	Configure GitHub authentication

How it works under the hood

The workflow that asd gh setup generates does the following:

1. Downloads ASD CLI binaries for the runner OS
2. Creates ephemeral tunnel credentials
3. Starts ttyd bound to your chosen shell
4. Connects an ASD tunnel with basic auth protection
5. Outputs the tunnel URL with embedded credentials

Everything is ephemeral — credentials expire when the workflow ends, and the runner is cleaned up by GitHub automatically.

Security considerations

• Ephemeral credentials: Each session gets unique credentials that expire when the workflow ends.
• Basic auth: The tunnel endpoint is protected with the username and password you chose during setup.
• Manual trigger only: The workflow uses workflow_dispatch, so it only runs when you explicitly trigger it — never on push or PR.
• Timeout: Sessions have a configurable timeout. The runner is terminated by GitHub after 6 hours regardless.

Summary

Instead of guessing through log output, step into your CI runner with a live terminal. One command to set up (asd gh setup), one command to connect (asd gh terminal), one command to manage (asd gh active/asd gh stop). No manual workflow YAML, no tunnel configuration, no credential management.