GitHub Action
Pritunl Client GitHub Action
Automate secure Pritunl VPN in GitHub Actions! Establish secure connections with Pritunl Client modes 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:
- Build and distribute cross-platform and multi-arch support for powerful desktop, mobile, IoT, and firmware applications across teams.
- Ensure secure access to private resources, including file servers (such as
SharePoint
andNFS
) and corporate infrastructure, with Pritunl VPN Enterprise Servers. - Automated testing of internal and private API endpoints.
- Ensure data safety with scheduled backups.
Check the compatibility of various runners and VPN modes:
Runner | OpenVPN | WireGuard |
---|---|---|
ubuntu-22.04 |
✅ yes | ✅ yes |
ubuntu-20.04 |
✅ yes | ✅ yes |
macos-13 |
✅ yes | ✅ yes |
macos-13-xlarge arm64* |
✅ yes | ✅ yes |
macos-12 |
✅ yes | ✅ yes |
windows-2022 |
✅ yes | ✅ yes |
windows-2019 |
✅ yes | ✅ yes |
Tip
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 a declarative syntax, making it easy to integrate and manage your VPN connections.
- 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', 'openvpn', 'OpenVPN', 'wg', 'wireguard', '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 the tar
archive file format to base64
text file format. Refer to the Working with Pritunl Profile File subsection for guidance.
-
client-id
— a string representing the primary client ID, which is a single identifier generated during the profile setup process.- Example:
client_id="6p5yiqbkjbktkrz5"
- Example:
-
client-ids
— a JSON array containing all client IDs and names in the profile, with each entry represented as a key-value pair (e.g.,{"id":"client_id","name":"profile_name"}
).- Example (single entry):
client-ids="[{"id":"6p5yiqbkjbktkrz5","name":"gha-automator-dev (dev-team)"}]"
- Example (multiple entries):
client-ids="[{"id":"kp4kx4zbcqpsqkbk","name":"gha-automator-qa2 (dev-team)"},{"id":"rsy6npzw5mwryge2","name":"gha-automator-qa2 (qa-team)"}]"
- Example (single entry):
The step output retrieving examples are:
${{ steps.pritunl-connection.outputs.client-id }}
, for the primary client ID.${{ steps.pritunl-connection.outputs.client-ids }}
, for the list of client IDs.
Note: pritunl-connection
refers to the Setup Step ID.
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 Output Visibility in GitHub Actions Log" by setting
concealed-outputs
.
Important
See also the workflow file connection-tests-complete.yml for a complete tests matrix example.
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:
- Short name: A concise name (e.g.,
dev-team
) - Short name with multiple servers: Separate multiple short names with commas (e.g.,
dev-team, qa-team
) - Full profile name: A complete name with the profile and server (e.g.,
gha-automator-qa1 (dev-team)
) - Full profile name with multiple servers: Separate multiple full profile names with commas (e.g.,
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 }}
profile-server: dev-team # Specify a single server using its short name
# profile-server: dev-team, qa-team # Connect to multiple servers using short names
# profile-server: gha-automator-qa1 (dev-team) # Use a full profile name to specify a single server
# profile-server: gha-automator-qa1 (dev-team), gha-automator-qa1 (qa-team) # Use full profile names to specify multiple servers
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.3814.40
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.
- 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.
- name: Starting a VPN Connection Manually
shell: bash
run: |
# Starting a VPN Connection Manually
pritunl-client start ${{ steps.pritunl-connection.outputs.client-id }} \
--password ${{ secrets.PRITUNL_PROFILE_PIN || '' }}
- name: Show VPN Connection Status Manually
shell: bash
run: |
# Show VPN Connection Status Manually
sleep 10
pritunl-client list -j | jq 'sort_by(.name) | .[0] | { "Profile Name": .name, "Client Address": .client_address }'
- name: Your CI/CD Core Logic
shell: bash
run: |
# Your CI/CD Core Logic
##
# Below is our simple example for VPN connectivity test.
##
# Install IP Calculator
if [ "$RUNNER_OS" == "Linux" ]; then
sudo apt-get install -qq -o=Dpkg::Use-Pty=0 -y ipcalc
elif [ "$RUNNER_OS" == "macOS" ]; then
brew install -q ipcalc
elif [ "$RUNNER_OS" == "Windows" ]; then
# Retry up to 3 times in case of failure
for attempt in $(seq 3); do
if curl -sSL "https://raw.githubusercontent.com/kjokjo/ipcalc/0.51/ipcalc" \
-o $HOME/bin/ipcalc && chmod +x $HOME/bin/ipcalc; then
break
else
echo "Attempt $attempt failed. Retrying..." && sleep 1
# If all retries fail, exit with an error
if [ $attempt -eq 3 ]; then
echo "Failed to install ipcalc after 3 attempts." && exit 1
fi
fi
done
fi
# Validate the IP Calculator Installation
echo "ipcalc version $(ipcalc --version)"
# VPN Gateway Reachability Test
ping_count_number=5
profile_ip=$(pritunl-client list -j | jq -r 'sort_by(.name) | .[0].client_address')
vpn_gateway="$(ipcalc $profile_ip | awk 'NR==6{print $2}')"
ping_flags="$([[ "$RUNNER_OS" == "Windows" ]] && echo "-n $ping_count_number" || echo "-c $ping_count_number")"
# Ping VPN Gateway
ping $vpn_gateway $ping_flags
- name: Stop VPN Connection Manually
if: ${{ always() }}
shell: bash
run: |
# Stop VPN Connection Manually
pritunl-client stop ${{ steps.pritunl-connection.outputs.client-id }}
Tip
See a working example of manual connection control in our connection-tests-manual-readme-example.yml for the readme example manual test.
By default, outputs are hidden in the GitHub Actions log to keep it clean and clutter-free. To reveal 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 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
Copy the contents of the base64 text file format.
# For macOS:
# Using `pbcopy`
cat ./pritunl.profile.base64 | pbcopy
# For Linux:
# Using `xclip`
cat ./pritunl.profile.base64 | xclip -selection clipboard
# Using `xsel`
cat ./pritunl.profile.base64 | xsel --clipboard --input
Alternatively, open the file in a code editor and copy the contents
code ./pritunl.profile.base64 # or,
vim ./pritunl.profile.base64
Then, copy the entire base64
text data.
Create a GitHub Action Secret (e.g., PRITUNL_PROFILE_FILE
) and paste the entire base64
text data as the secret value.
Pro Tip: One-liner Shorthand Script
Use this handy one-liner script to simplify the first three steps:
# For macOS
encode_profile_and_copy() { curl -sSL $1 | base64 -w 0 | pbcopy }
# For Linux
encode_profile_and_copy() { curl -sSL $1 | base64 -w 0 | xclip -selection clipboard } # Or,
encode_profile_and_copy() { curl -sSL $1 | base64 -w 0 | xsel --clipboard --input }
# Usage
encode_profile_and_copy https://vpn.domain.tld/key/a1b2c3d4e5.tar
This script combines the steps of downloading the profile, converting to base64, and copying to the clipboard into a single command. Just replace the URL with your profile link!
Tip
See an example of Arm64 support in our connection-tests-arm64.yml file.
Warning
arm64* — Arm64 runners incur usage charges, even in public repositories. Please note that these charges apply to your account.
For a detailed understanding of your billing, we recommend reviewing the "About billing for GitHub Actions" page.
Thank you for your interest in contributing to our project! We appreciate your help in making our project better.
- Fork our repository to your own GitHub account.
- Make changes, additions, or fixes on your forked repository.
- Send a pull request to our original repository.
- Rebase your branch on top of the latest main branch before submitting a pull request.
- Squash your commits into a single, meaningful commit.
If you have any suggestions for improvement, please don't hesitate to fork the project. Here's an example of how to use your fork:
- Modify the main files:
action.yml
(GitHub Actions Metadata File)pritunl-client.sh
(Pritunl Client Entrypoint Script File)
Example of using your fork:
- 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>
...
We use GitHub Actions to test our project. You can find example test workflows in the .github/workflows/connection-tests-*.yml
files. Please make sure to update these tests or add new ones as necessary to cover your changes.
When contributing to our project, please make sure to document your features or changes in the following ways:
- Update the README.md file to include information about your feature or change.
- Add comments to your code to explain what it does and how it works.
- If necessary, create a new documentation file or update an existing one to provide more detailed information about your feature or change.
- Be respectful and considerate of others in our community.
- Follow the GitHub Community Guidelines and Anti-Harassment Policy.
- Keep your contributions aligned with our project's goals and scope.
- Our maintainers will review your pull request and provide feedback.
- We may request changes or improvements before merging your pull request.
- Once approved, your contribution will be merged and credited to you.
Thank you again for your contribution! If you have any questions or concerns, feel free to reach out to us.