CLI Last verified:

Using via in CI/CD

Run the Viaalink CLI in a pipeline without prompts. Connect a runner to your Viaalink Relay with an SSH key, publish the app the job started with via expose, read its address as JSON, test it over HTTPS and stop it again, with a GitHub Actions example.

What it is for

In a pipeline, the Viaalink CLI (via) does what it does on your laptop: it publishes a port on the machine it runs on at an address on your Viaalink Relay. The machine is now the CI runner, so the app your job started gets an HTTPS address on your own domain for as long as the job runs. Use it to:

  • run end-to-end tests against a real HTTPS address instead of localhost;
  • let a payment provider or another service call your webhooks while the test runs;
  • give a reviewer a link to the build of a pull request while the job waits.

Everything on this page runs without a prompt. Three limits to know before you start:

  • The address lives as long as the job. via runs on the runner; when the job ends, the connection ends and the address goes away. There is no hosted preview that stays after the job.
  • The runner needs its own key on your Relay. You do not sign in with via login in a pipeline: publishing never needs a viaalink.com account (see Sign in to your Viaalink account).
  • The runner connects out to the Relay’s SSH port (2222 unless the operator changed it). Nothing on the runner has to be reachable from the internet.

Before you start

You need four things from the Relay, stored as secrets or variables in your CI:

WhatWhere it comes fromExample
A private SSH key for the pipelineCreate a key pair just for CI. The Relay operator approves its public half: a .pub file in the Relay’s public keys folder, or People › Users in the Relay’s web interface, which can also generate the pair with Generate & download key. See Approved keys.contents of ci_relay_key
The Relay’s SSH hostThe host name devices connect torelay.example.com
The Relay’s SSH port2222 unless the operator changed it2222
The Relay’s host keyPublished by the Relay at /_relay/discoverySHA256:…

Create the key on your own machine, so the private half never passes through the Relay:

bash

Give ci_relay_key.pub to the operator and store the contents of ci_relay_key as a secret. Then read the Relay’s host key once and store it as a variable:

bash

via refuses to connect to a Relay whose host key it does not know, so this value is required. Read it once from a machine you trust and keep it fixed in your CI settings: that way a runner can never be talked into connecting to a different server.

A separate key per pipeline means you can take its access away on its own, by deleting the key on the Relay, without touching your laptop.

Install on the runner

bash

The installer puts via in ~/.local/bin, together with the helpers it needs to publish. If that folder is not on the runner’s PATH, add it (on GitHub Actions: echo "$HOME/.local/bin" >> "$GITHUB_PATH"). Check with via --version. To run one fixed CLI version, add via update --version <v> after the install (Update the CLI).

Connect the runner to your Relay

On your laptop you add a Relay with an invite link. In a pipeline, add it with the key and the host key from the table above:

bash
  • ci is the name the Relay gets on this runner.
  • --key is the path of the private key file. Write the secret to a file only the job can read (chmod 600).
  • --host-key-fingerprint is the host key from /_relay/discovery. Repeat the option when the Relay lists more than one.
  • --default makes it the Relay via expose uses.
  • --domain <domain> picks one of the Relay’s other domains. Without it, via publishes under the Relay’s main domain, and says so.

The command does not ask anything and prints:

text

Publish the app

Start your app in the background, wait until it answers, then publish its port. The name is optional; in a pipeline, a name you choose makes the next steps easier:

bash

via expose starts the connection in the background and returns. It checks the public address before it reports success, and it exits with status 1 when the connection fails or the address does not answer, so a broken publish fails the step. Whether you get the name you asked for depends on the Relay’s settings (Which name you get); always read the address from via instead of building it yourself:

bash

via expose list --json lists every published service with its name, port, url and state.

The login in front

As on your laptop, a published address has a login in front of it (basic auth) unless you pass --auth=none. Keep it on for anything a stranger should not open: the address is on the internet for as long as the job runs.

There are two ways to know the login in a pipeline:

  • Choose it yourself. Set VIA_BASIC_AUTH_USERNAME and VIA_BASIC_AUTH_PASSWORD (from your CI secrets) before via expose. Reviewers who know the team password can open the address.
  • Read it. Without them, via makes a password. via expose auth --json prints the username and password, for example for your tests:
bash

via expose itself never prints the password, so it does not end up in your job log. Do not echo it yourself.

Stop it

bash

This closes the connection and the address stops answering. Run it in a final step that always runs, also when the tests failed, so the address never depends on how your runner cleans up.

Example: GitHub Actions

A workflow that builds a pull request, publishes it, runs tests against the HTTPS address, writes the address to the job summary, and stops it again. It expects:

  • secret RELAY_SSH_KEY: the private key of the pipeline;
  • secrets PREVIEW_USER and PREVIEW_PASSWORD: the login in front of the address;
  • variables RELAY_HOST, RELAY_PORT and RELAY_HOST_KEY.
yaml

Replace the build and start commands and port 3000 with your app’s. To give a reviewer time to click around, add a step before Stop that waits, such as sleep 900 for fifteen minutes; the address works until the job reaches Stop.

Example: any other CI

The same steps work in any CI that runs a shell script with curl, jq and bash. The values come from environment variables your CI fills from its secrets:

bash

Troubleshooting

  • has no host key fingerprints stored. Connecting unpinned is not allowed. The Relay was added without its host key. Add it again with --host-key-fingerprint.
  • exposed locally only -- the tunnel failed The runner reached nothing, or the Relay refused the key. Check that the operator approved the public half of the pipeline key, and that the runner can reach the Relay’s SSH port.
  • has a tunnel, but its public address does not answer yet The connection is up but the address did not answer the check. Look at the app’s own log first; the address answers only what the app answers.
  • More: Troubleshooting.