This page is in English — onze technische documentatie voor ontwikkelaars en beheerders is in het Engels.
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.
viaruns 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 loginin 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 (
2222unless 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:
| What | Where it comes from | Example |
|---|---|---|
| A private SSH key for the pipeline | Create 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 host | The host name devices connect to | relay.example.com |
| The Relay’s SSH port | 2222 unless the operator changed it | 2222 |
| The Relay’s host key | Published by the Relay at /_relay/discovery | SHA256:… |
Create the key on your own machine, so the private half never passes through the Relay:
ssh-keygen -t ed25519 -N "" -C "ci@example.com" -f ci_relay_keyGive 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:
curl -fsS https://relay.example.com/_relay/discovery | jq -r '.ssh.host_key_fingerprints[]'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
curl -fsSL https://raw.githubusercontent.com/viaalink/cli/main/install.sh | bashThe 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:
via relay add ci \
--host relay.example.com \
--port 2222 \
--key "$HOME/.ssh/ci_relay_key" \
--host-key-fingerprint "SHA256:…" \
--defaultciis the name the Relay gets on this runner.--keyis the path of the private key file. Write the secret to a file only the job can read (chmod 600).--host-key-fingerprintis the host key from/_relay/discovery. Repeat the option when the Relay lists more than one.--defaultmakes it the Relayvia exposeuses.--domain <domain>picks one of the Relay’s other domains. Without it,viapublishes under the Relay’s main domain, and says so.
The command does not ask anything and prints:
✅ Added private relay "ci" (relay.example.com:2222), set as default.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:
via expose 3000 pr-42via 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:
URL=$(via expose list --json | jq -r '.exposed[] | select(.name == "pr-42") | .url')
echo "$URL"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_USERNAMEandVIA_BASIC_AUTH_PASSWORD(from your CI secrets) beforevia expose. Reviewers who know the team password can open the address. - Read it. Without them,
viamakes a password.via expose auth --jsonprints theusernameandpassword, for example for your tests:
AUTH=$(via expose auth --json)
curl -fsS -u "$(jq -r .username <<<"$AUTH"):$(jq -r .password <<<"$AUTH")" "$URL"via expose itself never prints the password, so it does not end up in your job log. Do not echo it yourself.
Stop it
via expose stop pr-42This 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_USERandPREVIEW_PASSWORD: the login in front of the address; - variables
RELAY_HOST,RELAY_PORTandRELAY_HOST_KEY.
name: Preview
on:
pull_request:
jobs:
preview:
runs-on: ubuntu-latest
timeout-minutes: 30
env:
PREVIEW_NAME: pr-${{ github.event.pull_request.number }}
VIA_BASIC_AUTH_USERNAME: ${{ secrets.PREVIEW_USER }}
VIA_BASIC_AUTH_PASSWORD: ${{ secrets.PREVIEW_PASSWORD }}
steps:
- uses: actions/checkout@v4
- name: Install via
run: |
curl -fsSL https://raw.githubusercontent.com/viaalink/cli/main/install.sh | bash
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
- name: Connect to the Relay
env:
RELAY_SSH_KEY: ${{ secrets.RELAY_SSH_KEY }}
run: |
install -m 600 /dev/null "$RUNNER_TEMP/relay_key"
printf '%s\n' "$RELAY_SSH_KEY" > "$RUNNER_TEMP/relay_key"
via relay add ci \
--host "${{ vars.RELAY_HOST }}" \
--port "${{ vars.RELAY_PORT }}" \
--key "$RUNNER_TEMP/relay_key" \
--host-key-fingerprint "${{ vars.RELAY_HOST_KEY }}" \
--default
- name: Build and start the app
run: |
npm ci
npm run build
nohup npm start > app.log 2>&1 &
curl -fsS --retry 30 --retry-connrefused --retry-delay 1 -o /dev/null http://127.0.0.1:3000
- name: Publish
run: |
via expose 3000 "$PREVIEW_NAME"
URL=$(via expose list --json | jq -r --arg n "$PREVIEW_NAME" '.exposed[] | select(.name == $n) | .url')
echo "PREVIEW_URL=$URL" >> "$GITHUB_ENV"
echo "Preview while this job runs: $URL" >> "$GITHUB_STEP_SUMMARY"
- name: Test against the address
run: |
curl -fsS -u "$VIA_BASIC_AUTH_USERNAME:$VIA_BASIC_AUTH_PASSWORD" "$PREVIEW_URL" > /dev/null
# or: BASE_URL="$PREVIEW_URL" npm run test:e2e
- name: Stop
if: always()
run: via expose stop "$PREVIEW_NAME" || trueReplace 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:
#!/usr/bin/env bash
set -euo pipefail
curl -fsSL https://raw.githubusercontent.com/viaalink/cli/main/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
KEY_FILE=$(mktemp)
chmod 600 "$KEY_FILE"
printf '%s\n' "$RELAY_SSH_KEY" > "$KEY_FILE"
via relay add ci --host "$RELAY_HOST" --port "$RELAY_PORT" \
--key "$KEY_FILE" --host-key-fingerprint "$RELAY_HOST_KEY" --default
trap 'via expose stop preview || true' EXIT
via expose 3000 preview
URL=$(via expose list --json | jq -r '.exposed[] | select(.name == "preview") | .url')
echo "Preview: $URL"
# run your tests against "$URL" hereTroubleshooting
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 failedThe 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 yetThe 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.