Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/belak/gitdir
PoC of a self-contained, simple, and lightweight SSH git hosting with just a directory.
https://github.com/belak/gitdir
git golang ssh
Last synced: 25 days ago
JSON representation
PoC of a self-contained, simple, and lightweight SSH git hosting with just a directory.
- Host: GitHub
- URL: https://github.com/belak/gitdir
- Owner: belak
- License: mit
- Created: 2019-10-17T00:05:06.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-04-19T13:20:32.000Z (10 months ago)
- Last Synced: 2024-10-19T05:51:31.274Z (4 months ago)
- Topics: git, golang, ssh
- Language: Go
- Homepage:
- Size: 181 KB
- Stars: 182
- Watchers: 6
- Forks: 3
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# go-gitdir
[](https://goreportcard.com/report/github.com/belak/go-gitdir)
[](https://github.com/belak/gitdir/actions/workflows/test.yml)
This project makes it incredibly easy to host a secure git server with a config
that can be easily rolled back.
It aims to solve a number of problems other git servers have:
- Requires no external dependencies other than the binary and git
- Stores its configuration in a repo managed by itself
- Doesn't hook into the system's user accounts
- No vendor lock-in - everything is just a bare git repository
## Origins
The main goal of this project is to enable simple git hosting when a full
solution like Bitbucket, Github, Gitlab, Gitea, etc is not needed.
This project was inspired by gitolite and gitosis, but also includes a built-in
ssh server and some additional flexability. It is not considered stable, but
should be usable enough to experiment with.
Thankfully because all the repos are simply stored as bare git repositories, it
should be fairly simple to migrate to or from other git hosting solutions. There
is no vendor lock-in.
## Requirements
Build requirements:
- Go >= 1.13
Runtime requirements:
- git (for git-receive-pack and git-upload-pack)
## Building
Clone the repository somewhere, outside the GOPATH. Then, from the root of the
source tree, run:
```
go build ./cmd/gitdir
```
This will create a binary called `gitdir`.
## Running
### Server Config
There are a number of environment variables which can be used to configure your
go-git-dir instance.
The following are required:
- `GITDIR_BASE_DIR` - A directory to store all repositories in. This folder must
exist when the service starts up.
The following are optional:
- `GITDIR_BIND_ADDR` - The address and port to bind the service to. This
defaults to `:2222`.
- `GITDIR_LOG_READABLE` - A true value if the log should be human readable
- `GITDIR_LOG_DEBUG` - A true value if debug logging should be enabled
- `GITDIR_ADMIN_USER` - The name of an admin user which the server will ensure
exists on startup.
- `GITHUB_ADMIN_PUBLIC_KEY` - The contents of a public key which will be added
to the admin user on startup.
### Runtime Config
The runtime config is stored in the "admin" repository. It can be cloned and
modified by any admin on the server. In it you can specify groups (groupings of
users for config or convenience reasons), repos, and orgs (groupings of repos
managed by a person).
Additionally, there are a number of options that can be specified in this file
which change the behavior of the server.
- `implicit_repos` - allows a user with admin access to that area to create
repos by simply pushing to them.
- `user_config_keys` - allows users to specify ssh keys in their own config,
rather than relying on the main admin config.
- `user_config_repos` - allows users to specify repos in their own config,
rather than relying on the main admin config.
- `org_config_repos` - allows org admins to specify repos in their own config,
rather than relying on the main admin config.
## Usage
Simply run the built binary with `GITDIR_BASE_DIR` set and start using it!
On first run, gitdir will push a commit to the admin repo with a sample
config as well as generated server ssh keys. These can be updated at any time
(even at runtime) but if the server restarts and the keys cannot be loaded, they
will be re-generated.
If you set `GITDIR_ADMIN_USER` and `GITHUB_ADMIN_PUBLIC_KEY` an admin user will
automatically be added to the config.
If you do not set those environment variables, you will need to manually clone
the admin repository (at `$GITDIR_BASE_DIR/admin/admin`) to add a user to
`config.yml` and set them as an admin.
## Sample Config
Sample admin `config.yml`:
```
users:
belak:
is_admin: true
keys:
- ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDeQfBUWIqpGXS8xCOg/0RKVOGTnzpIdL7r9wK1/xA52 belak@tmp
repos:
personal-gitdir: {}
groups:
admins:
- belak
repos:
go-gitdir:
public: true
write:
- $admins
read:
- some-other-user
orgs:
vault:
admins:
- $admins
write:
- some-org-user
read:
- some-other-org-user
repos:
the-vault:
write:
- some-repo-access-user
options:
implicit_repos: false
user_config_keys: true
user_config_repos: false
org_config_repos: false
```
## Repo Creation
All repos defined in the config are created when the config is loaded. At
runtime, if implicit repos are enabled, trying to access a repo where you have
admin access will implicitly create it.