Configuring and connecting to your VPN

Do you require a VPN connection for your build, to be able to connect to your server, either to git clone your repository or to access a private API? If yes, then this tutorial is for you!

Technical information

To connect to a VPN, you need to:

  1. Make sure your local network address space does not clash with the Bitrise virtual machines’ internal address space as this can cause an error with the VPN.
  2. Install and configure the required VPN components.
  3. Connect to the VPN.

You can configure and connect a VPN anywhere in your Workflow - BEFORE you would use the VPN connection, of course. For example, if you require a VPN connection to access your repository, you have to connect before the Git Clone Step.

SSH sessions

When you choose your VPN tool and do the setup/configuration, you have to be careful NOT TO RESTART OR ABORT existing SSH sessions! The workers will abort the build if the SSH connection between the build’s Control/Master machine and the build virtual machine terminates!

Accessing a repository via VPN

If the repository of your application can be only accessed via VPN, you have two things to keep in mind above all:

Let’s go through this workaround!

  1. Create an empty repository that is accessible without a VPN connection.
  2. Add a new app, using this repository as the source. Make sure it is a private app! There is no need to register a webhook.
  3. When done, go to the Settings tab of your app.

    Configuring and connecting to your VPN

  4. In the REPOSITORY URL field, replace the URL with the URL of the actual repository you want to use.
  5. Click Save changes.
  6. Go to the Workflows tab to open the Workflow Editor.
  7. Place the Step or Steps establishing the VPN connection before any Steps that have to access your repository in your Workflow.

And you’re done. For the different methods of establishing a VPN connection, take a look at our Example configurations.

Example configurations

Using the Connect to OpenVPN Server Step

To use the Connect to OpenVPN Server Step, you need to build an OpenVPN server in advance. Read more about how to set up an OpenVPN server.

Once the server is ready, encode the following in Base64:

You can base64 encode files with the following command:

$ base64 <filepath>

Now you are ready to set up the VPN on Bitrise, in the Workflow Editor of your app:

  1. Register the encoded certificates and the key as Secrets on

    We recommend using the following keys as they are the default inputs for the VPN Step:

    • CA certificate: $VPN_CA_CRT_BASE64
    • Client certificate: $VPN_CLIENT_CRT_BASE64
    • Private key: VPN_CLIENT_KEY_BASE64
  2. Add the Connect to OpenVPN Server Step to your Workflow.

    Don’t forget to add the Step before any Steps that might require VPN connection.

  3. Add the previously created Secrets to their respective inputs:
    • Base64 encoded CA Certificate
    • Base64 encoded Client Certificate
    • Base64 encoded Client Private Key

    If you created the Secrets with the recommended keys, you do not have to change the inputs.

  4. Fill in the other required inputs.
    • Host: the Open VPN Server IP or hostname
    • Port: OpenVPN Server Port number
    • Protocol: OpenVPN Server Protocol

Strongswan VPN setup

This is an example script which you can either save into your repository and run it from there, or just copy paste its content into a Script Step in your bitrise configuration (bitrise.yml / Workflow).

#!/usr/bin/env bash
set -e

echo "WAN IP"
# This prints the servers Internet IP adress to the log, useful for debugging

case "$OSTYPE" in
    echo "Configuring for Linux"

    # Variables
    etc_sudo='sudo' # Sudo is needed for Linux Strongswan configuration

    # Install strongswan
    echo "Installing Strongswan..."
    sudo apt-get install -y strongswan

    echo "Configuring for Mac OS"

    # Variables
    etc_sudo='' # Sudo is NOT needed for Mac OS Strongswan configuration

    # Install Strongswan using homebrew
    echo "Installing OpenSSL..."
    # Manually install OpenSSL first to save time, since installing Strongswan directly compiles OpenSSL from source instead
    brew install openssl
    echo "Installing Strongswan..."
    brew install strongswan

    echo "Unknown operative system: $OSTYPE, exiting"
    exit 1

# Method for rendering a template string file (when run, returns the input string with $VARIABLES replaced from env)
render_template() {
  eval "echo \"$(cat $1)\""

# Create a temporary directory to hold files
mkdir $temp_dir

# IPsec config file, see examples at and
echo "Downloading ipsec.conf..."
wget -O $temp_dir/ipsec.conf.template
# IPsec credentials file, see documentation at
echo "Downloading ipsec.secrets..."
wget -O $temp_dir/ipsec.secrets.template
# In some cases you might need to download the certificate, or certificate chain, of your other VPN endpoint
echo "Downloading server.crt..."
wget -O $temp_dir/server.crt

echo "Rendering config templates"
render_template $temp_dir/ipsec.conf.template > $temp_dir/ipsec.conf
render_template $temp_dir/ipsec.secrets.template > $temp_dir/ipsec.secrets

echo "Installing configuration"
$etc_sudo cp $temp_dir/ipsec.conf $etc_dir/ipsec.conf
$etc_sudo cp $temp_dir/ipsec.secrets $etc_dir/ipsec.secrets
$etc_sudo cp $temp_dir/server.crt $etc_dir/ipsec.d/ocspcerts/server.crt

# Start the ipsec service
echo "Starting ipsec"
sudo ipsec start

# We're sleeping between commands, mostly since Mac OS seems to have some problems otherwise
sleep 1

# Output some helpful status to the log
echo "Status ipsec"
sudo ipsec statusall

sleep 1

# Switch out myconnection with the name of your connection in ipsec.conf
echo "Initiating VPN connection"
sudo ipsec up myconnection

sleep 1

case "$OSTYPE" in
    # In Mac OS El Capitan, the `sudo ipsec up` command consistently fails the first time, but succeeds after a restart of the ipsec service
    echo "Restarting ipsec"
    sudo ipsec restart

    sleep 1

    echo "Initiating VPN connection"
    sudo ipsec up myconnection

    sleep 1

    # This step might apply if you are routing all traffic trough the IPsec connection (that is, if your remote IP range is
    # Mac OS El Capitan seems to have problems getting the DNS configuration from the Strongswan interface. Also IPv6 sometimes causes issues. So we're manually turning off IPv6 and forcing a new DNS configuration.
    echo "Disabling IPv6 and forcing DNS settings"
    # Fetch main interface
    main_interface=$(networksetup -listnetworkserviceorder | awk -F'\\) ' '/\(1\)/ {print $2}')
    # Completely disable IPv6
    sudo networksetup -setv6off "$main_interface"
    # Switch with your DNS server
    sudo networksetup -setdnsservers "$main_interface"
  *) ;;

# Your VPN connection should be up and running. Any following steps of your Bitrise workflow can access devices over your VPN connection 🎉

Cisco VPN connect

You can use the Cisco VPN connect Step: it connects with Cisco VPN provided by VPN3000 Concentrator, Juniper/Netscreen, IOS and PIX using vpnc.

To provide VPN client settings and credentials required for the Step, you can:

For more information on setting up vpnc, check the vpnc homepage and the vpnc manual.