Add a basic readme #15

Merged
kjuulh merged 10 commits from feature/write-a-readme into v0.2 2022-09-18 21:07:08 +02:00
5 changed files with 260 additions and 0 deletions

BIN
.DS_Store vendored Normal file

Binary file not shown.

1
CONFIGURATION_SERVER.md Normal file
View File

@ -0,0 +1 @@
# Configuration server

249
README.md Normal file
View File

@ -0,0 +1,249 @@
<p align="center">
<image src="https://git.front.kjuulh.io/kjuulh/kraken/raw/branch/feature/write-a-readme/assets/kraken.svg" width="300" height="300"/>
</p>
<h1 align="center">Kraken - Your cute action executor</h1>
## 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
```

BIN
assets/kraken.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 32 KiB

10
assets/kraken.svg Normal file
View File

@ -0,0 +1,10 @@
<svg width="1000" height="1000" viewBox="0 0 1000 1000" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M975 568C975 830.335 762.335 497 500 497C237.665 497 25 830.335 25 568C25 305.665 237.665 93 500 93C762.335 93 975 305.665 975 568Z" fill="#52DB78"/>
<path d="M237.436 856.185C165.693 827.571 320.875 755.464 377.754 612.854C434.634 470.243 371.672 311.132 443.414 339.746C515.157 368.36 527.205 507.165 470.326 649.776C413.446 792.386 309.178 884.799 237.436 856.185Z" fill="#52DB78"/>
<path d="M428.353 849.847C353.918 829.229 500.308 740.627 541.293 592.663C582.278 444.699 502.337 293.405 576.773 314.023C651.208 334.641 678.325 471.303 637.34 619.267C596.355 767.231 502.788 870.465 428.353 849.847Z" fill="#52DB78"/>
<path d="M598.707 855.902C523.231 839.498 664.415 742.813 697.024 592.781C729.634 442.748 641.321 296.183 716.797 312.588C792.272 328.992 827.022 463.916 794.413 613.948C761.803 763.98 674.183 872.307 598.707 855.902Z" fill="#52DB78"/>
<path d="M47.896 838.855C-19.3259 800.817 144.17 750.323 219.784 616.698C295.397 483.073 254.495 316.918 321.717 354.956C388.938 392.994 382.136 532.155 306.522 665.78C230.909 799.405 115.118 876.893 47.896 838.855Z" fill="#52DB78"/>
<ellipse cx="605.35" cy="265.255" rx="57.5" ry="36.5" transform="rotate(-40.9544 605.35 265.255)" fill="white"/>
<ellipse cx="359.35" cy="265.255" rx="57.5" ry="36.5" transform="rotate(-40.9544 359.35 265.255)" fill="white"/>
<path d="M385.635 374C385.635 374 391.199 435.298 463.528 438.425C535.857 441.553 538.492 380.61 538.492 380.61" stroke="white" stroke-width="8"/>
</svg>

After

Width:  |  Height:  |  Size: 1.5 KiB