CI/CD Integration

Run OutRay tunnels in automated pipelines using API tokens and environment variables.

OutRay works well in CI/CD pipelines and other automated environments. Instead of browser-based login, you authenticate with an API token that you store as a secret in your CI provider.

Get an API token

1. Open the Tokens section

   In the OutRay dashboard, navigate to Tokens in the left sidebar.

2. Create a new token

   Click New Token, give it a descriptive name (e.g., github-actions-staging), and confirm. The token value is shown only once — copy it immediately.

3. Store the token as a secret

   Add the token to your CI provider’s secret store. The conventional variable name is OUTRAY_API_KEY, but you can use any name that fits your conventions.

API tokens grant full access to your organization’s OutRay resources. Treat them like passwords: never commit them to source control and rotate them if they are exposed.

Authenticate with a token

Using the environment variable

Set OUTRAY_API_KEY in the environment before running the CLI. OutRay picks it up automatically:

export OUTRAY_API_KEY=outray_...
outray 3000

Using the --key flag

Pass the token directly on the command line:

outray 3000 --key $OUTRAY_API_KEY

Example: GitHub Actions

The following workflow snippet installs OutRay, starts a tunnel in the background, and runs tests against the public URL:

name: Preview

on: [pull_request]

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install OutRay
        run: npm install -g outray

      - name: Start tunnel
        run: outray 3000 --key ${{ secrets.OUTRAY_API_KEY }} --no-logs &
        env:
          OUTRAY_API_KEY: ${{ secrets.OUTRAY_API_KEY }}

      - name: Run tests
        run: npm test

The & at the end of the tunnel command runs it in the background so the workflow step does not block. Add a short sleep if your test suite starts immediately and needs the tunnel to be ready first.

Using --no-logs in CI

By default, OutRay prints a log line for every request. In CI this adds noise to your build output. Suppress it with --no-logs:

outray 3000 --key $OUTRAY_API_KEY --no-logs

Using config.toml in CI

For consistent tunnel configuration across local development and CI, commit an outray/config.toml file to your repository and use the --key flag for individual tunnel commands. For example:

[tunnel.web]
protocol = "http"
local_port = 3000
subdomain = "my-app-preview"

outray start requires stored credentials from outray login. For fully automated CI environments, use individual tunnel commands (outray http, outray tcp, etc.) with the --key flag or OUTRAY_API_KEY environment variable instead.

GitHub Actions

- name: Start tunnel
  run: outray http 3000 --key ${{ secrets.OUTRAY_API_KEY }} --no-logs &

Cleaning up

Tunnels are automatically closed when the OutRay process exits. In most CI environments the process terminates naturally when the job completes, so no explicit cleanup step is needed. If you need to stop the tunnel early, send SIGTERM or SIGINT to the process.