https://github.com/bmc-labs/runrs
Manage GitLab Runners in Docker via REST
https://github.com/bmc-labs/runrs
Last synced: 3 months ago
JSON representation
Manage GitLab Runners in Docker via REST
- Host: GitHub
- URL: https://github.com/bmc-labs/runrs
- Owner: bmc-labs
- License: apache-2.0
- Created: 2024-02-04T01:49:32.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-11-09T23:10:20.000Z (6 months ago)
- Last Synced: 2025-01-31T12:51:21.409Z (4 months ago)
- Language: Rust
- Size: 392 KB
- Stars: 5
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# `🏃🏽 runrs`
**Manage GitLab Runners in Docker via REST**
If you're running GitLab runners in Docker and you're looking for a simple, non-manual way of doing
so, runrs has you covered. You can run runrs in your Docker alongside the GitLab Runners control
service - it just needs access to the configuration file containing Runner configs and things will
_just work™_.
## Motivation
Running GitLab Runners in Docker is simple, but managing them - adding new ones, cleaning up,
rotating them - is an annoying manual task. If you're anything like us, you don't like those.
Moreover, it's something we don't do _that often_ - a few times per month perhaps - so we end up
looking up the manual steps in the GitLab docs every godforsaken time. Meanwhile, pretty much
everything else we run is Terraformed, which makes this doubl-y annoying.
Thus, we wrote this simple service which provides a CRUD API for GitLab Runner configurations and
can run in Docker, managing the Runners configuration file. We also have [a Terraform
provider](https://github.com/bmc-labs/terraform-provider-peripheral) you can use to _GitLab Runner
Setup as Code_ your Runners.
## Using runrs in prod
We don't recommend you do (just yet). If you insist: use the Docker container we provide, and make
sure it has access to the GitLab Runner configuration file. You do so by passing the path to it via
the `CONFIG_PATH` environment variable.
If you want to persist the SQLite database (e.g. because you want your runner setup to survive
reboots, or because you're running several replicas of `runrs` for some reason), you can pass it any
URL that SQLite would understand - most commonly a path to a file on disk - via the `DATABASE_URL`
environment variable.
## Local Development Setup
It's a vanilla Rust and `cargo` project, so if you have a recent (1.75+) Rust toolchain installed,
you should be good. For testing end to end, you'll need:
- Docker, which is going to be used as the executor for your runners, up and running, and
- [Docker Compose](https://docs.docker.com/compose/install/)
It's _also_ a nixified project using a flake, so if you prefer to use that to build it, you can.
Look at the `flake.nix` for current package targets. In that vein: there is also a
[`direnv`](https://direnv.net/) setup in the project, so if you have that installed, you can just
`direnv allow` in the project root and you'll have the setup done.
### Setup
1. Clone the thing.
```bash
git clone [email protected]:bmc-labs/runrs.git
cd runrs
```
1. Use Docker Compose to run the `gitlab-runner` service with correct setup in Docker.
```bash
docker compose up -d
```
1. Build and run the thing.
```bash
cargo run
```
Similarly, testing is via `cargo test`, as you might have expected.
If you are building with nix, you can use the `nix` command to build the project:
```bash
# to build the default target, which is the "runrs" binary:
nix build
# to build the Docker image:
nix build .#runrs-docker-image
# after building the Docker image, you need to load it:
docker load < result
```
That's it. Make a PR with your changes and we'll talk about them.
## Support
This is an open source project, so there isn't support per se. If you open an issue in the
repository, we'll try and help you, but no promises.
## License
Licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
### Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the
work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
additional terms or conditions.
---
© Copyright 2024 bmc::labs GmbH. All rights reserved.
solid engineering. sustainable code.