Gitblit 1.10.0

In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration. Select Gitblit 1.10.0 on Ubuntu 24.04 as the software version, choose your Region, then choose Launch through EC2.

Choose m5.large, your key pair, a subnet and a security group as described above. Your repositories live on the root volume under /var/lib/gitblit, so raise its size under Configure storage if you expect large repositories.

To launch with the AWS CLI instead, replace the values in angle brackets. This command sets a 50 GiB root volume:

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --block-device-mappings 'DeviceName=/dev/sda1,Ebs={VolumeSize=50,VolumeType=gp3}' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=gitblit}]'

Connect over SSH with your key pair. For the Gitblit 1.10.0 on Ubuntu 24.04 AMI, the SSH user is ubuntu.

ssh -i <your-key.pem> ubuntu@<public-ip>

On first boot the instance works out its name, generates the certificate, the administrator password and Gitblit's SSH host keys, and starts Gitblit. It then proves a round trip over HTTPS and only then opens the web server. This takes about a minute. Check the services:

systemctl is-active gitblit nginx gitblit-set-host

active active active

gitblit-set-host runs on every boot before nginx. It keeps the served name, the certificate and nginx's host rules in step (Step 10).

Only SSH (22) and nginx (80, 443) listen on the network. Gitblit's web listener (8080) and its SSH server (29418) listen on the loopback address only, which Java shows as the IPv4-mapped [::ffff:127.0.0.1]. The :53 entries are Ubuntu's local DNS resolver, :323 is the time service on the loopback address and :68 is the DHCP client:

sudo ss -lntup | awk 'NR>1 {print $1, $5}' | sort -u

tcp 0.0.0.0:22 tcp 0.0.0.0:443 tcp 0.0.0.0:80 tcp 127.0.0.53%lo:53 tcp 127.0.0.54:53 tcp [::]:22 tcp [::]:443 tcp [::]:80 tcp [::ffff:127.0.0.1]:29418 tcp [::ffff:127.0.0.1]:8080 udp 127.0.0.1:323 udp 127.0.0.53%lo:53 udp 127.0.0.54:53 udp 172.31.80.97%ens5:68 udp [::1]:323

Gitblit runs as the gitblit account on Ubuntu's OpenJDK 17. Its settings are in /etc/gitblit/gitblit.properties. The command line carries the listener ports, so no other file can change them:

ps -o user:10=,args= -C java java -version 2>&1 | head -1

