Skip to content

docs: rewrite README and add usage, configuration, contributing guides #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Jaydee94 merged 1 commit into from
May 22, 2026
Merged

docs: rewrite README and add usage, configuration, contributing guides #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 85 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# Contributing to ChartScan

Thanks for taking the time to contribute. This document walks you through everything you need to develop, test, and submit changes.

## Prerequisites

- **Go 1.26** or newer (declared in [`go.mod`](go.mod)).
- **Helm** on your `PATH`. ChartScan shells out to `helm lint`, `helm template`, and `helm dependency update` and the test suite assumes Helm is available.
- **Git**, for cloning and for ChartScan's auto-discovery feature.

## Repository layout

```
chartscan/
├── cmd/chartscan/ # CLI entry point — Cobra commands wired in main.go.
├── internal/
│ ├── finder/ # Recursive discovery of Helm charts via Chart.yaml.
│ ├── models/ # Result, Config, TestSuite data structures.
│ └── renderer/ # Linting, templating, value-reference checking.
├── pkg/utils/ # Shared utilities (logger).
├── mock/ # Sample charts (valid + invalid) used by tests and smoke runs.
├── demo/ # Demo chart and the README gif.
├── docs/ # User documentation (usage, configuration).
└── .github/workflows/ # CI: go-test on every PR, go-build on release.
```

## Local development

Install dependencies and run the CLI:

```bash
go mod tidy
go run ./cmd/chartscan scan mock/charts
```

Build a binary:

```bash
go build -o chartscan ./cmd/chartscan
./chartscan version
```

## Testing

Run the full unit test suite:

```bash
go test ./...
```

The repo also ships a [`test.sh`](test.sh) helper that runs `go fmt`, `go vet`, `go test`, and a smoke `scan` against `mock/charts`. Note that `test.sh` currently hard-codes a developer-specific `GOROOT` near the top of the file — adjust the `export` lines for your machine, or just run the underlying commands directly:

```bash
go fmt ./...
go vet ./...
go test ./...
go run ./cmd/chartscan scan mock/charts
```

## Continuous integration

Two GitHub Actions workflows live in [`.github/workflows/`](.github/workflows):

- **`go-test.yml`** — runs `go vet` and `go test -v ./...` on every pull request and push to `main`. Uses Go 1.26.
- **`go-build.yml`** — runs when a release is created. Builds `linux/amd64`, `linux/arm64`, and `linux/386` binaries with the release tag injected as the version, and attaches them as release assets.

Your PR must pass `go-test` before it can be merged.

## Submitting a pull request

1. Fork the repository.
2. Create a feature branch: `git checkout -b my-feature`.
3. Make your changes. Keep commits focused and write descriptive messages.
4. Run `go fmt ./... && go vet ./... && go test ./...` and make sure everything passes.
5. Update the user-facing docs in [`docs/`](docs) or [`README.md`](README.md) if you changed CLI behavior, flags, or configuration syntax.
6. Push the branch: `git push origin my-feature`.
7. Open a pull request against `main` and describe what changed and why.

## Reporting bugs

