diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000..0c46512 Binary files /dev/null and b/.DS_Store differ diff --git a/CONFIGURATION_SERVER.md b/CONFIGURATION_SERVER.md new file mode 100644 index 0000000..04d5c69 --- /dev/null +++ b/CONFIGURATION_SERVER.md @@ -0,0 +1 @@ +# Configuration server diff --git a/README.md b/README.md new file mode 100644 index 0000000..ae5f156 --- /dev/null +++ b/README.md @@ -0,0 +1,249 @@ +

+ +

+

Kraken - Your cute action executor

+ +## Purpose + +The goal of this project is to easily do batch changes or queries a host of +repositories. In large organisations using multi-repository strategies, it may +be painful to change even small things, because there are so many repositories +to go through; Kraken aims to change that. + +**DISCLAIMER:** It is still early days, and the api is subject to change. + +## Features + +- uses a actions repository, where you store all your pending actions or queries + to be performed across your fleet of repositories. (See \_examples) +- Actions can both execute changes, open pull-requests or in some cases commit + directly to your preferred branch + - Actions natively use either shell, go or docker files to execute changes + (see \_examples/actions) +- Actions can also be analytical, so you can query your fleet for whatever you + would like +- Works both as a client, or as a server +- Supports SSH/https for fetching repos +- Supports GPG signing +- Supports dry-run mode for easy testing when developing your actions (enabled + by default on the cli) + +## Roadmap + +Refer to [roadmap.md](roadmap.md) + +## Installation + +Kraken comes in two modes. Client or Client -> Server. Kraken can stand alone as +a client, for smaller and less secure changes. However, for organisations, it +may be useful to use Kraken in server mode, which supports more features, and +has extra security built in. + +### Client (CLI) + +Download executable from [releases](https://github.com/kjuulh/kraken/releases) + +#### Or Use docker image + +```bash +docker run --rm kasperhermansen/krakencli:latest version +``` + +#### Or Build from source + +```bash +git clone https://github.com/kjuulh/kraken.git +cd kraken + +go build cmd/kraken/kraken.go +./kraken version +``` + +#### Or Build with cuddle + +```bash +git clone https://github.com/kjuulh/kraken.git +cd kraken + +cuddle_cli x build_cli +``` + +### Server + +We prefer to run the server directly as a docker image. + +```bash +docker pull kasperhermansen/krakenserver:latest +docker run -p 9090:80 --rm kasperhermansen/krakenserver:latest +``` + +#### Or Build from source + +```bash +git clone https://github.com/kjuulh/kraken.git +cd kraken + +go build cmd/server/server.go +./server version +``` + +#### Or Build with cuddle + +```bash +git clone https://github.com/kjuulh/kraken.git +cd kraken + +cuddle_cli x build_server +``` + +## Usage + +**DISCLAIMER:** It is still early days, and the api of the CLI is subject to +change, this provides the aim of the project, but as it is currently in flux, +there may not be as much handholding in the actual usage. + +I will focus on the client here, as the server provides the same features, +though available through the cli, but instead as configuration options (see +[CONFIGURATION_SERVER.md](CONFIGURATION_SERVER.md)) + +Kraken ships with autocomplete built in (courtesy of spf13/cobra). To add: + +- Bash: `echo 'source <(kraken completion bash)' >> ~/.bashrc` +- Zsh: `echo 'source <(kraken completion zsh)' >> ~/.zshrc` + +### Creating a new action + +Creating a new action + +```bash +git init my-actions # should only be done once +cd my-actions +kraken tmpl init write-a-readme --command +cat write-a-readme/kraken.yml + +# Output +# apiVersion: git.front.kjuulh.io/kjuulh/kraken/blob/main/schema/v1 +# name: write-a-readme +# select: +# repositories: [] +# actions: +# - type: shell +# entry: "main.sh" +``` + +Kraken also ships with yaml schema, which should help write the yaml +configuration. + +#### Add upstream repositories (victims) + +Now add a preferred repository + +``` +cat << EOF > write-a-readme/kraken.yml +apiVersion: git.front.kjuulh.io/kjuulh/kraken/blob/main/schema/v1 +name: write-a-readme +select: + providers: # new + - gitea: https://git.front.kjuulh.io # new + organisation: "kjuulh" # new +actions: + - type: shell + entry: "main.sh" +EOF +``` + +This will take all your repositories under an organisation and run the script +on. + +Another could be to use + +```bash +cat << EOF > write-a-readme/kraken.yml +apiVersion: git.front.kjuulh.io/kjuulh/kraken/blob/main/schema/v1 +name: write-a-readme +select: + repositories: #new + - git@git.front.kjuulh.io:kjuulh/kraken.git #new + - git@git.front.kjuulh.io:kjuulh/kraken-test.git #new +actions: + - type: shell + entry: "main.sh" +EOF +``` + +This will just apply to those repositories instead. Both can also be combined +for a shared effect. + +### Execute action + +To run the script use + +```bash +kraken process --path "write-a-readme" +``` + +This will cause the kraken process to automatically apply the action on the repo +and open a pr. + +### Query repositories + +Kraken can also be used to query. + +```bash +cat << EOF > write-a-readme/kraken.yml +apiVersion: git.front.kjuulh.io/kjuulh/kraken/blob/main/schema/v1 +name: write-a-readme +select: + repositories: + - git@git.front.kjuulh.io:kjuulh/kraken.git + - git@git.front.kjuulh.io:kjuulh/kraken-test.git +queries: + - type: grep + query: "# README" +EOF +``` + +Using the same command as above, will return the lines on each repo with those +criteria. Everything is run in docker, even locally, so no need to install fancy +tools. + +Do note: All actions will be run as dry-run unless `--apply` is added. This is +to help test locally, as well as not cause serious issues. The server +configuration is pretty much the same, except the command would look like so: +`kraken server process --path "write-a-readme" --apply`. Kraken will try to +infer as much as possible, but it may be needed to apply some extra flags to +specify upstream repositories and such. Kraken will also help you setup keys and +such on the first run, using `kraken setup` or `kraken server setup`. + +## Contributing + +It is still early days, and as such things are moving fast, I may not be able to +implement features, because I am focusing my energy on the API. That said PRs +are welcome, though they are at your own risk. + +### Bugs & features requests + +Please use [issues](https://github.com/kjuulh/kraken/issues) + +### Development + +We use [cuddle](https://git.front.kjuulh.io/kjuulh/cuddle) to improve ease of +use, it is however, not a requirement, and probably won't need to be used +outside core maintainers. + +Simply: + +```bash +go run cmd/kraken/kraken.go # CLI +go run cmd/server/server.go # Server +``` + +We follow the `gofmt` formatting, along with optionally but recommend `golines` + +If using cuddle + +``` +cuddle_cli x run # Run both server and client, will do a quick test sweep on the cli +cuddle_cli x watch_run # Automatically refresh both +cuddle_cli x fmt # will format the current code +``` diff --git a/assets/kraken.png b/assets/kraken.png new file mode 100644 index 0000000..9d1c499 Binary files /dev/null and b/assets/kraken.png differ diff --git a/assets/kraken.svg b/assets/kraken.svg new file mode 100644 index 0000000..8812c64 --- /dev/null +++ b/assets/kraken.svg @@ -0,0 +1,10 @@ + + + + + + + + + +