Add a basic readme (#15)
Co-authored-by: kjuulh <contact@kjuulh.io> Reviewed-on: kjuulh/kraken#15
This commit is contained in:
parent
38a657e745
commit
f6001f4e3d
1
CONFIGURATION_SERVER.md
Normal file
1
CONFIGURATION_SERVER.md
Normal file
@ -0,0 +1 @@
|
||||
# Configuration server
|
||||
249
README.md
Normal file
249
README.md
Normal 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
BIN
assets/kraken.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
10
assets/kraken.svg
Normal file
10
assets/kraken.svg
Normal 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 |
Loading…
Reference in New Issue
Block a user