Metadata-Version: 2.4
Name: forgejo-lxd-runner
Version: 0.1.0
Summary: Forgejo Runner act backend plugin that executes jobs in LXD instances
Author: vicamo
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://kernel.ubuntu.com/forgejo/vicamo/forgejo-lxd-runner
Keywords: forgejo,runner,lxd,act,plugin,grpc
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: grpcio>=1.51.1
Requires-Dist: grpcio-health-checking>=1.51.1
Requires-Dist: httpx>=0.27
Requires-Dist: protobuf>=4.21.12
Requires-Dist: websockets>=12
Provides-Extra: metrics
Requires-Dist: prometheus-client>=0.20; extra == "metrics"
Provides-Extra: dev
Requires-Dist: grpcio-tools>=1.51.1; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: grpc-stubs>=1.53; extra == "dev"
Requires-Dist: types-protobuf>=4.24; extra == "dev"
Requires-Dist: nox>=2024.4.15; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Requires-Dist: types-pyyaml>=6.0; extra == "dev"
Requires-Dist: prometheus-client>=0.20; extra == "dev"
Dynamic: license-file

# forgejo-lxd-runner

[![ci](https://github.com/vicamo/forgejo-lxd-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/vicamo/forgejo-lxd-runner/actions/workflows/ci.yml)

A [Forgejo Runner](https://code.forgejo.org/forgejo/runner) act backend plugin
that runs CI jobs inside [LXD](https://linuxcontainers.org/lxd/) instances.

It implements the experimental `plugin.v1alpha.BackendPlugin` gRPC service
introduced in Forgejo Runner [v13.1.0](https://forgejo.org/2026-09-runner-release-v131/), so the runner can drive the LXD instance
lifecycle (`Create` / `Start` / `Exec` / `CopyIn` / `CopyOut` / `Remove`) over
a Unix or TCP socket.

## Status

Alpha — the upstream plugin protocol itself is `v1alpha` and may change in
incompatible ways between runner releases.

## Install

```sh
pip install .
# or, for development:
pip install -e '.[dev]'
```

## Generate the gRPC stubs

The `.proto` file is vendored in `proto/plugin/v1alpha/plugin.proto` from
Forgejo Runner v13.1.0. Regenerate the Python bindings with:

```sh
nox -s proto
```

## Development

```sh
pipx install nox   # or: pip install nox

nox                # lint + type + tests on the current interpreter
nox -s lint        # ruff check + format --check
nox -s fmt         # ruff check --fix + format (writes changes)
nox -s type        # mypy
nox -s tests       # pytest
nox -s tests-3.12  # pytest on a specific Python version
nox -s e2e         # pytest against a live LXD or Incus daemon
nox -l             # list all sessions
```

## Run

```sh
forgejo-lxd-runner --address unix:///run/forgejo-lxd-runner.sock
```

Then point the runner at it via its plugin configuration. See
[`docs/usage.md`](docs/usage.md) for every command-line flag, the per-label
backend options, and the systemd deployment walkthrough.

## Layout

```
proto/                  vendored .proto files
src/forgejo_lxd_runner/  package sources
  proto/                 generated gRPC stubs (git-ignored)
  client.py              minimal REST client for the LXD / Incus ``/1.0`` API
  executor.py            job instance execution context
  health.py              health-check gRPC service reflecting LXD reachability
  metrics.py             opt-in Prometheus metrics endpoint and RPC interceptor
  server.py              BackendPlugin service implementation
  __main__.py            CLI entry point
tests/                   pytest suite
```

## License

GPL-3.0-or-later. The vendored `.proto` file is MIT-licensed by its upstream
authors.
