cuddle-please/docs/configuration.md
kjuulh decdf5f777
docs: add docs
Signed-off-by: kjuulh <contact@kjuulh.io>
2023-08-02 14:11:29 +02:00

81 lines
2.5 KiB
Markdown

# Configuration
`cuddle-please` requires configuration to function, it is quite flexible, and tries to help you as much as possible filling out values for you, or using sane defaults.
First of all, you can either use the `cuddle.yaml` if using `cuddle`, or `cuddle.please.yaml` if using standalone.
```yaml
# file: cuddle.yaml
please:
<contents of cuddle.please.yaml>
---
# file: cuddle.please.yaml
project:
owner: kjuulh
repository: cuddle-please
branch: main
settings:
api_url: https://git.front.kjuulh.io
```
This is all the configuration, most of these won't be needed when running in CI.
`cuddle` fetches configuration items from different sources, each level is able to override the previous layer.
1. Execution environment
2. Configuration files
3. Stdin
4. Env variables
5. Cli arguments
6. User input
Lets break each down.
### Execution environment
Execution environment, is the environment under which cuddle-please is run, if running in CI, we're able to take some variables, without requiring input from the user, or configuration values.
Right now only `drone-ci` is supported, but github actions and such, are nearly done.
#### Drone CI
Drone CI, will automatically fill out
```yaml
project:
owner: <drone>
repository: <drone>
branch: <drone>
```
This means that the only thing the user needs to configure is the `api_url` and the access `<token>`
### Configuration files
Already shown above, this allows setting hard-coded values, especially useful for the `api_url`.
### Stdin
All the configurations can be passed via. stdin
```bash
cat cuddle.please.yaml | cuddle-please release --stdin
```
### Env variables
The CLI shows which env variables are available via. `cuddle-please release --help`.
### CLI args
The CLI shows which args are available via. `cuddle-please release -h # or --help`
`-h` gives a shorthand description and `--help` provides a longer explanation of each arg.
There are some args, which are exclusive to the cli or env variables, such as `<token>`. This is because it is a secret and it shouldn't be leaked in the configuration. There are some exceptions such as `GITHUB_TOKEN` which is picked in the environment variable layer.
### Interactive (User input)
cuddle-please will determine whether or not it is running with a user interactive `stdin`, and will prompt for missing values if running locally. This is disabled without a proper tty, or if running in one of the CI execution environments by default. Otherwise `--no-interactive` can be passed to any command.