Open an issue on [GitHub](https://github.com/Jaydee94/chartscan/issues) with:

- The ChartScan version (`chartscan version`) and Helm version (`helm version`).
- The exact command you ran.
- The full output, plus the chart or a minimal reproducer if possible.
198 changes: 49 additions & 149 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,209 +1,109 @@
# ChartScan

![Latest Release](https://img.shields.io/github/release/Jaydee94/chartscan.svg)
[![Latest Release](https://img.shields.io/github/release/Jaydee94/chartscan.svg)](https://github.com/Jaydee94/chartscan/releases)
[![Build](https://github.com/Jaydee94/chartscan/actions/workflows/go-build.yml/badge.svg)](https://github.com/Jaydee94/chartscan/actions/workflows/go-build.yml)
[![Tests](https://github.com/Jaydee94/chartscan/actions/workflows/go-test.yml/badge.svg)](https://github.com/Jaydee94/chartscan/actions/workflows/go-test.yml)
![Built with Go](https://img.shields.io/badge/built%20with-Go-00ADD8.svg)
![License](https://img.shields.io/github/license/Jaydee94/chartscan.svg)
[![License](https://img.shields.io/github/license/Jaydee94/chartscan.svg)](LICENSE)
![Stars](https://img.shields.io/github/stars/Jaydee94/chartscan.svg)

**ChartScan** is a CLI tool for scanning and analyzing Helm charts. It provides insights into Helm chart configurations, values, and rendering issues, allowing developers to efficiently debug and validate Helm charts before deployment.
**ChartScan** is a command-line tool for validating Helm charts before they ship. It walks a directory, finds every chart, renders the templates with the values you give it, and reports anything that fails to lint, fails to render, or references a value that is not defined.

<img src="logo/chartscan_icon.png" alt="drawing" width="300"/>
<img src="logo/chartscan_icon.png" alt="ChartScan logo" width="240"/>

---

## Features

- Scans directories for Helm charts.
- Supports multiple values files for rendering charts.
- Configurable output formats: **pretty**, **JSON**, **JUnit**, or **YAML**.
- Supports configuration through YAML-based config files.
- Recursively discovers Helm charts under any directory.
- Renders charts with one or more values files and `--set` overrides.
- Detects undefined `.Values` references in templates.
- Four output formats: `pretty`, `json`, `yaml`, `junit`.
- YAML configuration with named environments (`test`, `staging`, `production`, …).
- Automatically loads `chartscan.yaml` from the root of the current Git repository.
- Renders charts to stdout or to a file via `chartscan template`.

---

## Installation

### Precompiled Binaries
### Precompiled binary

For convenience, precompiled binaries are available for the latest releases of **ChartScan**. These binaries are built for multiple architectures and can be directly downloaded from the **Releases** page on GitHub.
Download the binary for your platform from the [Releases page](https://github.com/Jaydee94/chartscan/releases):

To download the latest release:
| Platform | Asset |
|-----------------|----------------------|
| Linux x86_64 | `chartscan-amd64` |
| Linux ARM64 | `chartscan-arm64` |
| Linux x86 (32) | `chartscan-386` |

1. Go to the [ChartScan Releases Page](https://github.com/Jaydee94/chartscan/releases).
2. Download the appropriate binary for your system:
- **Linux amd64**: `chartscan-amd64`
- **Linux arm64**: `chartscan-arm64`
- **Linux 386**: `chartscan-386`
3. (Optional) Move the binary to a directory in your system's `PATH`:

```bash
mv chartscan-[architecture] /usr/local/bin/chartscan
```

---

## Prerequisites

Ensure the following dependencies are installed:

- **Helm**: [Install Helm](https://helm.sh/docs/intro/install/)

---

## Usage

### Demo

![demo](demo/chartscan.gif)

### Commands

#### Scan Command

The `scan` command is used to analyze Helm charts for potential issues:
Move it into your `PATH`:

```bash
chartscan scan [chart-path]
chmod +x chartscan-amd64
sudo mv chartscan-amd64 /usr/local/bin/chartscan
```

### Options for `scan`

- `-f, --values`: Specify values files to use for rendering.
- `-o, --format`: Set the output format (pretty, json, yaml, junit). Default is `pretty`.
- `-c, --config`: Provide a configuration file (YAML format) to override CLI flags.
- `-e, --environment`: (Optional) Specify the environment to use (e.g., test, staging, production). This will load preconfigured values files for the specified environment in chartscan.yaml.

#### Template Command

The `template` command is used to render Helm charts with helm template:
### From source

```bash
chartscan template [chart-path]
go install github.com/Jaydee94/chartscan/cmd/chartscan@latest
```

### Options for `template`
Requires Go 1.26 or newer (see [go.mod](go.mod)).

- `-f, --values`: Specify values files to use for rendering.
- `-o, --format`: Specify an output file to write the rendered chart (optional).
- `-c, --config`: Provide a configuration file (YAML format) to override CLI flags.
- `-e, --environment`: (Optional) Specify the environment to use (e.g., test, staging, production). This will load preconfigured values files for the specified environment in chartscan.yaml.
---

#### Version Command
## Prerequisites

The `version` command displays the current version of ChartScan:
- [Helm](https://helm.sh/docs/intro/install/) on your `PATH`. ChartScan shells out to `helm lint`, `helm template` and `helm dependency update`.

```bash
chartscan version
```
---

### Examples
## Quickstart

#### Scan a Chart Directory with Values Files
Scan a single chart:

```bash
chartscan scan ./charts -f values.yaml -o json
chartscan scan ./charts/my-chart -f values.yaml
```

#### Use a Config File
Scan every chart under a directory and emit JUnit for CI:

```bash
chartscan scan -c config.yaml
```

#### Example Config File

```yaml
chartPath: ./charts
valuesFiles:
- values.yaml
format: yaml
environments:
test:
valuesFiles:
- values-test.yaml
- values-2-test.yaml
staging:
valuesFiles:
- values-staging.yaml
production:
valuesFiles:
- values-production.yaml
chartscan scan ./charts -o junit > report.xml
```

---

## Automatic Config File Loading in Git Repositories
Render a chart with `helm template`:

When you run ChartScan inside a Git repository, the tool will automatically search for and load a configuration file located in the root directory of the repository. This behavior eliminates the need to manually specify the config file with the -c option if you already have one in your repository.

How It Works
ChartScan looks for a file named chartscan.yaml in the root directory of the repository.
If the config file is found, ChartScan will automatically load it and use its settings, including chart paths, values files, output format, and more.

This behavior simplifies configuration management, especially for projects with shared settings across team members.
Example: Automatic Config Loading
For example, if your Git repository has the following directory structure:

```
my-repo/
├── chartscan.yaml
├── charts/
│ └── my-chart/
├── values.yaml
└── README.md
```bash
chartscan template ./charts/my-chart -f values.yaml -o rendered.yaml
```

When you run (inside a git repo with a chartscan.yaml in the root directory):
Use a config file:

```bash
chartscan scan ./charts
chartscan scan -c chartscan.yaml
```

ChartScan will automatically detect and use chartscan.yaml for its configuration.
When you run ChartScan inside a Git repository that has a `chartscan.yaml` at its root, the file is picked up automatically — no `-c` needed.

---

## Output Formats
## Demo

- **Pretty**: Human-readable formatted output.
- **JSON**: Machine-readable JSON format.
- **YAML**: YAML-encoded output for further processing.
- **JUnit**: JUnit-compatible XML format for test reports.
![ChartScan demo](demo/chartscan.gif)

---

## Development
## Documentation

### Running Locally

1. Clone the repository.
2. Install dependencies:

```bash
go mod tidy
```

3. Run the tool:

```bash
go run ./cmd/chartscan [command] [options]
```

### Testing

Run the test suite:

```bash
go test ./...
```
- [Usage reference](docs/usage.md) — every command, flag, and example.
- [Configuration](docs/configuration.md) — `chartscan.yaml` schema, environments, auto-discovery.
- [Contributing](CONTRIBUTING.md) — local setup, tests, PR workflow.

---

## Contribution

Contributions are welcome! Please follow these steps:
## License

1. Fork the repository.
2. Create a feature branch (`git checkout -b feature-name`).
3. Commit your changes (`git commit -m "Add feature"`).
4. Push to the branch (`git push origin feature-name`).
5. Open a pull request.
Released under the terms of the [LICENSE](LICENSE) file in this repository.
Loading
Loading