Connecting to a private network from GitHub-hosted Actions runners

GitHub Actions is a powerful tool for automating your development workflows, including CI/CD. There’s several options for where those workflows run, but GitHub-hosted runners can seem particularly magical. Your job runs, you get the results, and that’s it. You don’t have to provision and maintain servers.

But sometimes, particularly for CI/CD, your job needs to connect to resources on a private network. Maybe you need to access a signing service to sign your builds, or a package registry to upload your finished build. You could use self-hosted runners to run the workflows on your network, but then you need to provision and maintain those servers. Sometimes that’s no big deal, but as your usage grows, or if your team doesn’t have the resources to focus there, that might not work for you.

If that describes you, you’re in luck! We’ve added documentation on connecting to a private network from GitHub-hosted runners. In there, we describe three different approaches you can take and the tradeoffs with each approach. Check out the documentation for all the details, but briefly the three options are as follows:

1) Use the GitHub Actions OpenID Connect (OIDC) token to authenticate through an API gateway (we open sourced a reference implementation as an example, but do note that it requires customization for your use case and is not ready-to-run as-is). You would run the API gateway on your infrastructure, but as it is stateless, it can scale quite well for high-bandwidth use cases. Here’s what this looks like:

2) You can use WireGuard to create a temporary overlay network between the GitHub Actions runner and your private network. This is great for point-to-point communication, and not too much effort to set up, but it does not support NAT traversal out of the box, which could be a problem if the edge of your private network doesn’t support resources with public IP addresses.

3) You can use a commercial solution for an overlay network, like Tailscale. Based on WireGuard, it has similar advantages and disadvantages, except that as a commercial product, it’s even easier to set up and includes NAT traversal. Please note that it might require a paid plan for higher data volumes.

The more GitHub customers I talk to, the more I realize there isn’t a one-size-fits-all solution. Between these options for connecting GitHub-hosted runners to your private network, and the option to run self-hosted runners, we hope that one of these solutions will meet your needs.

Happy building!

Written by

Zachary Steindler

@steiza