docs: added readme

This commit is contained in:
əlemi 2024-02-13 17:16:57 +01:00
parent 3f95b8b733
commit 7f9ec06586
Signed by: alemi
GPG key ID: A4895B84D311642C

63
README.md Normal file
View file

@ -0,0 +1,63 @@
# tci
> tiny custom CI runner for your selfhosted just-git repositories
## why
continuous integration is really convenient when you have quite some tiny projects which you'd like to keep updated.
this one has its doc page, that one compiles to a minified js file that i should serve, this one has a demo instance that i should restart...
i don't want to bother doing these things every time i write some fixes!
also, i really like the idea of keeping CI configuration committed with the repository itself
## how
git natively supports [hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks). they are extremely convenient and pleasant to use (just a shell script!), but aren't version-controlled in the repository they belong to.
i use them on my client to validate my commits and sometimes configure/cleanup projects
because i self-host my git repositories (did you know you just need to `git init --bare <name>` in your home and you can pull/push from there! `git clone <user>@<host>:<repo-path>` just works), i can't just use github/gitlab, and would rather not go mad configuring jenkins
most of my CIs are super simple: `cargo doc; cp * /srv/http/docs/`, configuring something complex like jenkins seems overkill
# introducing tci!
`tci` is a Tiny CI runner
just set it as `post-update` hook in your repository and, each time such repository gets updated, tci will:
* make sure repo is allowed to run CI: checks said repo git config for `tci.allow == true`
* create a temp dir (under `/tmp`) with unique name
* clone your repository in that dir
* change current working directory to be inside your freshly cloned repo
* run `.tci` script (you can change it by setting git config `tci.script`)
* print script's `STDOUT` to console
* delete temporary directory
and that's it! could not be simpler
# using tci
a very simple example: i'd like to auto-update cargo documentation for my project
first step is enabling tci for such repo: `git config tci.allow true` on my server
then i can just add a `.tci` script in the project root:
```
#!/bin/bash
cargo doc
rm -rf /srv/http/docs/*
cp ./build/* /srv/http/docs/
```
just commit and push!
### setting tci as default runner for every repository
configuring tci as post-update hook for *each repository* is definitely annoying
luckily, git allows us to configure a default hook location valid for every repository!
inside your `~/.gitconfig` just insert:
```
[core]
hooksPath = /path/to/some/directory/
```
inside such directory, place `tci` and rename it to `post-update`
and done! should enable tci for all repos (if they are configured to allow it)