DocsGuidesGitHub Actions

GitHub Actions

The repository includes a reusable action that downloads a release, verifies its checksum, starts an ngstone agent, and waits for its public URL. It is designed for preview environments and end-to-end tests that need a real public hostname. The recommended mode issues a unique credential for the workflow run and revokes it during the action post step.

Short-lived credentials#

Give the action a management API URL and bearer token. When subdomain is empty, it generates a run-specific DNS label. The post-job cleanup stops the process and revokes the credential even when a later workflow step fails:

- uses: emilio-kariuki/ngstone@v0.3.2
id: tunnel
with:
target: 3000
admin-server: https://edge.example.com:4041
admin-token: ${{ secrets.NGSTONE_ADMIN_TOKEN }}
ttl: 20m

Command workflow#

A command can run while the tunnel is alive. The action writes NGSTONE_URL, NGSTONE_PID, and NGSTONE_LOG to the job environment, then its post step performs cleanup:

- uses: emilio-kariuki/ngstone@v0.3.2
id: tunnel
with:
target: 3000
admin-server: https://edge.example.com:4041
admin-token: ${{ secrets.NGSTONE_ADMIN_TOKEN }}
ttl: 20m
command: npm run e2e -- --base-url "$NGSTONE_URL"

Inputs and outputs#

target is required. Use admin-server and admin-token for automatic per-run credentials; the legacy token input remains as a compatibility fallback. server, server-name, subdomain,transport, host-header, ttl, version, and wait-timeout customize the tunnel. The public URL is available as steps.tunnel.outputs.url and NGSTONE_URL.

Security#

Keep management credentials secret

Store the management token in GitHub Actions secrets. Pin the action to a release tag or commit, do not include credentials in command or logs, and remember that the preview URL is public while the tunnel is alive. The TTL limits a leaked or abandoned runner. The legacy token input is long-lived and does not receive automatic revocation.