gitblit /usr/bin/java -XX:MaxRAMPercentage=40 -XX:+ExitOnOutOfMemoryError -XX:-UsePerfData -Djava.awt.headless=true --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.lang.reflect=ALL-UNNAMED -cp /opt/gitblit/gitblit.jar:/opt/gitblit/ext/* com.gitblit.GitBlitServer --baseFolder /var/lib/gitblit --settings /etc/gitblit/gitblit.properties --httpPort 8080 --httpsPort 0 --gitPort 0 --sshPort 29418 --shutdownPort 0 --tempFolder /var/lib/gitblit/temp --repositoriesFolder /var/lib/gitblit/git --userService /var/lib/gitblit/users.conf openjdk version "17.0.20.1" 2026-08-18

Gitblit can use up to 40% of the instance's memory for its Java heap, so a larger instance type gives it more room with no configuration change.

If nginx is not running, either first boot has not finished or it failed. In that case the web server is never opened. Check systemctl status gitblit-firstboot and sudo tail -40 /var/log/sac/gitblit-firstboot.log.

sudo cat /root/gitblit-credentials.txt

The file is readable by root only. It holds the address, the administrator's user name and password, and the certificate fingerprint:

# Gitblit - generated on first boot. Unique to this instance; keep it safe.
# Sign in at GITBLIT_URL as GITBLIT_USERNAME / GITBLIT_ADMIN_PASSWORD (the browser asks for them: HTTP Basic over TLS).
# Clone:
git clone https://ec2-203-0-113-10.compute-1.amazonaws.com/r/<repository>.git (git asks for the same user name and password)
# Compare GITBLIT_TLS_SHA256 with the certificate your browser shows (or install your own certificate: see the guide). GITBLIT_URL=https://ec2-203-0-113-10.compute-1.amazonaws.com/ GITBLIT_USERNAME=admin GITBLIT_ADMIN_PASSWORD=<GITBLIT_ADMIN_PASSWORD> GITBLIT_TLS_SHA256=38:1D:8B:33:0B:BC:51:0C:65:24:84:46:AF:F4:07:35:50:6B:0C:F3:37:15:FC:B2:31:F0:42:14:CA:35:E5:2B

To see everything but the password:

sudo grep -E '^GITBLIT_(URL|USERNAME|TLS_SHA256)=' /root/gitblit-credentials.txt

GITBLIT_URL=https://ec2-203-0-113-10.compute-1.amazonaws.com/ GITBLIT_USERNAME=admin GITBLIT_TLS_SHA256=38:1D:8B:33:0B:BC:51:0C:65:24:84:46:AF:F4:07:35:50:6B:0C:F3:37:15:FC:B2:31:F0:42:14:CA:35:E5:2B

You can confirm the whole path from the instance itself. The helper goes through nginx over HTTPS with the certificate pinned. It checks three things. First, that 19 kinds of request are refused without a credential. Second, that a wrong password and the well-known defaults (admin/admin, admin/password, gitblit/gitblit) are refused. Third, that this instance's password is accepted by the web interface, the RPC API and git:

sudo /usr/local/sbin/gitblit-verify.sh

GITBLIT_ROUNDTRIP_OK (HTTPS: 19 routes refused without a credential, wrong/admin:admin/admin:password/gitblit:gitblit refused; the minted credential accepted by the web UI, RPC and git smart HTTP)

Change the password with gitblit-set-password. With no argument it generates a new 24-character password. With - it reads your own password from standard input (at least 16 printable characters, with no spaces, :, " or backslash).

The command never accepts the password as an argument, so it does not appear in the process list or your shell history. It updates /root/gitblit-credentials.txt, and Gitblit refuses the old password as soon as the command returns:

$
sudo gitblit-set-password gitblit-set-password: the admin password was replaced (sudo cat /root/gitblit-credentials.txt)

To set your own password:

$ read -rs NEWPW && printf '%s\n' "$NEWPW" | sudo gitblit-set-password - ; unset NEWPW gitblit-set-password: the admin password was replaced (sudo cat /root/gitblit-credentials.txt)

Other users change their own password in the web interface: select their name at the top right, then change password. An administrator can also set it under users.

Open GITBLIT_URL in your browser. The certificate is self-signed until you install your own (Step 10), so the browser shows a warning once. Compare the fingerprint it shows with GITBLIT_TLS_SHA256.

The browser then asks for a user name and password. Enter admin and the password from Step 4. Gitblit uses HTTP Basic authentication over TLS for every page, so there is no separate sign-in form and no "remember me" cookie.

The dashboard lists the repositories you own and recent activity:

In the web interface: open the menu under your user name (top right) and choose new repository. Give the repository a name. Use / to group repositories into projects, for example team/service.git.

Restrict View, Clone & Push is preselected, so only the accounts you name can see the repository. Tick Include a README if you want to clone it straight away:

From git: an administrator, or an account that an administrator gave the can create right, can also create a repository by pushing to a new name. Clone URLs are https://<host>/r/<repository>.git, and git asks for your user name and password. From your workstation:

git init hello && cd hello echo "# hello" > README.md
git add README.md && git commit -m "First commit"
git push https://<host>/r/hello.git master

To trust the instance's self-signed certificate on your workstation, copy /etc/ssl/gitblit/gitblit.crt from the instance and use git -c http.sslCAInfo=gitblit.crt .... Alternatively, install a certificate from your own CA (Step 10). Never set http.sslVerify=false.

You can run the same round trip on the instance itself. The password reaches git through a small GIT_ASKPASS script that reads it from the credentials file, so it is never typed, printed or put on a command line:

cd "$(mktemp -d)"
GB_URL=$(sudo sed -n 's/^GITBLIT_URL=//p' /root/gitblit-credentials.txt) printf '#!/bin/sh\ncase "$1" in Username*) echo admin ;; *) sudo sed -n "s/^GITBLIT_ADMIN_PASSWORD=//p" /root/gitblit-credentials.txt ;; esac\n' > askpass.sh chmod 700 askpass.sh export GIT_ASKPASS="$PWD/askpass.sh" git -c init.defaultBranch=master init -q hello && cd hello echo "# hello" > README.md git add README.md && git -c user.name=Demo -c user.email=demo@example.com commit -qm "First commit" git -c http.sslCAInfo=/etc/ssl/gitblit/gitblit.crt push -q "${GB_URL}r/hello.git" master 2>&1 | grep -v '^remote:' || true
cd .. && git -c http.sslCAInfo=/etc/ssl/gitblit/gitblit.crt clone -q "${GB_URL}r/hello.git" hello-copy cat hello-copy/README.md git -C hello-copy log --oneline

# hello 743c6f4 First commit

The repository now has a summary page with the clone URL for your account, the branches and the activity:

Browse files under tree and history under commits. Each commit is shown with its diff:

Administrators manage accounts under users and teams, in the menu under their user name (top right). Choose new user and set a user name and a password of at least 12 characters.

Then grant repository permissions, either per repository or through a team. The permission levels are V (view), R (clone), RW (push), RWC (push and create branches and tags), RWD (also delete them) and RW+ (also rewrite history, which allows force push):

Accounts are stored with PBKDF2 password hashes in /var/lib/gitblit/users.conf, readable by the gitblit account only. There is no sign-up page and no external directory, so every account is one an administrator created. Give the #admin role only to people who need it, because an administrator can change every repository and every account.

Gitblit's SSH server listens on 127.0.0.1:29418 and accepts public keys only. Gitblit offers no password method over SSH, and its keyboard-interactive method never prompts and never succeeds.

Add your public key in the web interface. Open the menu under your user name (top right), choose my profile, then SSH Keys. Paste the contents of your ~/.ssh/id_ed25519.pub (or another public key) and choose the permission the key carries. The default is RW, and a key never has more permission than your account:

Use SSH through a tunnel (nothing to open). Forward a local port to Gitblit's SSH server over your normal SSH connection, then use localhost in the repository URL:

ssh -N -i <your-key.pem> -L 29418:127.0.0.1:29418 ubuntu@<public-ip> & git clone ssh://admin@localhost:29418/hello.git

Or open SSH to your network. Make three changes:

• Let Gitblit listen on every address. In /etc/gitblit/gitblit.properties, set git.sshBindInterface = (empty) and web.showSshDaemonUrls = true, so the repository page shows SSH clone URLs.
• Let the Gitblit service accept connections from your network. Its systemd sandbox allows the loopback address only, so add your client network. This also lets Gitblit send traffic to that network, but never to the metadata service:

text sudo mkdir -p /etc/systemd/system/gitblit.service.d printf '[Service]\nIPAddressAllow=<your-client-cidr>\n' | sudo tee /etc/systemd/system/gitblit.service.d/60-ssh-clients.conf sudo systemctl daemon-reload && sudo systemctl restart gitblit

• Allow TCP 29418 in the instance's security group from that network only.

Then clone with git clone ssh://<user>@<host>:29418/<repository>.git. Gitblit's host keys were generated on your instance's first boot. Compare them with what your SSH client shows:

ssh-keyscan -p 29418 127.0.0.1 2>/dev/null | ssh-keygen -lf - | awk '{print $1, $3, $4}' | sort

2048 [127.0.0.1]:29418 (RSA) 256 [127.0.0.1]:29418 (ECDSA) 256 [127.0.0.1]:29418 (ED25519)

The fingerprints (the second field of ssh-keygen -lf -) are unique to your instance. Gitblit's unauthenticated git daemon (port 9418) stays off. No setting on this image turns it on without a change to the service's command line.

Gitblit can run Groovy scripts before and after a push, and it can load plugins. Both run inside the Gitblit service, as the gitblit account, with access to every repository and account. Treat them as administrator-only:

• groovy.scriptsFolder is /etc/gitblit/groovy and plugins.folder is /etc/gitblit/plugins. Both are owned by root, empty and read-only to Gitblit. A Gitblit user, even an administrator in the web interface, cannot add a script or plugin. Only root on the instance can.
• No script is enabled: groovy.preReceiveScripts and groovy.postReceiveScripts are empty. Upstream's sample scripts are kept for reference, not executable, in /usr/share/doc/gitblit/groovy-samples.
• To use a hook, review the script, then copy it as root into /etc/gitblit/groovy. Name it in groovy.preReceiveScripts or groovy.postReceiveScripts (all repositories), or in a repository's settings. Then restart Gitblit.

These features are also off on this image. Each is a setting in /etc/gitblit/gitblit.properties, and upstream's documentation of every key is in /etc/gitblit/defaults.properties:

• Federation (federation.passphrase empty, federation.allowProposals = false): no other Gitblit can pull your repositories or accounts, and nginx answers 404 for /federation/.
• The git daemon and fanout (git.daemonPort = 0, fanout.port = 0).
• RPC administration and management (web.enableRpcManagement and web.enableRpcAdministration false): the RPC API can list repositories and branches for a signed-in user, but cannot change settings, accounts or repositories.
• Mirroring (git.enableMirroring = false): Gitblit never fetches from another server.
• Cookie sign-in (web.allowCookieAuthentication = false).

After you change the file, run sudo systemctl restart gitblit. Read the comments marked [security] in the file before you change those values.

On every boot, gitblit-set-host works out the name to serve. It uses the name you set or, failing that, the instance's public DNS name from the instance metadata service (IMDSv2). Gitblit builds its clone URLs from that name:

systemctl is-enabled gitblit-set-host.service
sudo gitblit-set-hostname --boot

enabled gitblit-set-hostname: unchanged (ec2-203-0-113-10.compute-1.amazonaws.com)

To use your own DNS name, point a DNS record at the instance (an Elastic IP keeps the address fixed), then run sudo gitblit-set-hostname git.example.com.

The helper keeps the name in /etc/sac/gitblit-hostname for every later boot and updates the credentials file. nginx then serves that name and redirects the instance's other addresses to it, and clone URLs become https://git.example.com/r/.... Because the certificate in place is the one SecureAnyCloud generated, it is re-created for the new name.

Only a certificate that SecureAnyCloud generated is ever re-created. Its SHA-256 fingerprint is recorded, owned by root, in /var/lib/sac/data/gitblit-cert.sha256, and a certificate counts as SecureAnyCloud's only while it matches that record:

sudo cat /var/lib/sac/data/gitblit-cert.sha256 openssl x509 -in /etc/ssl/gitblit/gitblit.crt -noout -fingerprint -sha256

38:1D:8B:33:0B:BC:51:0C:65:24:84:46:AF:F4:07:35:50:6B:0C:F3:37:15:FC:B2:31:F0:42:14:CA:35:E5:2B sha256 Fingerprint=38:1D:8B:33:0B:BC:51:0C:65:24:84:46:AF:F4:07:35:50:6B:0C:F3:37:15:FC:B2:31:F0:42:14:CA:35:E5:2B

Install your own certificate (from your CA, or from Let's Encrypt with a DNS challenge) by putting the full chain and the key at the same paths. Anything there that does not match the record is yours and is never replaced, neither on boot nor when the name changes:

sudo install -m 0644 -o root -g root fullchain.pem /etc/ssl/gitblit/gitblit.crt
sudo install -m 0600 -o root -g root privkey.pem /etc/ssl/gitblit/gitblit.key
sudo nginx -t && sudo systemctl reload nginx

Go back to a generated certificate by removing both files and running the helper with the name to serve:

$
sudo rm /etc/ssl/gitblit/gitblit.crt /etc/ssl/gitblit/gitblit.key $
sudo gitblit-set-hostname git.example.com

To return to the instance's own public name on every boot, run sudo rm /etc/sac/gitblit-hostname && sudo gitblit-set-hostname --boot.

Everything Gitblit stores is under /var/lib/gitblit: the repositories in git/, the accounts in users.conf, the SSH keys users added in ssh/, the tickets in tickets/, and the SSH host keys. Back it up with an EBS snapshot of the root volume, or stop Gitblit and copy the folder:

sudo systemctl stop gitblit
sudo tar -C /var/lib -czf /root/gitblit-backup.tar.gz gitblit
sudo systemctl start gitblit

Unattended security upgrades update Ubuntu packages, including OpenJDK, nginx and git. To update everything immediately, run sudo apt-get update && sudo apt-get upgrade, then sudo systemctl restart gitblit so that Gitblit runs on the updated Java.

Gitblit itself is not an apt package. It is the release in /opt/gitblit, and apt never changes it:

systemctl is-enabled unattended-upgrades apt-daily-upgrade.timer dpkg -S /opt/gitblit/gitblit.jar 2>&1 || true

enabled enabled dpkg-query: no path found matching pattern /opt/gitblit/gitblit.jar

SecureAnyCloud publishes a new version of this listing when Gitblit has a new release or a security fix. To move to it, launch the new version and restore /var/lib/gitblit into it. Stop Gitblit first, and keep the files owned by gitblit.