DevInCi instellen in GitLab CI/CD

Als een GitLab pipeline faalt is de gebruikelijke workflow: logs lezen, gokken, fix pushen, wachten, herhalen. DevInCi vervangt die cyclus met een live terminal of VS Code IDE in de CI runner zelf. Je klikt op een URL en debugt in exact de omgeving waar de failure optrad.

Wat je krijgt

• Web terminal (ttyd) — volledige shell in je browser, geen SSH keys
• VS Code (code-server) — browser IDE met extensies en debugger
• Beveiligde tunnel URL — HTTPS met ingebedde credentials, deelbaar met teamleden
• Auto-provisioning — credentials, tunnel server en URL worden automatisch afgehandeld

DevInCi is gepubliceerd als GitLab CI/CD Catalog component. Het gebruikt een eigen Docker image (ubuntu:22.04) en werkt op elke runner met Docker executor.

Vereisten

• Een ASD account (asd.host/workspace)
• Een API key met cicd:provision scope
• Een GitLab project met CI/CD ingeschakeld

Stap 1: Maak een API key

1. Ga naar asd.host/workspace/api-keys
2. Klik op Create API Key
3. Activeer de cicd:provision scope
4. Kopieer de key — je ziet deze niet meer

Stap 2: Voeg de key toe als CI/CD variabele

1. Ga naar je project → Settings → CI/CD → Variables
2. Klik op Add variable
3. Key: ASD_API_KEY
4. Value: plak je API key
5. Vink Mask variable aan — dit maskeert de waarde in job logs
6. Vink Protect variable aan — beperkt de variabele tot beschermde branches

Belangrijk: GitLab ondersteunt geen runtime secret masking zoals GitHub's ::add-mask::. De "Mask variable" instelling in project settings is de enige manier om je key uit de logs te houden.

Stap 3: Voeg DevInCi toe aan je pipeline

Include de DevInCi component in je .gitlab-ci.yml en configureer deze om te draaien bij een failure:

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

Het include blok haalt de component op uit de GitLab CI/CD Catalog. Het rules blok zorgt dat DevInCi alleen start wanneer een eerdere stage faalt.

Stap 4: Open de sessie

Wanneer je pipeline faalt, doet DevInCi automatisch:

1. Een ubuntu:22.04 container opstarten
2. Component scripts clonen via CI_JOB_TOKEN
3. ASD CLI installeren
4. Tunnel credentials aanmaken via je API key
5. Web terminal (ttyd) starten
6. Beveiligde tunnel verbinden
7. Sessie URL schrijven naar een devinci.env dotenv artifact

De URL is zichtbaar in de job log en wordt ook ingesteld als environment URL voor de job. Klik erop om een live terminal te openen in je browser.

VS Code in plaats van terminal

Stel de interface input in op codeserver voor een volledige 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 sessies

Trigger DevInCi handmatig in plaats van te wachten op een failure. Gebruik een web-getriggerde pipeline met een handmatige 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

Ga naar je project → Build → Pipelines → Run pipeline. Klik dan op de play knop bij de DevInCi job.

Outputs gebruiken in downstream jobs

DevInCi schrijft een devinci.env dotenv artifact met de TUNNEL_URL variabele. Downstream jobs kunnen deze lezen:

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

Custom stage

Standaard gebruikt de component de deploy stage. Overschrijf met de 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

Configuratie opties

Troubleshooting

"Failed to provision credentials"

1. Controleer of je API key de cicd:provision scope heeft
2. Check of de key niet verlopen is
3. Bevestig dat ASD_API_KEY is ingesteld in CI/CD variabelen

"Tunnel connection failed"

1. Controleer of de runner uitgaande SSH op poort 2223 toestaat
2. Probeer een andere regio als beschikbaar

Secrets zichtbaar in logs

GitLab ondersteunt geen runtime secret masking. Markeer je ASD_API_KEY variabele als masked in Settings → CI/CD → Variables.

"git clone" faalt in before_script

De component clonet scripts via CI_JOB_TOKEN. Als het component project privé is, zorg dat je project toegang heeft via Settings → CI/CD → Token Access.

Samenvatting

Include de DevInCi component in je .gitlab-ci.yml. Als een job faalt, klik op de URL en debug in exact de runner omgeving. Geen SSH keys, geen handmatige setup.