= README

punyci is a smaller than tiny continuous integration (CI) tool for Git and
Podman. It runs as post-receive or post-commit hook and executes the jobs with
Podman in the background. If a job fails it sends a mail to the current user.
The container is kept alive for an hour to debug issues "live" without needing
multiple runs. To debug issues with punyci the job can also be run in the
foreground.

punyci is free software and licensed under GPL version 3 or later.


== Setup

Compile `punyci` with `go build` or `make`.

Setup `podman` for an unprivileged user. To send mails `/usr/bin/sendmail`
needs to be installed (provided by e.g. Postfix, nullmailer, etc.). Create a
bare Git repository and call `punyci post-receive` from the post-receive hook.
Alternatively, setup a regular Git repository and call `punyci post-commit`
from the post-commit hook.


== Usage

Example (post-receive):

    $ git init --bare repo.git
    $ echo 'punyci post-receive' > repo.git/hooks/post-receive
    $ chmod +x repo.git/hooks/post-receive

    # Optional, see below
    $ git -C repo.git config receive.advertisePushOptions true

    $ git clone user@example.org:repo.git
    $ cd repo
    $ cat > .punyci.toml <<EOF
    [[Jobs]]
    Image = "debian:trixie"
    Script = "exit 1"
    EOF
    $ git add .punyci.toml
    $ git commit -m punyci
    $ git push
    [...]
    remote: 2026/02/22 14:24:52 punyci: queued 1 jobs

This will create an email reporting the failure of the job. It's send to the
current user the CI is running as (adapt with `~/.forward` or similar). The
container continues to run for an hour. To debug the issue simply run `podman
exec -it $uuid-from-email sh` on the host where the CI is running.

If a job succeeds then no mail is generated. The only exception is if the
previous run of the job failed. Then a "fixed" mail is generated. Failed jobs
are marked with an empty file `punyci-failed-$job` in the bare repository.

The build log of the last job is stored in `punyci-log-$job` in the bare
repository. It's written "live" during the run and can be used with `tail -f`
to watch the output during the run.

To run the CI in the foreground use `git push -o wait`. This needs the option
`receive.advertisePushOptions = true` in the remote repository. If a job fails
the command will hang until the timeout. Simply press Ctrl-C or kill the
containers manually.

Example (post-commit):

    $ git init repo
    $ echo 'punyci post-commit' > repo/.git/hooks/post-commit
    $ chmod +x repo/.git/hooks/post-commit

    $ cd repo
    $ cat > .punyci.toml <<EOF
    [[Jobs]]
    Image = "debian:trixie"
    Script = "exit 1"
    EOF
    $ git add .punyci.toml
    $ git commit -m punyci
    2026/02/26 06:41:15 punyci: queued 1 jobs
    [...]

The behavior is the same as above. To run the CI in the foreground use
`PUNYCI=wait git commit`.


== Configuration

punyci is configured through `.punyci.toml` in the top-level of the
repository.

    [[Jobs]]
    Image = "golang:1.26"
    Script = "./ci/run"

    [[Jobs]]
    Image = "golang:1.25"
    Script = "./ci/run"
    Cache = true

An unlimited number of jobs can be configured. They are run in sequence. A
failing job doesn't stop the following jobs from starting.

`Script` can be an arbitrary script (multiple lines with TOML's `"""`
strings). If no shebang is present then `#!/bin/sh` is prepended. Otherwise
the existing shebang is used.

`Cache` can be used to configure a persistent cache for each job. The cache is
mounted in the container at `/punyci-cache` and must be manually used. For
example by symlinking into it (e.g. `ln -s /punyci-cache /root/.cache`) at the
beginning of the CI script. The cache is stored as `punyci-cache-$job` in the
(bare) repository.


== Architecture

=== Execution

For each job the following steps are executed:

- Clone the repository
- Start given image as detached container in Podman which waits forever,
  mounting the repository and cache (optional)
- Execute the script to run the CI job
  . If the CI runs in the foreground write the output to stdout/stderr
  . Otherwise write it to the log file
- If the script exits with a non-zero exit code wait for the container to
  exit with a timeout of one hour
- Kill the container
- Send email if running in the background and the job either failed or was
  fixed

=== Container

The following files and directories are mounted in the container:

- `/punyci-cache/`: persistent cache for this job, only if `Cache` is true
- `/punyci-repo/`: clone of the repository, separate for each job
- `/punyci-script`: configured `Script` of the job (read-only); executed with
  `/punyci-repo/` as working directory

=== Repository

The following files and directories are stored in the Git repository (either
in the bare repository itself or in `.git` for non-bare repositories); `$job`
is the index of the job (starting from zero):

- `punyci-cache-$job/`: persistent cache
- `punyci-log-$job`: log of the last run of this job
- `punyci-failed-$job`: empty file created if the last job failed, used to
  report "fixed" jobs (gets deleted when a job is fixed)


== Licenses

punyci is licensed under GPL 3 or later.

Copyright (C) 2026  Simon Ruderich

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.