https://github.com/yuseferi/envyaml
env Yaml is a configuration loader from Yaml file with enviromental variable that helps to have secret placeholders in yaml file.
https://github.com/yuseferi/envyaml
Last synced: about 2 months ago
JSON representation
env Yaml is a configuration loader from Yaml file with enviromental variable that helps to have secret placeholders in yaml file.
- Host: GitHub
- URL: https://github.com/yuseferi/envyaml
- Owner: yuseferi
- License: gpl-3.0
- Created: 2024-09-18T14:36:39.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-12-25T22:48:40.000Z (3 months ago)
- Last Synced: 2025-12-27T09:08:44.668Z (3 months ago)
- Language: Go
- Size: 49.8 KB
- Stars: 17
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- trackawesomelist - envyaml (⭐10) - Yaml with environment variables reader. it helps to have secrets as environment variable but load them configs as structured Yaml. (Recently Updated / [Dec 24, 2024](/content/2024/12/24/README.md))
- awesome-go-cn - envyaml
- awesome-go - envyaml - Yaml with environment variables reader. it helps to have secrets as environment variable but load them configs as structured Yaml. (Configuration / Standard CLI)
- awesome-go-with-stars - envyaml - 12-25 | (Configuration / Standard CLI)
- awesome-go - envyaml - Yaml with environment variables reader. it helps to have secrets as environment variable but load them configs as structured Yaml. (Configuration / Standard CLI)
- awesome-go-plus - envyaml - Yaml with environment variables reader. it helps to have secrets as environment variable but load them configs as structured Yaml.  (Configuration / Standard CLI)
- fucking-awesome-go - envyaml - Yaml with environment variables reader. it helps to have secrets as environment variable but load them configs as structured Yaml. (Configuration / Standard CLI)
README
# 🔐 envYaml
### Seamlessly merge YAML configuration with environment variables
[](https://go.dev/)
[](https://codecov.io/github/yuseferi/envyaml)
[](https://github.com/yuseferi/envyaml/actions/workflows/ci.yml)
[](https://goreportcard.com/report/github.com/yuseferi/envyaml)
[](LICENSE)
[](https://github.com/yuseferi/envyaml/releases)
**Keep your configuration clean. Keep your secrets safe.**
[Installation](#-installation) •
[Quick Start](#-quick-start) •
[Features](#-features) •
[Examples](#-examples) •
[Contributing](#-contributing)
---
## 🎯 The Problem
You love YAML for configuration—it's clean, readable, and organized. But what about sensitive data like API keys, database passwords, and tokens? Hardcoding them is a security nightmare. 😱
## ✨ The Solution
**envYaml** bridges the gap between clean YAML configuration and secure environment variable management. Reference environment variables directly in your YAML files, and envYaml handles the rest!
```yaml
# config.yml - Clean and secure! 🔒
database:
host: localhost
port: 5432
password: ${DB_PASSWORD} # Loaded from environment
api:
key: ${API_KEY} # Never committed to git
secret: ${API_SECRET} # Always secure
```
## 🚀 Installation
```bash
go get github.com/yuseferi/envyaml@latest
```
**Requirements:** Go 1.25+
## ⚡ Quick Start
**1. Create your YAML configuration:**
```yaml
# config.yml
host: localhost
port: 3606
password: ${DB_PASSWORD}
```
**2. Define your config struct:**
```go
type Config struct {
Host string `yaml:"host" env:"HOST"`
Port int `yaml:"port" env:"PORT"`
Password string `yaml:"password" env:"DB_PASSWORD,required"`
}
```
**3. Load and use:**
```go
package main
import (
"fmt"
"log"
"github.com/yuseferi/envyaml"
)
func main() {
var cfg Config
if err := envyaml.LoadConfig("config.yml", &cfg); err != nil {
log.Fatal(err)
}
fmt.Printf("Connected to %s:%d\n", cfg.Host, cfg.Port)
}
```
## 🎨 Features
| Feature | Description |
|---------|-------------|
| 🔄 **Seamless Integration** | Combine YAML files with environment variables effortlessly |
| ✅ **Required Variables** | Mark critical env vars as required with automatic validation |
| 🏷️ **Struct Tags** | Use familiar `yaml` and `env` struct tags |
| 🛡️ **Type Safety** | Full Go type safety with automatic type conversion |
| 📦 **Zero Config** | Works out of the box with sensible defaults |
| 🪶 **Lightweight** | Minimal dependencies, maximum performance |
## 📚 Examples
### Required Environment Variables
Mark sensitive variables as required to fail fast if they're missing:
```go
type Config struct {
Host string `yaml:"host" env:"HOST"`
Port int `yaml:"port" env:"PORT"`
Password string `yaml:"password" env:"DB_PASSWORD,required"` // 👈 Required!
}
var cfg Config
err := envyaml.LoadConfig("config.yml", &cfg)
if err != nil {
// Error: failed to parse environment variables: env: required environment variable "DB_PASSWORD" is not set
log.Fatal(err)
}
```
### Complete Working Example
```go
package main
import (
"fmt"
"log"
"os"
"github.com/yuseferi/envyaml"
)
type DatabaseConfig struct {
Host string `yaml:"host" env:"DB_HOST"`
Port int `yaml:"port" env:"DB_PORT"`
Username string `yaml:"username" env:"DB_USER"`
Password string `yaml:"password" env:"DB_PASSWORD,required"`
Database string `yaml:"database" env:"DB_NAME"`
}
type Config struct {
Database DatabaseConfig `yaml:"database"`
Debug bool `yaml:"debug" env:"DEBUG"`
}
func main() {
// Set environment variables (in production, these come from your environment)
os.Setenv("DB_PASSWORD", "super_secret_password")
var cfg Config
if err := envyaml.LoadConfig("config.yml", &cfg); err != nil {
log.Fatalf("Failed to load config: %v", err)
}
fmt.Printf("Database: %s@%s:%d/%s\n",
cfg.Database.Username,
cfg.Database.Host,
cfg.Database.Port,
cfg.Database.Database,
)
}
```
With this `config.yml`:
```yaml
database:
host: localhost
port: 5432
username: admin
password: ${DB_PASSWORD}
database: myapp
debug: false
```
**Output:**
```
Database: admin@localhost:5432/myapp
```
## 🏗️ How It Works
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ YAML File │ │ Environment │ │ Go Struct │
│ │ │ Variables │ │ │
│ host: localhost│ │ │ │ Host: localhost│
│ port: 3606 │ ──► │ DB_PASSWORD= │ ──► │ Port: 3606 │
│ password: ${..}│ │ "secret123" │ │ Password: ... │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┴───────────────────────┘
envYaml
```
1. **Read** - Parse your YAML configuration file
2. **Merge** - Overlay environment variables using struct tags
3. **Validate** - Ensure required variables are present
4. **Return** - Provide a fully populated, type-safe config struct
## 🛠️ Development
This project uses [Task](https://taskfile.dev) for managing development tasks.
```bash
# Build the project
task build
# Run tests
task test
# Run tests with coverage
task test-coverage
# Clean generated files
task clean
# Run all tasks
task all
```
## 🤝 Contributing
We love contributions! ❤️
1. 🍴 Fork the repository
2. 🌿 Create your feature branch (`git checkout -b feature/amazing-feature`)
3. 💾 Commit your changes (`git commit -m 'Add amazing feature'`)
4. 📤 Push to the branch (`git push origin feature/amazing-feature`)
5. 🎉 Open a Pull Request
Please feel free to:
- 🐛 Report bugs
- 💡 Suggest new features
- 📖 Improve documentation
- ⭐ Star the project if you find it useful!
## 📄 License
This project is licensed under the **GNU General Public License v3.0** - see the [LICENSE](LICENSE) file for details.
---
**Made with ❤️ by [Yusef Mohamadi](https://github.com/yuseferi)**
If this project helped you, consider giving it a ⭐!
[](https://github.com/yuseferi/envyaml/stargazers)
[](https://github.com/yuseferi/envyaml/network/members)