[[!meta title="What is Gitano?"]]

<!-- The elevator pitch -->

Gitano is a git server
providing user separation
with ssh keys or passwords
with access rules defined in customisable ACLs
and maximally sandboxed hooks written in Lua
with this configuration stored in git repositories
for both global and per-repository configuration
with additional server-side commands for easier administration
accessible over the git, http and ssh transport protocols.

<!-- More in-depth description of features -->

# Is a git server providing user separation with ssh keys or passwords

Git servers implement the `git-{receive,upload}-pack` commands
when accessed over ssh,
handle requests to `/info/refs?service=git-{upload,receive}-pack`
when accessed over http,
and the bespoke protocol of the git transport.

Gitano implements the ssh interface by generating a `.ssh/authorized_keys` file
for all the permitted ssh keys
that runs a proxy command that determines which user the key belonged to
and whether the user is permitted to run the requested command
before running the git command.

Gitano implements the http interface by providing `gitano-smart-http.cgi`
which the system administrator configures their web server to run,
which authenticates the user based on a generated htpasswd file
then determines whether the authenticated user is permitted to run the service
before handing it off to `git-http-backend`.

Gitano implements the git interface by generating `git-daemon-export-ok` files
for every repository that the anonymous user is permitted to read.

# Access rules defined as customisable ACLs

All Gitano commands consult ACLs written in [lace][]
to determine whether the operation is permitted.

Existing git operations have ACLs applied by a hook installed by Gitano.

This allows a Gitano administrator to define rules
that permit delegation of roles to different users.

If those roles are defined by group membership
and the ability to add a user to a group is delegated
then the permission to grant permissions can also be delegated.

[lace]: https://www.gitano.org.uk/lace/

# Maximally sandboxed hooks run in Lua

In addition to installing hooks to provide ACL checking for git operations,
these hooks will also run hooks written in Lua in a [supple][] sandbox,
so it's safe to run semi-trusted code contributed by users
for purposes such as notifying web services of a repository update.

[supple]: https://www.gitano.org.uk/supple/

# Configuration stored in git for global and per-repository configuration

Gitano reads the majority of its configuration
from the master branch of the `gitano-admin.git` repository
in the set of repositories it manages access to.

For operations performed on a specific repository
it reads configuration from that repository's `refs/gitano/admin` branch.

ACLs stored in `gitano-admin.git` are supplemented from `refs/gitano/admin`
so users may add their own access restrictions.

Any hooks defined in `gitano-admin.git` (i.e. a global hook) get called
with a per-repo hook as a parameter if defined in `refs/gitano/admin`,
so the global hook may decide whether to suppress or call the per-repo hook.
If a global hook is not defined then per-repo hooks are called if defined.

Users, their ssh keys, groups and GPG keys
are only loaded from the `gitano-admin.git` repository.

By putting the configuration of Gitano in repositories managed by Gitano
it is easy to make a backup of configuration with the data
by mirroring the repository content,
configuration gains the same traceability guarantees as git history
and can be access controlled with the same mechanism as the data.

# Server side commands for easier administration

Management of git repositories isn't naturally part of the git protocol,
so commands for creating and deleting repositories need to be added
so that you don't need a shell account on the machine to manage repositories.

Additionally operations that may be performed
by making changes to the `gitano-admin.git` repository
may also be done with the command-line,
which is significantly quicker and more scriptable than pushing changes.

<!-- Gitano lets you delegate CLI interface management
     but does not parse changes to gitano-admin to see what they do
     and then run ACLs to see whether the user is permitted to do so -->