tci/README.md

# 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`
 * make sure the branch being updated is `tci` (customizable in server settings)
 * 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 (customizable in repo settings)
 * print script's `stdout` and `stderr` 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 mark it executable, 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)

### making a git alias to quickly merge and push on tci branch
just run

```sh
git config --global alias.tci '!func(){ BRANCH=\"$1\"; REMOTE=\"origin\"; if [ -n \"$2\" ]; then REMOTE=\"$2\"; fi; git checkout tci && git pull $REMOTE tci && git merge $BRANCH && git push $REMOTE tci; git checkout $BRANCH; }; func"'

```

it will add a `git tci <branch>` alias, which you can use to quickly checkout, pull, merge and push on tci branch