Establish automated secure Pritunl VPN connections with Pritunl Client in GitHub Actions, supporting OpenVPN and WireGuard.
Simplify your workflow, strengthen security, and safeguard access to corporate resources and infrastructure. This utility ensures secure connections, protecting your organization's valuable assets and data.
Streamline tasks such as:
[!NOTE] The diagram above is an editable vector image using drawio app.
Check the compatibility of various runners and VPN modes:
Runner | OpenVPN | WireGuard |
---|---|---|
ubuntu-24.04 :warning: beta |
:white_check_mark: Yes | :construction: Unstable |
ubuntu-22.04 |
:white_check_mark: Yes | :white_check_mark: Yes |
ubuntu-20.04 |
:white_check_mark: Yes | :white_check_mark: Yes |
macos-14 arm64 |
:white_check_mark: Yes | :construction: Unstable |
macos-13 |
:white_check_mark: Yes | :white_check_mark: Yes |
macos-12 |
:white_check_mark: Yes | :white_check_mark: Yes |
windows-2022 |
:white_check_mark: Yes | :white_check_mark: Yes |
windows-2019 |
:white_check_mark: Yes | :white_check_mark: Yes |
[!TIP]
- See the workflow file connection-tests-complete.yml for a complete tests matrix example.
- View the comprehensive connection tests matrix on our GitHub Actions page for more details.
We have confirmed compatibility with Pritunl v1.32.3805.95 and later versions through rigorous testing. Our server clusters are deployed across multiple cloud platforms, including AWS, Azure and Linode (Akamai).
Configure the Pritunl Client GitHub Action using YAML's declarative syntax, making it easy to integrate and manage your VPN connections in a clear and concise manner. Define your configuration in a simple and human-readable YAML file, and let the action handle the rest.
Provides input parameters for the Pritunl Client GitHub Action, allowing users to customize the setup process and connection settings.
- name: Pritunl Client GitHub Action
uses: nathanielvarona/pritunl-client-github-action@v1
with:
profile-file: ''
# REQUIRED: Pritunl Profile File (Base64 text format)
# Description: Provide the Base64-encoded Pritunl profile file contents.
profile-pin: ''
# OPTIONAL: Profile Pin (Numerical values, default: no pin)
# Description: Specify a numerical pin for the profile (if required).
profile-server: ''
# OPTIONAL: Profile Server (Single string or comma-separated for multiple names, default: first or only server in the profile)
# Description: Specify the profile server(s) to connect to.
vpn-mode: ''
# OPTIONAL: VPN Connection Mode (choices: 'ovpn' for OpenVPN, or 'wg' for WireGuard, default: 'ovpn')
# Description: Select the VPN connection mode.
client-version: ''
# OPTIONAL: Pritunl Client Version (Numerical dot-separated identifiers, default: latest version from Package Manager)
# Description: Specify the Pritunl client version to use.
start-connection: ''
# OPTIONAL: Start the Connection (Boolean, default: true)
# Description: Set to 'false' to prevent the connection from starting automatically.
ready-profile-timeout: ''
# OPTIONAL: Ready Profile Timeout (Natural Numbers, unit of time in seconds, default: 3)
# Description: Set the timeout for the profile to become ready.
established-connection-timeout: ''
# OPTIONAL: Established Connection Timeout (Natural Numbers, unit of time in seconds, default: 30)
# Description: Set the timeout for the connection to become established.
concealed-outputs: ''
# OPTIONAL: Concealed Outputs (Boolean, default: true)
# Description: Set to 'false' to reveal sensitive output information.
[!IMPORTANT] For the
profile-file
input, ensure you convert thetar
archive file format tobase64
text file format. Refer to the Working with Pritunl Profile File subsection for guidance.
Outputs essential variables from Pritunl Client setup, supporting and extending automation, integration, and audit processes.
client-id
— a unique string identifier generated during the profile setup process.
6p5yiqbkjbktkrz5
client-ids
— a JSON array containing all client IDs and names in the profile, with each entry represented as a key-value pair.
{"id":"client-id","name":"profile-name (server-name)"}
[{"id":"6p5yiqbkjbktkrz5","name":"gha-automator-dev (dev-team)"}]
[{"id":"kp4kx4zbcqpsqkbk","name":"gha-automator-qa2 (dev-team)"},{"id":"rsy6npzw5mwryge2","name":"gha-automator-qa2 (qa-team)"}]
To retrieve the client-id
:
${{ steps.pritunl-connection.outputs.client-id }}
To retrieve the client-ids
:
${{ steps.pritunl-connection.outputs.client-ids }}
[!NOTE] The
pritunl-connection
refers to the Setup Step ID. Make sure to replace it with the actual step ID in your workflow.[!TIP]
- See "Manual Connection Control" for an example of using
client_id
.- See "Specifying Server or Servers in a Multi-Server Profile" for examples of using
client_ids
.- See "Controlling Step Outputs Visibility in GitHub Actions Log" by setting
concealed-outputs
.
Provided that profile-file
is available, we have the flexibility to generate multiple scenarios.
Establish a VPN connection with just a few lines of code! Simply set the required profile-file
input, and let the action handle the rest.
- name: Setup Pritunl Profile and Start VPN Connection
uses: nathanielvarona/pritunl-client-github-action@v1
with:
profile-file: ${{ secrets.PRITUNL_PROFILE_FILE }}
[!TIP] See a working example of this action in our connection-tests-basic.yml. This example demonstrates a basic setup and connection test.
If your VPN connection requires authentication, use the profile-pin
input to provide a PIN or password.
- name: Setup Pritunl Profile and Start VPN Connection
uses: nathanielvarona/pritunl-client-github-action@v1
with:
profile-file: ${{ secrets.PRITUNL_PROFILE_FILE }}
profile-pin: ${{ secrets.PRITUNL_PROFILE_PIN }}
Select one or more servers by specifying their names. You can use:
dev-team
)dev-team, qa-team
)gha-automator-qa1 (dev-team)
)gha-automator-qa1 (dev-team), gha-automator-qa1 (qa-team)
)- name: Setup Pritunl Profile and Start VPN Connection
uses: nathanielvarona/pritunl-client-github-action@v1
with:
profile-file: ${{ secrets.PRITUNL_PROFILE_FILE }}
# Specify a single server using its short name
profile-server: dev-team
# Connect to multiple servers using short names
# profile-server: dev-team, qa-team
# Use a full profile name to specify a single server
# profile-server: gha-automator-qa1 (dev-team)
# Use full profile names to specify multiple servers
# profile-server: gha-automator-qa1 (dev-team), gha-automator-qa1 (qa-team)
[!TIP] See an example of connecting to multiple servers in our connection-tests-multi-server-profile.yml file. This workflow demonstrates how to configure and test connections to multiple servers using a single profile.
Use a specific version of the Pritunl client.
- name: Setup Pritunl Profile and Start VPN Connection
uses: nathanielvarona/pritunl-client-github-action@v1
with:
profile-file: ${{ secrets.PRITUNL_PROFILE_FILE }}
client-version: 1.3.3883.60
Use a specific VPN mode (e.g., WireGuard).
- name: Setup Pritunl Profile and Start VPN Connection
uses: nathanielvarona/pritunl-client-github-action@v1
with:
profile-file: ${{ secrets.PRITUNL_PROFILE_FILE }}
vpn-mode: wg
Demonstrates manual control over the VPN connection, including starting, stopping, and checking the connection status.
# Set up Pritunl profile and store client ID for later use
- name: Setup Pritunl Profile
id: pritunl-connection # A `Setup Step ID` has been added as a reference identifier for the output `client-id`.
uses: nathanielvarona/pritunl-client-github-action@v1
with:
profile-file: ${{ secrets.PRITUNL_PROFILE_FILE }}
start-connection: false # Do not establish a connection in this step.
# Start VPN connection using stored client ID and password (use stored secret if available, otherwise use an empty string)
- name: Start VPN Connection Manually
shell: bash
run: |
pritunl-client start ${{ steps.pritunl-connection.outputs.client-id }} \
--password ${{ secrets.PRITUNL_PROFILE_PIN || '' }}
sleep 10 # Wait for 10 seconds to allow the connection to establish
# Display VPN connection status
- name: Display VPN Connection Status Manually
shell: bash
run: |
pritunl-client list --json | jq 'sort_by(.name) | .[0] | { "Profile Name": .name, "Client Address": .client_address }'
# Insert your CI/CD core logic here
- name: Your CI/CD Core Logic Here
# Stop VPN connection using stored client ID (always run, even on failure)
- name: Stop VPN Connection Manually
if: ${{ always() }}
shell: bash
run: |
pritunl-client stop ${{ steps.pritunl-connection.outputs.client-id }}
[!TIP] See a working example of manual connection control in our connection-tests-manual-control.yml for the readme example manual test.
By default, step outputs are hidden in the GitHub Actions log to keep it clean and clutter-free. To reveal step outputs, set concealed-outputs
to false
.
- name: Setup Pritunl Profile and Start VPN Connection
uses: nathanielvarona/pritunl-client-github-action@v1
with:
profile-file: ${{ secrets.PRITUNL_PROFILE_FILE }}
concealed-outputs: false # Set to false to reveal step outputs in the GitHub Actions log
The Pritunl Client CLI requires a specific file format, and GitHub has limitations on uploading binary files. To store the Pritunl Profile in GitHub Secrets, we need to convert the tar
archive file to a base64
text file format.
Download the Profile File
from the User Profile Page
or obtain it from your Infrastructure Team
. If you receive a tar
file, proceed to Step 2
.
curl -sSL https://vpn.domain.tld/key/a1b2c3d4e5.tar -o ./pritunl.profile.tar
Convert the Pritunl Profile File from tar
archive file format to base64
text file format.
base64 --wrap 0 ./pritunl.profile.tar > ./pritunl.profile.base64
pbcopy
):
cat ./pritunl.profile.base64 | pbcopy
xclip
:
cat ./pritunl.profile.base64 | xclip -selection clipboard
xsel
:
cat ./pritunl.profile.base64 | xsel --clipboard --input
PowerShell
):
Get-Content .\pritunl.profile.base64 | Set-Clipboard
./pritunl.profile.base64
in a code editor (e.g., code
or vim
) and select all the text (or use the keyboard shortcut Ctrl+A
or Cmd+A
)."Copy"
(or use the keyboard shortcut Ctrl+C
or Cmd+C
).Create a GitHub Action Secret (e.g., PRITUNL_PROFILE_FILE
) and paste the entire base64
text data as the secret value.
Supports GitHub Actions runners with Arm64 architecture, enabling users to run workflows on Arm64-based systems.
[!TIP] See an example of Arm64 support in our connection-tests-basic.yml file.
[!WARNING] arm64 — While most runners are free to use in public repositories, certain Arm64 runners may incur usage charges to your account.
For details on runner billing, please refer to the "About billing for GitHub Actions" documentation.
Affected Runners: Ubuntu (Linux) Runners using the Apt Repository
for installation.
Problems:
Solutions:
Specify the desired Pritunl Client version using the client-version
input in your GitHub Action. This will download the client directly from the official Pritunl Client GitHub Releases page, ensuring you get the exact version you need.
NOTE: When specifying the
client-version
input, please use the version number without the 'v' prefix. For example, use 1.3.3883.60 instead of v1.3.3883.60.
Example:
- uses: nathanielvarona/pritunl-client-github-action@v1
...
with:
...
client-version: 1.3.3883.60
Thank you for your interest in contributing to our project! We appreciate your help in making our project better.
Modify the main files:
pritunl-client.sh
.Test your changes thoroughly:
Ensure your contributions are reliable by testing your fork using the same GitHub Actions workflows we use for our project. Please update or add new test workflows in the .github/workflows/connection-tests-*.yml
files as needed to cover your changes.
Once you've modified and tested your fork, you can use it in your own projects. Here's an example usage:
- name: Pritunl Client GitHub Action (Development Fork)
uses: <YOUR GITHUB USERNAME>/pritunl-client-github-action@<YOUR FEATURE BRANCH>
with:
profile-file: ${{ secrets.PRITUNL_PROFILE_FILE }}
...
<YOUR FEATURE INPUTS>
...
When contributing to our project, please make sure to document your features or changes in the following ways:
Thank you again for your contribution! If you have any questions or concerns, feel free to reach out to us.