How to Set Up DevInCi in GitLab CI/CD

When a GitLab pipeline 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 CI 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

DevInCi is published as a GitLab CI/CD Catalog component. It uses its own Docker image (ubuntu:22.04) so it works on any runner with Docker executor.

Prerequisites

• An ASD account (asd.host/workspace)
• An API key with cicd:provision scope
• A GitLab project with CI/CD 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 CI/CD variable

1. Go to your project → Settings → CI/CD → Variables
2. Click Add variable
3. Key: ASD_API_KEY
4. Value: paste your API key
5. Check Mask variable — this redacts the value from job logs
6. Check Protect variable — limits the variable to protected branches

Important: GitLab does not support runtime secret masking like GitHub's ::add-mask::. The "Mask variable" setting in project settings is the only way to prevent your key from appearing in logs.

Step 3: Add DevInCi to your pipeline

Include the DevInCi component in your .gitlab-ci.yml and configure it to run when a job fails:

stages:
  -  test
  -  debug

test:
  stage: test
  script:
    -  npm ci
    -  npm test

include:
  -  component: gitlab.com/accelerated-software-development/devinci/dev-environment@1
    inputs:
      api-key: $ASD_API_KEY
      tunnel-name: debug-$CI_PIPELINE_ID
      stage: debug

dev-environment:
  rules:
    -  when: on_failure

The include block pulls the component from the GitLab CI/CD Catalog. The rules block ensures DevInCi only starts when a previous stage fails.

Step 4: Open the session

When your pipeline fails, DevInCi automatically:

1. Spins up an ubuntu:22.04 container
2. Clones the component scripts via CI_JOB_TOKEN
3. Installs the ASD CLI
4. Provisions tunnel credentials via your API key
5. Starts the web terminal (ttyd)
6. Connects a secure tunnel
7. Writes the session URL to a devinci.env dotenv artifact

The URL is visible in the job log and also set as the environment URL for the job. Click it to open a live terminal in your browser.

VS Code instead of terminal

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

include:
  -  component: gitlab.com/accelerated-software-development/devinci/dev-environment@1
    inputs:
      api-key: $ASD_API_KEY
      interface: codeserver
      tunnel-name: vscode-$CI_PIPELINE_ID

On-demand sessions

Trigger DevInCi manually instead of waiting for a failure. Use a web-triggered pipeline with a manual job:

include:
  -  component: gitlab.com/accelerated-software-development/devinci/dev-environment@1
    inputs:
      api-key: $ASD_API_KEY
      interface: codeserver
      tunnel-name: dev-$CI_PIPELINE_ID

dev-environment:
  rules:
    -  if: $CI_PIPELINE_SOURCE == "web"
      when: manual

Go to your project → Build → Pipelines → Run pipeline. Then click the play button on the DevInCi job.

Using outputs in downstream jobs

DevInCi writes a devinci.env dotenv artifact with the TUNNEL_URL variable. Downstream jobs can read it:

notify:
  stage: .post
  needs: [dev-environment]
  script:
    -  echo "Debug session at $TUNNEL_URL"

Custom stage

By default the component uses the deploy stage. Override with the stage input:

include:
  -  component: gitlab.com/accelerated-software-development/devinci/dev-environment@1
    inputs:
      api-key: $ASD_API_KEY
      tunnel-name: debug-$CI_PIPELINE_ID
      stage: build

Configuration options

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 CI/CD variables

"Tunnel connection failed"

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

Secrets visible in logs

GitLab does not support runtime secret masking. Mark your ASD_API_KEY variable as masked in Settings → CI/CD → Variables.

"git clone" fails in before_script

The component clones scripts using CI_JOB_TOKEN. If the component project is private, ensure your project has access via Settings → CI/CD → Token Access.

Summary

Include the DevInCi component in your .gitlab-ci.yml. When a job fails, click the URL and debug in the exact runner environment. No SSH keys, no manual setup.