Icy is a fork of Soft Serve. Charm has sunset Soft Serve. Thank you to Charm and to everyone who contributed to it over the years.
A tasty, self-hostable Git server for the command line. 🍦
- Easy to navigate TUI available over SSH
- Clone repos over SSH, HTTP, or Git protocol
- Git LFS support with both HTTP and SSH backends
- Manage repos with SSH
- Create repos on demand with SSH or
git push - Browse repos, files and commits with SSH-accessible UI
- Print files over SSH with or without syntax highlighting and line numbers
- Easy access control
- SSH authentication using public keys
- Allow/disallow anonymous access
- Add collaborators with SSH public keys
- Repos can be public or private
- User access tokens
Icy is a single binary called icy. Install it with go:
go install github.com/skunkwerks/icy/cmd/icy@latestOr build it from a checkout:
go build -o icy ./cmd/icyA Docker image is also available.
Make sure git is installed, then run icy serve. That’s it.
This will create a data directory that will store all the repos, ssh keys,
and database.
By default, program configuration is stored within the data directory. But,
this can be overridden by setting a custom path to a config file with ICY_CONFIG_LOCATION
that is pre-created. If a config file pointed to by ICY_CONFIG_LOCATION,
the default location within the data dir is used for generating a default config.
To change the default data path use ICY_DATA_PATH environment variable.
ICY_DATA_PATH=/var/lib/icy icy serveWhen you run Icy for the first time, make sure you have the
ICY_INITIAL_ADMIN_KEYS environment variable is set to your ssh
authorized key. Any added key to this variable will be treated as admin with
full privileges.
Using this environment variable, Icy will create a new admin user that
has full privileges. You can rename and change the user settings later.
If you'd like a repository to exist the moment the server finishes booting,
with no human logging in to run repo create, set ICY_DEFAULT_REPO
to a repository name. This is useful for GitOps tools like ArgoCD that need a
git remote to point at as part of their own bootstrap (e.g. from a Helm chart
or Terraform apply):
ICY_INITIAL_ADMIN_KEYS="$(cat ~/.ssh/id_ed25519.pub)" \
ICY_DEFAULT_REPO=gitops \
icy serveThe repository is created empty and public, exactly as if a human had run
repo create gitops with no flags; only its existence is guaranteed on
boot, not its reachability, which is still governed entirely by the
anon-access/allow-keyless settings described below. Booting again against
the same data directory is a no-op if the repository already exists.
Check out Systemd on how to run Icy as a service using Systemd. Icy packages in our Apt/Yum repositories come with Systemd service units.
Once you start the server for the first time, the settings will be in
config.yaml under your data directory. The default config.yaml is
self-explanatory and will look like this:
# Icy Server configurations
# The name of the server.
# This is the name that will be displayed in the UI.
name: "Icy"
# Log format to use. Valid values are "json", "logfmt", and "text".
log_format: "text"
# The SSH server configuration.
ssh:
# The address on which the SSH server will listen.
listen_addr: ":23231"
# The public URL of the SSH server.
# This is the address that will be used to clone repositories.
public_url: "ssh://localhost:23231"
# The path to the SSH server's private key.
key_path: "ssh/icy_host"
# The path to the SSH server's client private key.
# This key will be used to authenticate the server to make git requests to
# ssh remotes.
client_key_path: "ssh/icy_client"
# How the server's ssh client verifies host keys of ssh remotes it imports
# or mirrors from, checked against <data_path>/ssh/known_hosts.
# "accept-new" records a host key on first contact and refuses a changed
# one (needs OpenSSH 7.6 or newer). "yes" refuses any host that is not
# already in known_hosts; use it with a pre-seeded known_hosts file.
client_strict_host_key_checking: "accept-new"
# The ssh hosts that repositories may be imported from or mirrored. The
# client key above is presented to every host a user imports from, so list
# only hosts you trust that key with. Entries are hostnames, IP addresses,
# or CIDR ranges, each with an optional port. When the list is empty, only
# server admins may import from or mirror ssh remotes.
# CIDR entries are checked against DNS only at import or sync time and ssh
# resolves the name again, so prefer hostnames for anything you do not
# control. The list is matched against the name given to ssh; your
# ssh_config still applies to it.
client_allowed_hosts: []
# - "git.internal.example"
# - "gitlab.corp:2222"
# - "10.0.0.0/8"
# The maximum number of seconds a connection can take.
# A value of 0 means no timeout.
max_timeout: 0
# The number of seconds a connection can be idle before it is closed.
idle_timeout: 120
# The Git daemon configuration.
git:
# The address on which the Git daemon will listen.
listen_addr: ":9418"
# The maximum number of seconds a connection can take.
# A value of 0 means no timeout.
max_timeout: 0
# The number of seconds a connection can be idle before it is closed.
idle_timeout: 3
# The maximum number of concurrent connections.
max_connections: 32
# The HTTP server configuration.
http:
# The address on which the HTTP server will listen.
listen_addr: ":23232"
# The path to the TLS private key.
tls_key_path: ""
# The path to the TLS certificate.
tls_cert_path: ""
# The public URL of the HTTP server.
# This is the address that will be used to clone repositories.
# Make sure to use https:// if you are using TLS.
public_url: "http://localhost:23232"
# The cross-origin request security options
cors:
# The allowed cross-origin headers
allowed_headers:
- "Accept"
- "Accept-Language"
- "Content-Language"
- "Content-Type"
- "Origin"
- "X-Requested-With"
- "User-Agent"
- "Authorization"
- "Access-Control-Request-Method"
- "Access-Control-Allow-Origin"
# The allowed cross-origin URLs
allowed_origins:
- "http://localhost:23232" # always allowed
# - "https://example.com"
# The allowed cross-origin methods
allowed_methods:
- "GET"
- "HEAD"
- "POST"
- "PUT"
- "OPTIONS"
# The database configuration.
db:
# The database driver to use.
# Valid values are "sqlite" and "postgres".
driver: "sqlite"
# The database data source name.
# This is driver specific and can be a file path or connection string.
# Make sure foreign key support is enabled when using SQLite.
data_source: "icy.db?_pragma=busy_timeout(5000)&_pragma=foreign_keys(1)"
# Git LFS configuration.
lfs:
# Enable Git LFS.
enabled: true
# Enable Git SSH transfer.
ssh_enabled: false
# The read-only web UI, served by the HTTP server.
web:
# Enable the web UI.
enabled: true
# Who runs this server, shown on the front page.
owner: ""
# A short description, shown on the front page.
description: ""
# Cron job configuration
jobs:
mirror_pull: "@every 10m"
# Repository webhook configuration.
webhook:
# Private or internal networks that webhooks may reach, such as a CI
# server on the LAN. Entries are CIDR prefixes or single IP addresses.
allowed_networks: []
# How many times a delivery is tried before it is given up.
max_attempts: 5
# The wait after the first failed attempt. It doubles after each failure.
retry_backoff: "2m0s"
# The stats server configuration.
stats:
# The address on which the stats server will listen.
listen_addr: ":23233"
# Additional admin keys.
#initial_admin_keys:
# - "ssh-rsa AAAAB3NzaC1yc2..."
# Override the anon-access and allow-keyless settings below (normally
# managed at runtime via the `settings` command and stored in the
# database). If set, these always take precedence over the database, for
# as long as they remain set -- not just on first run. This is intended for
# scripted, non-production bootstrapping (e.g. spinning up a throwaway
# server for local dev tooling), not for production use.
# With state_source "config" they are written to the database instead.
#anon_access: "admin-access"
#allow_keyless: true
# Repository name to create on boot if it does not already exist.
# Leave empty to disable.
#default_repo: ""
# Where users, repositories and access settings come from: "db" or
# "config". See "Users and Repositories in config.yaml" below.
#state_source: "db"You can also use environment variables, to override these settings. All server
settings environment variables start with ICY_ followed by the setting
name all in uppercase. Here are some examples:
ICY_NAME: The name of the server that will appear in the TUIICY_SSH_LISTEN_ADDR: SSH listen addressICY_SSH_KEY_PATH: SSH host key-pair pathICY_HTTP_LISTEN_ADDR: HTTP listen addressICY_HTTP_PUBLIC_URL: HTTP public URL used for cloningICY_GIT_MAX_CONNECTIONS: The number of simultaneous connections to git daemonICY_ANON_ACCESS: Overrides theanon-accesssetting (see Authentication)ICY_ALLOW_KEYLESS: Overrides theallow-keylesssetting (see Authentication)ICY_DEFAULT_REPO: Repository name to create on boot if missingICY_STATE_SOURCE: Where users, repositories and access come from,dborconfig(see Users and Repositories in config.yaml)
Icy supports both SQLite and Postgres for its database. Like all other Icy settings, you can change the database driver and data source using either config.yaml or environment variables. The default config uses SQLite as the default database driver.
To use Postgres as your database, first create a Icy database:
psql -h<hostname> -p<port> -U<user> -c 'CREATE DATABASE icy'Then set the database data source to point to your Postgres database. For instance, if you're running Postgres locally, using the default user postgres and using a database name icy, you would have this config in your config file or environment variable:
db:
driver: "postgres"
data_source: "postgres://postgres@localhost:5432/icy?sslmode=disable"
Environment variables equivalent:
ICY_DB_DRIVER=postgres \
ICY_DB_DATA_SOURCE="postgres://postgres@localhost:5432/icy?sslmode=disable" \
icy serveYou can specify a database connection password in the data source url. For example, postgres://myuser:dbpass@localhost:5432/my_icy_db.
Icy supports both Git LFS HTTP and SSH protocols out of the box, there is no need to do any extra set up.
Use the lfs config section to customize your Git LFS server.
Note: The pure-SSH transfer is disabled by default.
By default Icy keeps users, repositories and access settings in its database,
and you change them with ssh commands. You can instead list them in
config.yaml. This suits tools such as Ansible, which can template the file
and reload the server.
Turn it on with state_source: config in config.yaml, the
ICY_STATE_SOURCE=config environment variable, or
icy serve --state-source config. The flag beats the environment variable,
which beats the file. Then add these top-level keys:
state_source: config
anon_access: read-only # no-access, read-only, read-write or admin-access
allow_keyless: true
users:
- name: alice
admin: true
public_keys:
- "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5... alice@laptop"
- name: bob
public_keys:
- "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5... bob@desk"
repos:
- name: icy
project_name: Icy
description: A Git server
private: true
hidden: false
owner: alice # defaults to the first admin in users
collaborators:
bob: read-writeAt startup, and each time the server gets SIGHUP, Icy reads these keys and
makes the database match them. It adds what is new, updates what has changed
and removes what the file no longer lists. A removed repository is moved to
repos-removed in the data directory, not deleted. A reload applies only these
keys. Other settings, such as listen addresses, still need a restart, and the
log says so if they have changed.
Icy checks all of these keys before it changes anything, and applies them in
one database transaction. An unknown key inside users or repos is an error,
so a typo cannot drop a setting. A file with errors stops the server from
starting. On SIGHUP, a file with errors is logged and the server keeps its
current state. Two more checks guard against mistakes:
- The file must list at least one admin with a public key, unless
initial_admin_keysis set, so that you cannot lock yourself out. - The file must have a
usersor areposkey. Aconfig.yamlwith neither would remove every user and repository. Writeusers: []andrepos: []if that is what you want.
anon_access and allow_keyless follow one rule in both modes. The
environment variable (ICY_ANON_ACCESS, ICY_ALLOW_KEYLESS) beats
config.yaml, which beats the database. With state_source: db, a value from
either overrides the database while it is set, and the settings command
changes the database underneath. With state_source: config, Icy writes the
winning value into the database at startup and on reload. A key left out of
the file means the default: read-only and true.
While state_source is config, ssh commands that would change users,
repositories, collaborators or settings are refused. Pushes to repositories in
the file still work. A push to a repository that is not in the file does not
create it. With state_source: db, any users or repos keys in
config.yaml are ignored, and the log warns about them.
To check a file before you install it, for example as an Ansible validate
step, run icy admin check-state FILE. With no FILE it checks the server's
own config.yaml. To move an existing server over, run
icy admin export-state. It prints the current users, repositories and
settings as keys to paste into config.yaml.
Icy at its core manages your server authentication and authorization. Authentication verifies the identity of a user, while authorization determines their access rights to a repository.
To manage the server users, access, and repos, you can use the SSH command line interface.
Try ssh localhost -i ~/.ssh/id_ed25519 -o IdentitiesOnly=yes -p 23231 help for more info. Make sure
you use your key here.
Note The
IdentitiesOnlyoption is used to prevent SSH from using any other keys in your~/.sshdirectory. This is useful when you have multiple keys, and you want to use a specific key for Icy.
For ease of use, instead of specifying the key, port, and hostname every time
you SSH into Icy, add your own Icy instance entry to your SSH
config. For instance, to use ssh icy instead of typing ssh localhost -i ~/.ssh/id_ed25519 -o IdentitiesOnly=yes -p 23231, we can define a icy entry in our SSH config
file ~/.ssh/config.
Host icy
HostName localhost
Port 23231
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yesNow, we can do ssh icy to SSH into Icy. Since git is also aware of
this config, you can use icy as the hostname for your clone commands.
git clone ssh://icy/dotfiles
# make changes
# add & commit
git push origin mainNote The
-iand-oparts will be omitted in the examples below for brevity. You can add your server settings to your sshconfig for quicker access.
Everything that needs authentication is done using SSH. Make sure you have
added an entry for your Icy instance in your ~/.ssh/config file.
By default, Icy gives read-only permission to anonymous connections to
any of the above protocols. This is controlled by two settings anon-access
and allow-keyless.
anon-access: Defines the access level for anonymous users. Available options areno-access,read-only,read-write, andadmin-access. Default isread-only.allow-keyless: Whether to allow connections that doesn't use keys to pass. Setting this tofalsewould disable access to SSH keyboard-interactive, HTTP, and Git protocol connections. Default istrue.
$ ssh -p 23231 localhost settings
Manage server settings
Usage:
ssh -p 23231 localhost settings [command]
Available Commands:
allow-keyless Set or get allow keyless access to repositories
anon-access Set or get the default access level for anonymous users
Flags:
-h, --help help for settings
Use "ssh -p 23231 localhost settings [command] --help" for more information about a command.Note These settings can only be changed by admins.
When allow-keyless is disabled, connections that don't use SSH Public Key
authentication will get denied. This means cloning repos over HTTP(s) or git://
will get denied.
Meanwhile, anon-access controls the access level granted to connections that
use SSH Public Key authentication but are not registered users. The default
setting for this is read-only. This will grant anonymous connections that use
SSH Public Key authentication read-only access to public repos.
anon-access is also used in combination with allow-keyless to determine the
access level for HTTP(s) and git:// clone requests.
anon-access and allow-keyless are normally admin-only runtime settings,
which means scripting a fully open server from a cold start would otherwise
require booting with an admin key, waiting for the server to come up, then
SSHing in as that admin to run settings commands. For local development
tooling (e.g. standing up a throwaway Git remote for something like Argo CD
to pull from in a dev environment), you can instead set the ICY_ANON_ACCESS
and ICY_ALLOW_KEYLESS environment variables (or the equivalent
anon_access/allow_keyless config.yaml fields) to grant full,
unauthenticated access from the moment the server starts, with no admin key
and no settings command required:
ICY_ANON_ACCESS=admin-access \
ICY_ALLOW_KEYLESS=true \
icy serveWarning This grants anyone who can reach the server full admin access with no authentication at all. It is intended strictly for local/dev use on a machine or network you trust — never expose a server configured this way to an untrusted network. The server logs a warning banner on startup whenever this combination is active.
Unlike the
settingscommand, these overrides always take precedence over the database for as long as they're set — not just on first run. If you also try to tighten access viassh icy settings ...while an override is active, the change is saved but has no effect until the override is removed; thesettingscommand will warn you when this happens.
Icy doesn't allow duplicate SSH public keys for users. A public key can be associated with one user only. This makes SSH authentication simple and straight forward, add your public key to your Icy user to be able to access Icy.
You can generate user access tokens through the SSH command line interface. Access tokens can have an optional expiration date. Use your access token as the basic auth user to access your Icy repos through HTTP.
# Create a user token
ssh -p 23231 localhost token create 'my new token'
ss_1234abc56789012345678901234de246d798fghi
# Or with an expiry date
ssh -p 23231 localhost token create --expires-in 1y 'my other token'
ss_98fghi1234abc56789012345678901234de246d7Now you can access to repos that require read-write access.
git clone http://ss_98fghi1234abc56789012345678901234de246d7@localhost:23232/my-private-repo.git my-private-repo
# Make changes and pushIcy offers a simple access control. There are four access levels, no-access, read-only, read-write, and admin-access.
admin-access has full control of the server and can make changes to users and repos.
read-write access gets full control of repos.
read-only can read public repos.
no-access denies access to all repos.
Admins can manage users and their keys using the user command. Once a user is
created and has access to the server, they can manage their own keys and
settings.
To create a new user simply use user create:
# Create a new user
ssh -p 23231 localhost user create beatrice
# Add user keys
ssh -p 23231 localhost user add-pubkey beatrice ssh-rsa AAAAB3Nz...
ssh -p 23231 localhost user add-pubkey beatrice ssh-ed25519 AAAA...
# Create another user with public key
ssh -p 23231 localhost user create frankie '-k "ssh-ed25519 AAAATzN..."'
# Need help?
ssh -p 23231 localhost user helpOnce a user is created, they get read-only access to public repositories.
They can also create new repositories on the server.
Users can manage their keys using the pubkey command:
# List user keys
ssh -p 23231 localhost pubkey list
# Add key
ssh -p 23231 localhost pubkey add ssh-ed25519 AAAA...
# Wanna change your username?
ssh -p 23231 localhost set-username yolo
# To display user info
ssh -p 23231 localhost infoYou can manage repositories using the repo command.
# Run repo help
$ ssh -p 23231 localhost repo help
Manage repositories
Usage:
ssh -p 23231 localhost repo [command]
Aliases:
repo, repos, repository, repositories
Available Commands:
blob Print out the contents of file at path
branch Manage repository branches
collab Manage collaborators
create Create a new repository
delete Delete a repository
description Set or get the description for a repository
hide Hide or unhide a repository
import Import a new repository from remote
info Get information about a repository
list List repositories
mirror Set or get a repository mirror property
private Set or get a repository private property
project-name Set or get the project name for a repository
rename Rename an existing repository
tag Manage repository tags
tree Print repository tree at path
Flags:
-h, --help help for repo
Use "ssh -p 23231 localhost repo [command] --help" for more information about a command.To use any of the above repo commands, a user must be a collaborator in the repository. More on this below.
To create a repository, first make sure you are a registered user. Use the
repo create <repo> command to create a new repository:
# Create a new repository
ssh -p 23231 localhost repo create icecream
# Create a repo with description
ssh -p 23231 localhost repo create icecream '-d "This is an Ice Cream description"'
# ... and project name
ssh -p 23231 localhost repo create icecream '-d "This is an Ice Cream description"' '-n "Ice Cream"'
# I need my repository private!
ssh -p 23231 localhost repo create icecream -p '-d "This is an Ice Cream description"' '-n "Ice Cream"'
# Help?
ssh -p 23231 localhost repo create -hOr you can add your Icy server as a remote to any existing repo, given you have write access, and push to remote:
git remote add origin ssh://localhost:23231/icecream
After you’ve added the remote just go ahead and push. If the repo doesn’t exist on the server it’ll be created.
git push origin main
Repositories can be nested too:
# Create a new nested repository
ssh -p 23231 localhost repo create skunkwerks/icecream
# Or ...
git remote add icy ssh://localhost:23231/skunkwerks/icecream
git push icy mainYou can also import repositories from any public remote. Use the repo import command.
ssh -p 23231 localhost repo import icy https://github.com/skunkwerks/icyUse --mirror or -m to mark the repository as a pull mirror.
You can delete repositories using the repo delete <repo> command.
ssh -p 23231 localhost repo delete icecreamUse the repo rename <old> <new> command to rename existing repositories.
ssh -p 23231 localhost repo rename icecream vanillaSometimes you want to restrict write access to certain repositories. This can be achieved by adding a collaborator to your repository.
Use the repo collab <command> <repo> command to manage repo collaborators.
# Add collaborator to icy
ssh -p 23231 localhost repo collab add icy frankie
# Add collaborator with a specific access level
ssh -p 23231 localhost repo collab add icy beatrice read-only
# Remove collaborator
ssh -p 23231 localhost repo collab remove icy beatrice
# List collaborators
ssh -p 23231 localhost repo collab list icyYou can also change the repo's description, project name, whether it's private,
etc using the repo <command> command.
# Set description for repo
ssh -p 23231 localhost repo description icecream "This is a new description"
# Hide repo from listing
ssh -p 23231 localhost repo hidden icecream true
# List repository info (branches, tags, description, etc)
ssh -p 23231 localhost repo icecream infoTo make a repository private, use repo private <repo> [true|false]. Private
repos can only be accessed by admins and collaborators.
ssh -p 23231 localhost repo private icecream trueA repository has one of three visibilities.
publicrepositories are listed. Anyone theanon-accesssetting allows can read and clone them.unlistedrepositories are listed only for signed in users. Anyone who knows the name can still read them and clone them over HTTPS.privaterepositories can only be read by admins, the owner and collaborators. To everyone else a private repository looks exactly like one that does not exist.
The web front page, repo list and the TUI all list repositories by the
same rule. Signed in means a registered user: over ssh, a key that belongs
to a user, and on the web, a session from web login.
| Who | Public | Unlisted | Private |
|---|---|---|---|
Anonymous, allow-keyless on |
anon-access, listed |
anon-access by name, not listed |
nothing, looks missing |
Anonymous, allow-keyless off |
nothing | nothing | nothing, looks missing |
| Signed in user | read, listed | read, listed | nothing, looks missing |
| Collaborator | their access, listed | their access, listed | their access, listed |
| Owner or admin | admin, listed | admin, listed | admin, listed |
anon-access is read-only by default. A collaborator never gets less than
anon-access on a public repository. The owner is the user who created the
repository. A private repository is listed for those who can read it even
when it is also hidden.
Visibility is stored in the private and hidden flags, so the private and
hidden commands still work. unlisted is the same as hidden but not private.
# Show the visibility
ssh -p 23231 localhost repo visibility icecream
# Change it
ssh -p 23231 localhost repo visibility icecream unlisted
# Set it when creating a repository
ssh -p 23231 localhost repo create icecream --visibility privateUse repo branch and repo tag to list, and delete branches or tags. You can
also use repo branch default to set or get the repository default branch.
To print a file tree for the project, just use the repo tree command along with
the repo name as the SSH command to your Icy server:
ssh -p 23231 localhost repo tree icyYou can also specify the sub-path and a specific reference or branch.
ssh -p 23231 localhost repo tree icy server/config
ssh -p 23231 localhost repo tree icy main server/configFrom there, you can print individual files using the repo blob command:
ssh -p 23231 localhost repo blob icy cmd/icy/main.goYou can add the -c flag to enable syntax coloring and -l to print line
numbers:
ssh -p 23231 localhost repo blob icy cmd/icy/main.go -c -l
Use --raw to print raw file contents. This is useful for dumping binary data.
A webhook sends an HTTP POST to a URL when something happens in a
repository. Repo admins manage them with the repo webhook command. Use
ssh -p 23231 localhost repo webhook help for the full list of flags.
# Send push events to a CI server, signed with a secret
ssh -p 23231 localhost repo webhook create icy https://ci.example.com/hook \
-e push -e branch_tag_create --secret 's3cret'
# List webhooks and their IDs
ssh -p 23231 localhost repo webhook list icy
# Change the URL or events of webhook 1, or switch it off
ssh -p 23231 localhost repo webhook update icy 1 --url https://ci2.example.com/hook
ssh -p 23231 localhost repo webhook update icy 1 --active=falsePass one or more of these to -e:
| Event | Sent when |
|---|---|
push |
commits are pushed to a branch or tag |
branch_tag_create |
a branch or tag is created |
branch_tag_delete |
a branch or tag is deleted |
collaborator |
a collaborator is added or removed |
repository |
the repository is created, deleted, or renamed |
repository_visibility_change |
the repository is made private or public |
A push that creates a branch sends both branch_tag_create and push.
The body is JSON by default. Use --content-type form to get it as
application/x-www-form-urlencoded instead. Every event has event,
repository, and sender. A push event adds these fields:
refis the full name of the ref that moved, such asrefs/heads/main.beforeis the commit the ref pointed at before the push. It is all zeros when the push created the ref.afteris the commit the ref points at now. Build this one.commitslists up to 20 of the pushed commits, newest first.
A trimmed push payload looks like this:
{
"event": "push",
"ref": "refs/heads/main",
"before": "0f3c1b5a…",
"after": "9a8e47d2…",
"repository": {
"id": 3,
"name": "icy",
"private": true,
"default_branch": "main",
"owner": { "id": 1, "username": "admin" },
"http_url": "https://git.example.com/icy.git",
"ssh_url": "ssh://git.example.com:23231/icy.git",
"git_url": "git://git.example.com/icy.git"
},
"sender": { "id": 2, "username": "frankie" },
"commits": [
{
"id": "9a8e47d2…",
"title": "Fix the build",
"message": "Fix the build\n",
"author": { "name": "Frankie", "email": "frankie@example.com", "date": "2026-11-17T10:04:27Z" },
"committer": { "name": "Frankie", "email": "frankie@example.com", "date": "2026-11-17T10:04:27Z" },
"timestamp": "2026-11-17T10:04:27Z"
}
]
}| Header | Value |
|---|---|
Content-Type |
application/json or application/x-www-form-urlencoded |
User-Agent |
Icy/<version> |
X-Icy-Event |
the event name, such as push |
X-Icy-Delivery |
a UUID for this delivery. Retries send the same UUID. |
X-Icy-Signature |
sha256= and the hex HMAC of the body. Sent only with a secret. |
A receiver can drop a delivery whose X-Icy-Delivery it has seen before.
This stops a retry from starting a second build.
When the webhook has a secret, Icy signs the raw request body with HMAC-SHA256 and that secret. Compute the same HMAC over the bytes you received, before any JSON parsing, and compare it with the header. Reject the request if they differ.
In shell, with the body saved to body.json and the header value in
HTTP_X_ICY_SIGNATURE, as a CGI script gets it:
want="sha256=$(openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -r body.json | cut -d' ' -f1)"
[ "$want" = "$HTTP_X_ICY_SIGNATURE" ] || { echo "bad signature" >&2; exit 1; }In Go:
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
)
// validSignature reports whether header is the X-Icy-Signature of body.
func validSignature(body []byte, header, secret string) bool {
mac := hmac.New(sha256.New, []byte(secret))
mac.Write(body)
want := "sha256=" + hex.EncodeToString(mac.Sum(nil))
return hmac.Equal([]byte(header), []byte(want))
}hmac.Equal takes the same time for every input, so it does not leak how
much of the signature matched.
Icy does not send webhooks during the push. The git hook writes each
delivery to a queue in the database and returns at once. The icy serve
process sends queued deliveries within a second or so. A slow or broken
receiver never holds up a push.
A delivery succeeds when the receiver answers with a 2xx status. Any
other status, a timeout, or a connection error counts as a failure. Each
attempt times out after 30 seconds. After a failure Icy waits and tries
again, and the wait doubles each time. With the defaults it tries five
times, waiting 2, 4, 8, and 16 minutes, so it gives up about 30 minutes
after the push. One failing webhook does not delay the others.
The queue lives in the database, so deliveries survive a restart of the server. A delivery that was in flight when the server stopped is sent again when it starts.
Change the retry policy in config.yaml, or with ICY_WEBHOOK_MAX_ATTEMPTS
and ICY_WEBHOOK_RETRY_BACKOFF:
webhook:
max_attempts: 5
retry_backoff: "2m"Every attempt is kept in the delivery log. Only repo admins can read it, because it has the full request and response.
# List deliveries of webhook 1. ✅ is a 2xx answer, ❌ is a failure,
# and ⏳ is still queued or waiting to retry.
ssh -p 23231 localhost repo webhook deliveries list icy 1
# Show the request and response of one attempt
ssh -p 23231 localhost repo webhook deliveries get icy 1 <delivery-id>
# Queue a recorded delivery to be sent again, with a new delivery ID
ssh -p 23231 localhost repo webhook deliveries redeliver icy 1 <delivery-id>The first attempt is logged under its X-Icy-Delivery UUID. Each retry
gets its own log entry, and its request headers show the shared
X-Icy-Delivery.
Icy refuses webhook URLs that point at private, loopback, link-local, CGNAT, or other internal addresses. This stops a repo admin from using a webhook to reach hosts inside your network. It checks the URL when the webhook is created or updated, and again for the address that it connects to on each attempt.
If your CI server is on the LAN or in a jail, list its address in
webhook.allowed_networks. Entries are CIDR prefixes or single IP
addresses:
webhook:
allowed_networks:
- "10.0.10.0/24"
- "192.168.1.20"Or use ICY_WEBHOOK_ALLOWED_NETWORKS="10.0.10.0/24,192.168.1.20".
Hostnames are not accepted in the list. A webhook URL may still use a
hostname, but only if every address it resolves to is public or in the
list. Icy connects to the address that it checked, so a DNS change after
the check cannot send the request somewhere else. Names such as
localhost are always refused, so write http://127.0.0.1:8080/ if the
receiver is on the same host. Keep the list as small as you can. Every
repo admin can send requests to anything in it.
This example runs a CI build on every push to main of a private repo
called app. The CI server is at 10.0.10.5 on the LAN.
Allow the CI server and restart Icy:
webhook:
allowed_networks:
- "10.0.10.5"Create a user for CI and give it read-only access to the repo. It can then
clone app but not push to it.
ssh -p 23231 localhost user create ci '-k "ssh-ed25519 AAAA... ci@ci"'
ssh -p 23231 localhost repo collab add app ci read-onlyAs the ci user, create an access token for cloning over HTTP:
ssh -i ~/.ssh/ci_ed25519 -p 23231 git.example.com token create 'ci clone'Store the token and a webhook secret on the CI server. Then add the webhook:
ssh -p 23231 localhost repo webhook create app http://10.0.10.5:8080/hook \
-e push --secret "$WEBHOOK_SECRET"On the CI server, a small receiver checks the signature, answers at once, and starts the build in the background. It answers before the build ends so that the attempt does not time out.
package main
import (
"encoding/json"
"io"
"net/http"
"os"
"os/exec"
)
func main() {
secret := os.Getenv("WEBHOOK_SECRET")
http.HandleFunc("/hook", func(w http.ResponseWriter, r *http.Request) {
body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
if err != nil || !validSignature(body, r.Header.Get("X-Icy-Signature"), secret) {
http.Error(w, "bad signature", http.StatusUnauthorized)
return
}
if r.Header.Get("X-Icy-Event") != "push" {
w.WriteHeader(http.StatusNoContent)
return
}
var p struct {
Ref string `json:"ref"`
After string `json:"after"`
Repository struct {
Name string `json:"name"`
} `json:"repository"`
}
if err := json.Unmarshal(body, &p); err != nil {
http.Error(w, "bad payload", http.StatusBadRequest)
return
}
if p.Ref == "refs/heads/main" {
cmd := exec.Command("./build.sh", p.Repository.Name, p.After, r.Header.Get("X-Icy-Delivery"))
cmd.Stdout, cmd.Stderr = os.Stdout, os.Stderr
if err := cmd.Start(); err == nil {
go cmd.Wait()
}
}
w.WriteHeader(http.StatusAccepted)
})
http.ListenAndServe(":8080", nil)
}validSignature is the function from the section above. build.sh clones
the exact commit that was pushed, using the token:
#!/bin/sh
set -eu
repo="$1" commit="$2" delivery="$3"
dir="/var/ci/$delivery"
# Skip a delivery that we have already built
[ -d "$dir" ] && exit 0
git clone "https://$ICY_CI_TOKEN@git.example.com/$repo.git" "$dir"
cd "$dir"
git checkout --detach "$commit"
make testThe token is in the clone URL, so do not print it in build logs. If the
build fails to start, check repo webhook deliveries list app 1 on Icy. It
shows whether the hook reached the CI server and what the CI server
answered.
Icy TUI is mainly used to browse repos over SSH. You can also use it to
browse local repositories with icy browse or running icy within a Git
repository.
ssh localhost -p 23231It's also possible to “link” to a specific repo:
ssh -p 23231 localhost -t icyYou can copy text to your clipboard over SSH. For instance, you can press c on the highlighted repo in the menu to copy the clone command 1.
The HTTP server also serves a read-only web view of your repositories. It needs no JavaScript and follows the browser's light or dark theme.
/shows the server name, owner and description, and the public repositories./<repo>shows the README, the latest commits and the clone URLs./<repo>/tree/<path>,/<repo>/logand/<repo>/refsbrowse files, history, branches and tags. Add?h=<branch, tag or commit>to look at another revision./<repo>/blob/<path>shows a file with syntax highlighting./<repo>/raw/<path>downloads it./<repo>/commit/<id>shows one commit and its diff./-/holds the server's own pages, such as sign-in.
The words tree, blob, raw, log, commit, refs and - cannot be a
segment of a new repository name, in any letter case. So org/tree and
docs/Log are refused, but org/trees and changelog are fine. This is what
lets a URL say where the repository name ends.
A repository created before this rule keeps working over SSH, git over HTTP and in the TUI. The web UI does not show it, and the server logs a warning for it at startup. Rename it to show it in the web UI.
Git requests win over web pages. A file whose path ends like a git request,
such as HEAD or info/refs, cannot be shown in the web UI.
Set web.owner and web.description in config.yaml to fill in the front
page. Set web.enabled: false, or ICY_WEB_ENABLED=false, to turn the web UI
off.
Anyone can browse what the anon-access setting lets them read. To see your
private repositories, sign in with SSH:
ssh -p 23231 localhost web login
# or go straight to a repository
ssh -p 23231 localhost web login icecreamThis prints a link. It works once and expires after five minutes. Opening it gives your browser a session cookie that lasts 24 hours and grants your read access. Use the "Sign out" button to end the session early.
The cookie is HttpOnly and SameSite=Lax. It is marked Secure when the server
uses TLS or http.public_url starts with https://. Pending sign-in links
and sessions are tied to the running server. A restart cancels unused links
and signs everyone out.
Icy supports git server-side hooks pre-receive, update,
post-update, and post-receive. This means you can define your own hooks to
run on repository push events. Hooks can be defined as a per-repository hook,
and/or global hooks that run for all repositories.
You can find per-repository hooks under the repository hooks directory.
Globs hooks can be found in your ICY_DATA_PATH directory under
hooks. Defining global hooks is useful if you want to run CI/CD for example.
Here's an example of sending a message after receiving a push event. Create an
executable file <data path>/hooks/update:
#!/bin/sh
#
# An example hook script to echo information about the push
# and send it to the client.
refname="$1"
oldrev="$2"
newrev="$3"
# Safety check
if [ -z "$GIT_DIR" ]; then
echo "Don't run this script from the command line." >&2
echo " (if you want, you could supply GIT_DIR then run" >&2
echo " $0 <ref> <oldrev> <newrev>)" >&2
exit 1
fi
if [ -z "$refname" -o -z "$oldrev" -o -z "$newrev" ]; then
echo "usage: $0 <ref> <oldrev> <newrev>" >&2
exit 1
fi
# Check types
# if $newrev is 0000...0000, it's a commit to delete a ref.
zero=$(git hash-object --stdin </dev/null | tr '[0-9a-f]' '0')
if [ "$newrev" = "$zero" ]; then
newrev_type=delete
else
newrev_type=$(git cat-file -t $newrev)
fi
echo "Hi from Icy update hook!"
echo
echo "RefName: $refname"
echo "Change Type: $newrev_type"
echo "Old SHA1: $oldrev"
echo "New SHA1: $newrev"
exit 0Now, you should get a message after pushing changes to any repository.
Unfortunately, due to a shortcoming in Go’s x/crypto/ssh package, Icy
does not currently support access via new SSH RSA keys: only the old SHA-1
ones will work.
Until we sort this out you’ll either need an SHA-1 RSA key or a key with another algorithm, e.g. Ed25519. Not sure what type of keys you have? You can check with the following:
$ find ~/.ssh/id_*.pub -exec ssh-keygen -l -f {} \;If you’re curious about the inner workings of this problem have a look at:
See contributing.
Please open an issue at https://github.com/skunkwerks/icy/issues.
Icy is a fork of Soft Serve by Charm.