How to Set Up DevInCi in GitHub Actions

When a GitHub Actions job fails, the usual workflow is: read logs, guess, push a fix, wait, repeat. DevInCi replaces that loop with a live terminal or VS Code IDE inside the runner itself. You click a URL and debug in the exact environment where the failure happened.

What you get

• Web terminal (ttyd) — full shell in your browser, no SSH keys
• VS Code (code-server) — browser IDE with extensions and debugger
• Secure tunnel URL — HTTPS with embedded credentials, shareable with teammates
• Auto-provisioning — credentials, tunnel server, and URL are all handled automatically

The action is available on the GitHub Marketplace — search for "ASD DevInCi" or go to github.com/marketplace/actions/asd-devinci. Works on Ubuntu, macOS, and Windows runners.

Prerequisites

• An ASD account (asd.host/workspace)
• An API key with cicd:provision scope
• A GitHub repository with Actions enabled

Step 1: Create an API key

1. Go to asd.host/workspace/api-keys
2. Click Create API Key
3. Enable the cicd:provision scope
4. Copy the key — you will not see it again

Step 2: Add the key as a repository secret

1. Go to your repository → Settings → Secrets and variables → Actions
2. Click New repository secret
3. Name: ASD_API_KEY
4. Value: paste your API key

Step 3: Add DevInCi to your workflow

Add the DevInCi step after your test command. It only runs when the previous step fails:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

      - name: DevInCi — Debug on failure
        if: failure()
        uses: asd-engineering/asd-devinci@v1
        with:
          api-key: ${{ secrets.ASD_API_KEY }}

That's it. When the test step fails, DevInCi starts a web terminal and prints a URL in the job logs.

Step 4: Open the session

When your workflow fails, DevInCi automatically:

1. Installs the ASD CLI
2. Provisions tunnel credentials via your API key
3. Starts the web terminal (ttyd)
4. Connects a secure tunnel
5. Prints the session URL in the job logs

Click the URL to open a live terminal in your browser. The credentials are embedded in the URL, so authentication is automatic. Secrets are masked in logs via ::add-mask::.

VS Code instead of terminal

Set the interface input to codeserver for a full VS Code IDE:

- name: DevInCi — VS Code on failure
  if: failure()
  uses: asd-engineering/asd-devinci@v1
  with:
    api-key: ${{ secrets.ASD_API_KEY }}
    interface: codeserver
    tunnel-name: vscode-${{ github.run_id }}

On-demand sessions

Trigger DevInCi manually instead of waiting for a failure. Create a separate workflow with workflow_dispatch:

name: Development Environment

on:
  workflow_dispatch:
    inputs:
      ttl:
        description: 'Session duration (minutes)'
        default: '30'

jobs:
  dev:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install

      - name: Start DevInCi
        uses: asd-engineering/asd-devinci@v1
        with:
          api-key: ${{ secrets.ASD_API_KEY }}
          interface: codeserver
          tunnel-name: dev-${{ github.actor }}
          ttl-minutes: ${{ github.event.inputs.ttl }}

Go to your repository → Actions → select the workflow → Run workflow.

Debug a specific failing job

Use continue-on-error to keep the workflow running after the test fails, then check the outcome:

jobs:
  debug:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run tests
        id: tests
        run: npm test
        continue-on-error: true

      - name: Start DevInCi on failure
        if: steps.tests.outcome == 'failure'
        uses: asd-engineering/asd-devinci@v1
        with:
          api-key: ${{ secrets.ASD_API_KEY }}
          tunnel-name: debug-${{ github.run_id }}

Using action outputs

DevInCi exposes outputs you can use in subsequent steps:

- name: Start DevInCi
  id: devinci
  if: failure()
  uses: asd-engineering/asd-devinci@v1
  with:
    api-key: ${{ secrets.ASD_API_KEY }}

- name: Notify team
  if: failure()
  run: |
    echo "Debug URL: ${{ steps.devinci.outputs.url }}"
    echo "Expires: ${{ steps.devinci.outputs.expires-at }}"

Output	Description
url	Session URL with embedded credentials
url-base	Session URL without credentials
tunnel-user	Tunnel client ID
local-port	Local service port
expires-at	Token expiration (ISO 8601)

Configuration options

Input	Description	Default
api-key	ASD API key with cicd:provision scope	—
interface	ttyd (terminal) or codeserver (VS Code)	ttyd
shell	bash, zsh, or powershell	bash
username	Basic auth username	asd
password	Basic auth password (auto-generated if empty)	—
tunnel-name	Subdomain prefix	Short SHA
ttl-minutes	Session TTL in minutes (0 = no expiry)	0
region	Tunnel server region	Auto

Troubleshooting

"Failed to provision credentials"

1. Verify your API key has the cicd:provision scope
2. Check the key is not expired
3. Confirm ASD_API_KEY is set in repository secrets

"Tunnel connection failed"

1. Verify the runner allows outbound SSH on port 2223
2. Try a different region if available

Summary

Add the asd-engineering/asd-devinci action to any workflow. When a job fails, click the URL and debug in the exact runner environment. No SSH keys, no manual setup.