Introduction
With ServiceNow's relatively new integration of source control in Studio, the application development process has improved significantly. However, instead of opting for a hosted Git repository from a service like GitHub or BitBucket, it may be preferable to host your own Git repository on a local server in your own secure network. This guide will show you how to configure a self-hosted Git repository that will be accessible from ServiceNow's servers using a machine on your own network running Apache.
This guide was written based on a setup using Ubuntu 18.04.1 LTS, Apache 2.4.29, and Git 2.17.1 running on a dedicated Dell laptop in my kitchen. In general, you will need the following:
- A machine (preferably Linux-based) to run your server
- Apache (sudo apt-get install apache2)
- Git (sudo apt-get install git)
- A ServiceNow instance
- Access to configure your network (Port-forwarding is required)
IMPORTANT: Using a self-hosted Git repository for source control in ServiceNow is not supported. If you have trouble, please do not open an incident with ServiceNow. Your incident will be closed.
VERY IMPORTANT: This guide does not cover security, as that is an extensive topic. I do not advocate implementing this kind of setup on your company's network without an extensive security review by qualified engineers. This guide is only intended to provide you with an example of a baseline configuration that you can then expand and modify to suit your company's needs.
Firewall Settings
Source control in ServiceNow must use either the HTTP or HTTPS protocol. For that reason, you cannot rely on SSH to connect to your server's Git repo. For this guide, we will be using HTTP. The port used by HTTP traffic is port 80. We will need to configure the network's firewall to forward this port to the local IP address of your server. Consult your ISP or your router's manual for instructions on logging in to the admin panel and changing the port forwarding settings. You will also need to determine which IP address to forward to. To obtain your server's IP address, run the ifconfig command:
root@ryan-laptop:~# ifconfig
enp9s0: flags=4163[UP,BROADCAST,RUNNING,MULTICAST] mtu 1500
inet 192.168.0.7 netmask 255.255.255.0 broadcast 192.168.0.255
inet6 fe80::9987:e061:4297:a09f prefixlen 64 scopeid 0x20
inet6 2606:6000:cdc4:8100:947d:71f3:ffed:a9a6 prefixlen 64 scopeid 0x0
inet6 2606:6000:cdc4:8100:30da:1724:8408:3b37 prefixlen 64 scopeid 0x0
ether 00:18:8b:d4:97:de txqueuelen 1000 (Ethernet)
RX packets 51771 bytes 5553504 (5.5 MB)
RX errors 0 dropped 0 overruns 0 frame 0
TX packets 34190 bytes 5441628 (5.4 MB)
TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
device interrupt 18
lo: flags=73[UP,LOOPBACK,RUNNING] mtu 65536
inet 127.0.0.1 netmask 255.0.0.0
inet6 ::1 prefixlen 128 scopeid 0x10
loop txqueuelen 1000 (Local Loopback)
RX packets 438 bytes 45613 (45.6 KB)
RX errors 0 dropped 0 overruns 0 frame 0
TX packets 438 bytes 45613 (45.6 KB)
TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
Ethernet connections usually start with 'e' and wireless connections usually start with 'w'. Yours may be 'eth0' or something different. The 'inet' value is what we're interested in. Here we can see my ethernet connection (enp9s0) is using the IP address 192.168.0.7. Use this IP address when forwarding port 80 on your network.
NOTE: If your server connects using DHCP, your IP address may change frequently. You will likely want to configure the server to use a static IP address. A quick search on the internet should provide instructions for configuring a static IP address on whatever operating system you are using.
Configure Apache
If you haven't done so already, you will need to install Apache:
sudo apt-get install apache2
Once installed, we need to enable some necessary modules:
a2enmod cgi alias env rewrite
Then, we need to make some changes to Apache's default configuration file. This file is called 000-default.conf and is located in the /etc/apache2/sites-enabled/ directory:
cd /etc/apache2/sites-enabled nano 000-default.conf
With the file open in nano, add the following snippet inside the VirtualHost tags:
SetEnv GIT_PROJECT_ROOT /var/www/html/git
SetEnv GIT_HTTP_EXPORT_ALL
ScriptAlias /git/ /usr/lib/git-core/git-http-backend/
RewriteEngine On
RewriteCond %{QUERY_STRING} service=git-receive-pack [OR]
RewriteCond %{REQUEST_URI} /git-receive-pack$
RewriteRule ^/git/ - [E=AUTHREQUIRED]
<Files "git-http-backend">
AuthType Basic
AuthName "Git Access"
AuthUserFile /var/www/html/.htpasswd
Require valid-user
Order deny,allow
Deny from env=AUTHREQUIRED
Satisfy any
</Files>
It's possible that your git-http-backend file will be elsewhere, so be sure to verify that file path. As you can see, the GIT_PROJECT_ROOT variable is set to /var/www/html/git. This is the simplest configuration since the /git/ folder is a direct descendant of our DocumentRoot. Since our server will be using this directory, we need to create it and initialize a Git repository inside of it:
mkdir /var/www/html/git cd /var/www/html/git mkdir test.git cd test.git git init --bare
With our directory and repo created, we now need to give ownership of this directory to the user that Apache will use for HTTP, which is typically www-data:
chown -R www-data /var/www/html/git
The last thing we need to do is create some credentials to authenticate with:
htpasswd –c /var/www/html/.htpasswd gituser
You will then be prompted to enter a password for the user. Remember these credentials, because it is what you will need to enter when linking your application to the repository in ServiceNow. Now the only thing left to do is restart our Apache server so the changes will take effect:
service apache2 restart
If your server was not already started, you will need to start it like this:
apache2ctl start
To test if our server is online and accessible from the internet through port 80, log on to a machine on a different network (such as a cell phone that is not connected to wi-fi) and enter the network's IP address into your favorite web browser. I customized my /var/www/html/index.html file, so when I access my server from the web I see this:
NOTE: Be sure to enter the network IP address, not the server's local IP address. The HTTP request coming through port 80 from your browser will be forwarded to your server's local address thanks to our network configuration. If you aren't sure what your network's IP address is, you can visit www.whatismyip.com from your server, or a machine that is connected to the same network as your server.
Link an Application
Now that our server, network, and Git repository are all set up, we can move on to the fun part. Let's create a new application in Studio and link it to our test.git repo. Start by going to System Applications > Studio in the navigator, select Create Application if prompted, and choose Start from scratch. Then, open the Source Control menu and select Link To Source Control. In the window that pops up, enter your server's address followed by the repository path. If you've been following along, it will look like this:
If everything is set up properly, your initial commit will go through and you will officially be linked to your very own self-hosted Git repository:
FAQ
Please share your questions and issues in the comments. I will do my best to respond to them and share the solutions in this section.
VERY IMPORTANT: This guide does not cover security, as that is an extensive topic. I do not advocate implementing this kind of setup on your company's network without an extensive security review by qualified engineers. This guide is only intended to provide you with an example of a baseline configuration that you can then expand and modify to suit your company's needs.
