NetBird CLI Connect

A GitHub Action that joins your NetBird network as an ephemeral peer, so a workflow runner can reach private resources (internal services, databases, jump hosts) over an encrypted WireGuard mesh.

Optionally waits for the local NetBird DNS resolver (and specific hostnames resolving to private IPs only) before the next steps run.

Inspired by shaban00/netbird-connect.

Usage

- name: NetBird Connect
  uses: NomisCZ/netbird-cli-action@v1
  with:
    setup-key: ${{ secrets.NETBIRD_SETUP_KEY }}
    management-url: ${{ secrets.NETBIRD_MANAGEMENT_URL }}
    wait-for-dns: true
    dns-hosts: ${{ vars.DOKPLOY_URL }}
    dns-timeout: 90

Minimal (no DNS wait):

- name: NetBird Connect
  uses: NomisCZ/netbird-cli-action@v1
  with:
    setup-key: ${{ secrets.NETBIRD_SETUP_KEY }}

Inputs

Input	Required	Default	Description
setup-key	yes	—	Ephemeral, reusable setup key. Store as a secret.
management-url	no	https://api.netbird.io:443	Self-hosted management URL, or the cloud default.
hostname	no	gh-runner-<repo>	Peer name shown in the dashboard.
version	no	latest	Release for the official installer (NETBIRD_RELEASE, e.g. 0.73.2).
preshared-key	no	''	WireGuard PSK, if your peers require one.
allow-ssh	no	false	Enable NetBird SSH access to the runner.
wait-for-dns	no	false	Wait until the local NetBird DNS resolver is ready. Implied when dns-hosts is set.
dns-hosts	no	''	Comma-separated hostnames or URLs that must resolve to private IPs only (NetBird CGNAT / RFC1918).
dns-timeout	no	60	Max seconds for local DNS + dns-hosts waits.

Wait for DNS

Private resources often have the same hostname on public DNS and on NetBird DNS (split-horizon). Right after netbird up, the local NetBird resolver may still be settling — so a step can resolve the public A record, call the API from outside the mesh, and get e.g. 403 instead of reaching the service over NetBird.

Use dns-hosts when later steps must hit those private endpoints:

with:
  setup-key: ${{ secrets.NETBIRD_SETUP_KEY }}
  wait-for-dns: true
  dns-hosts: internal.example.com, https://db.internal:8443
  dns-timeout: 90

Behavior:

1. Poll /etc/resolv.conf and query the first nameserver until it responds.
2. If dns-hosts is set, keep resolving each host until every answer is a private IPv4 (100.64/10, 10/8, 172.16/12, 192.168/16) — no public A records mixed in. Only then is it safe to call the API over NetBird.

Setting dns-hosts alone implies the local-resolver wait (wait-for-dns is not required).

NetBird side setup

1. Settings → Setup Keys → Create key: Make it reusable and ephemeral, auto-assigned to a dedicated group (e.g. github-actions).
2. Access Control: Add a policy allowing github-actions to reach the target resources.
3. DNS: Put the runner group in the nameserver / DNS zone distribution groups so private names are pushed to the peer.

License

MIT