Project: Botkube (Observability and Analysis / Observability)
File: CONTRIBUTING.md

We'd love your help! Botkube is and accepts contributions via GitHub pull requests. This document outlines conventions on development workflow, commit message formatting, contact points and other resources to make it easier to get your contributions accepted. We gratefully welcome improvements to as well as to code. Follow the file to learn how to contribute to documentation. This section describes how to build and run Botkube from source code. , at least 1.18 `make` Kubernetes cluster, at least 1.21 Cloned Botkube repository Use the following command to clone it: ```sh git clone https://github.com/kubeshop/botkube.git ``` Build Botkube and create a new container image tagged as `ghcr.io/kubeshop/botkube:v9.99.9-dev`. Choose one option: Single target build for your local K8s cluster This is ideal for running Botkube on a local cluster, e.g. using or . Remember to set the `IMAGE_PLATFORM` env var to your target architecture. By default, the build targets `linux/amd64`. For example, the command below builds the `linux/arm64` target: ```sh IMAGE_PLATFORM=linux/arm64 make container-image-single docker tag ghcr.io/kubeshop/botkube:v9.99.9-dev {your_account}/botkube:v9.99.9-dev docker push {your_account}/botkube:v9.99.9-dev ``` Where `{your_account}` is Docker hub or any other registry provider account to which you can push the image. Multi-arch target builds for any K8s cluster This is ideal for running Botkube on remote clusters. When tagging your dev image take care to add your target image architecture as a suffix. For example, in the command below we added `-amd64` as our target architecture. This ensures the image will run correctly on the target K8s cluster. > Note > This command takes some time to run as it builds the images for multiple architectures. ```sh make container-image docker tag ghcr.io/kubeshop/botkube:v9.99.9-dev-amd64 {your_account}/botkube:v9.99.9-dev docker push {your_account}/botkube:v9.99.9-dev ``` Where `{your_account}` is Docker hub or any other registry provider account to which you can push the image. Install Botkube with any of communication platform configured, according to . During the Helm chart installation step, set the following flags: ```sh export IMAGE_REGISTRY="{imageRegistry}" # e.g. docker.io export IMAGEPULLPOLICY="{pullPolicy}" # e.g. Always or IfNotPresent --set image.registry=${IMAGE_REGISTRY} \ --set image.repository={your_account}/botkube \ --set image.tag=v9.99.9-dev \ --set image.pullPolicy=${IMAGEPULLPOLICY} ``` Check for default options. For faster development, you can also build and run Botkube outside K8s cluster. Build Botkube local binary: ```sh go mod download go build -o botkube-agent ./cmd/botkube-agent/ ``` Create a local configuration file to override default values. For example, set communication credentials, specify cluster name, and disable analytics: ```yaml cat <<EOF >

communications: default-group: socketSlack: enabled: true channels: default: name: random appToken: "xapp-xxxx" botToken: "xoxb-xxxx" configWatcher: enabled: false settings: clusterName: "labs" analytics: disable: true EOF ``` To learn more about configuration, visit https://docs.botkube.io/configuration/. Export paths to configuration files. The priority will be given to the last (right-most) file specified. ```sh export BOTKUBECONFIGPATHS="$(pwd)/helm/botkube/values.yaml,$(pwd)/local_config.yaml" ``` Export the path to Kubeconfig: ```sh export BOTKUBESETTINGSKUBECONFIG=/Users/$USER/.kube/config # set custom path if necessary ``` Make sure you are able to access your Kubernetes cluster: ```sh kubectl cluster-info ``` ```sh Kubernetes master is running at https://192.168.39.233:8443 CoreDNS is running at https://192.168.39.233:8443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy ... ``` Run Botkube agent binary: ```sh ./botkube-agent ``` Prerequisite Being able to start the Botkube binary locally. Steps Start fake plugins server to serve binaries from folder: ```bash go run hack/target/serve-plugins/main.go ``` > Note > If Botkube runs inside the k3d cluster, export the `PLUGINSERVERHOST=http://host.k3d.internal` environment variable. Export Botkube plugins cache directory: ```bash export BOTKUBEPLUGINSCACHEDIR="/tmp/plugins" ``` In other terminal window, run: ```bash make build-plugins-single && rm -rf $BOTKUBEPLUGINSCACHEDIR && ./botkube-agent ``` > Note > Each time you make a change to the or plugins re-run the above command. > Note > To build specific plugin binaries, use `PLUGINTARGETS`. For example `PLUGINTARGETS="kubernetes,echo" make build-plugins-single`. Before making any significant changes, please . Discussing your proposed changes ahead of time will make the contribution process smooth for everyone. Once we've discussed your changes, and you've got your code ready, make sure that the build steps mentioned above pass. Open your pull request against the branch. To learn how to do it, follow the Contribute section in the . To avoid build failures in CI, install and run: ```sh make lint-fix ``` This will run the `golangci-lint` tool to lint the Go code. Here to set up and run the e2e tests. Make sure your pull request has : Separate subject from body with a blank line Limit the subject line to 50 characters Capitalize the subject line Do not end the subject line with a period Use the imperative mood in the subject line Wrap the body at 72 characters Use the body to explain what and why instead of how Try to squash unimportant commits and rebase your changes on to the `main` branch, this will make sure we have clean log of changes. Join the Botkube-related discussion on Slack! Create your Slack account on workspace. To report bug or feature, use .