Viaalink CI/CD · GitHub Action

Work inside your CI job, from your browser.

A terminal or VS Code on the runner, and your job's services on a temporary public address. Through your own Viaalink Relay, behind a login, for as long as the job runs.

uses: viaalink/cicd@v2 · Linux, macOS and Windows runners · your own runners too

In short

The runner connects out. You open a link.

During a job, the action publishes a terminal, VS Code or one of your services through your Relay. Nothing is opened on the runner: it connects out to your Relay. The session is behind a login, and your Relay serves it over HTTPS.

  1. Runner your CI job
  2. Relay serves it over HTTPS
  3. Login in front of it
    Browser terminal or VS Code

What you get

Three things during a CI/CD job.

  • A browser terminal on the runner

    The checked-out repository, the toolchain and the environment your pipeline sees. For the job that only fails in CI, or a machine you do not have on your desk.

  • VS Code on the runner

    The same session with an editor: read the files, change them and run the job's commands again, all in a browser tab. After the login, VS Code asks for a password once more: the same one, unless you give it its own.

  • Your services on temporary addresses

    An app or API the job started gets its own HTTPS address while the job runs. Test real Mollie or Adyen test webhooks in CI instead of mocks.

With the Viaalink CLI

Three commands to your first session.

Run them in your repository, on a device that is enrolled on your Relay.

  1. 1

    Install the workflow

    Writes .github/workflows/terminal.yml and stores your Relay key and a terminal password as repository secrets. It asks before it stores them.

    via ci install
  2. 2

    Commit and push it

    The workflow is an ordinary file in your repository. Read it, change it, review it like any other.

    git add .github/workflows/terminal.yml
    git commit -m "ci: add terminal workflow"
    git push
  3. 3

    Open a session

    Pick the operating system and shell, wait for the address and open it. For VS Code instead of a terminal, add --interface codeserver.

    via gh terminal
    via gh terminal --interface codeserver

While it runs

See, reopen and stop your sessions.

A session lives as long as its job. When it ends, its address answers 404.

CommandWhat it does
via gh activeLists the running sessions with their addresses.
via gh terminal --show-loginPrints the address with the login in it. Treat it like a password.
via gh stopEnds a session. Its address then answers 404.
via gh runsShows recent sessions.

Without the CLI

Start it from the Actions tab.

The workflow is an ordinary workflow_dispatch workflow. Open your repository's Actions tab, choose the Terminal workflow and press Run workflow. Pick the operating system, shell and interface (terminal or VS Code) in the form.

The address is on the run's summary. Sign in with the username you chose and the terminal password. It is saved on the machine that ran via ci install: via gh terminal --show-login prints the address with it.

  1. 1 Actions
  2. 2 Terminal
  3. 3 Run workflow
  4. 4 Run summary

In your own workflow

One step, wherever you need it.

Use the action directly to open a session only when the tests failed, or to publish a service for the rest of the job.

A terminal or VS Code

The step holds the job while the session is open. Put it last, or behind a condition such as a failed test step. With interface: codeserver, the optional codeserver-password input gives VS Code a password of its own.

- uses: viaalink/cicd@v2
  with:
    tunnel-key: ${{ secrets.VIA_TUNNEL_KEY }}
    tunnel-key-id: ${{ secrets.VIA_TUNNEL_KEY_ID }}
    tunnel-host: ${{ secrets.VIA_TUNNEL_HOST }}
    tunnel-port: ${{ secrets.VIA_TUNNEL_PORT }}
    tunnel-host-key-fingerprints: ${{ secrets.VIA_TUNNEL_HOST_KEY_FINGERPRINTS }}
    password: ${{ secrets.VIA_TERMINAL_PASSWORD }}
    interface: terminal   # or codeserver for VS Code

Services only, for real webhooks

With interface: none and mode: background the step returns and the address stays up until the job ends. A public service has no login: only the random part of its address protects it, so your handler must verify every webhook itself.

- id: via
  uses: viaalink/cicd@v2
  with:
    tunnel-key: ${{ secrets.VIA_TUNNEL_KEY }}
    tunnel-key-id: ${{ secrets.VIA_TUNNEL_KEY_ID }}
    tunnel-host: ${{ secrets.VIA_TUNNEL_HOST }}
    tunnel-host-key-fingerprints: ${{ secrets.VIA_TUNNEL_HOST_KEY_FINGERPRINTS }}
    interface: none
    mode: background
    expose: |
      3000 webhooks public

- run: npm run test:payments
  env:
    WEBHOOK_URL: ${{ fromJSON(steps.via.outputs.urls).webhooks }}

Where it runs

GitHub's runners, or your own.

  • GitHub-hosted runners

    Linux, macOS and Windows.

  • Self-hosted runners

    The same session on your own machines. The runner needs outbound access to your Relay and to GitHub, nothing inbound.

Good to know

What it protects, and what it does not.

  • Give CI its own key.

    Whoever opens the terminal can read the Relay key on the runner. Enroll a device for CI alone, so you can remove it from your Relay without touching your own devices.

  • Whoever can start the workflow can open a session.

    A session has the repository's secrets in reach. Keep the workflow to people you would give that access.

  • The login is checked, not assumed.

    After publishing, the action asks each address behind the login without credentials and requires a refusal before it continues.

  • Nothing stays behind.

    When the job ends, the session stops and its addresses answer 404.

Read on

The reference and the pieces around it.