added readme
This commit is contained in:
parent
a3e770a19f
commit
1e793d3248
GPG Key ID:
57B6E1465221F912
1
CONFIGURATION_SERVER.md
Normal file
1
CONFIGURATION_SERVER.md
Normal file
@ -0,0 +1 @@
|
||||
# Configuration server
|
||||
245
README.md
245
README.md
@ -2,3 +2,248 @@
|
||||
<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
|
||||
```
|
||||
|
||||
Loading…
Reference in New Issue
Block a user