acid/acid.adoc

acid(1)
=======
:doctype: manpage
:manmanual: acid Manual
:mansource: acid {release-version}

Name
----
acid - A Continuous Integration Daemon

Synopsis
--------
*acid* [_OPTION_]... acid.yaml [_COMMAND_...]

Description
-----------
*acid* run without command arguments will start an HTTP server that creates
and executes tasks against *git*(1) commits from a particular Gitea instance,
in accordance with the passed configuration file.

When a command is passed, *acid* will relay it to that running instance
of itself as an RPC call.

Tasks can be triggered to run either upon receiving Gitea push events
on the */push* endpoint, and/or using the RPC commands.

Options
-------
*-version*::
	Output version information and exit.

Commands
--------
*enqueue* _OWNER_ _REPO_ _REF_ [_RUNNER_]...::
	Create new or restart existing tasks for the given reference,
	which will be resolved to a full commit hash.
*restart* [_ID_]...::
	Schedule tasks with the given IDs to be rerun.
	Run this command without arguments to pick up external database changes.
*reload*::
	Reload configuration.

Configuration
-------------
For help with creating the configuration file, consult the _acid.yaml.example_
file present in the distribution.

All paths are currently relative to the directory you launch *acid* from.

The *notify*, *setup*, *build*, and *deploy* scripts are processed using Go's
_text/template_ package, and take an object describing the task,
which has the following fields:

*ID*::
	Unique integer ID for each task.

*Owner*::
	Gitea user owning the repository.
*Repo*::
	Name of the repository.
*FullName*::
	Full name of the repository, including the owner.
*Hash*::
	Commit hash pertaining to the task.
*Runner*::
	Runner ID.
*RunnerName*::
	Descriptive name of the runner.

// Intentionally not documenting CreatedUnix, ChangedUnix, DurationSeconds,
// which can be derived from the objects.
*Created*, *Changed*::
	`*time.Time` of task creation and last task state change respectively,
	or nil if not known.
*CreatedAgo*, *ChangedAgo*::
	Abbreviated human-friendly relative elapsed time duration
	since *Created* and *Changed* respectively.
*Duration*::
	`*time.Duration` of the last run in seconds, or nil if not known.

*URL*::
	*acid* link to the task, where its log output can be seen.
*RepoURL*::
	Gitea link to the repository.
*CommitURL*::
	Gitea link to the commit.
*CloneURL*::
	Gitea link for cloning the repository over HTTP.

The special *quote* template function quotes fields for safe usage
in *sh*(1) command arguments.

Runners
-------
Runners and deploy scripts receive the following additional
environment variables:

*ACID_ROOT*::   The same as the base directory for configuration.
*ACID_RUNNER*:: The same as *Runner* in script templates.

Reporting bugs
--------------
Use https://git.janouch.name/p/acid to report bugs, request features,
or submit pull requests.

See also
--------
*git*(1), *sh*(1)