The midnight config crash
You push a new release to production. The server starts, connects to the database, and immediately crashes because it is trying to authenticate against a localhost instance that only exists on your laptop. The configuration file slipped through code review. Or worse, a debug flag that prints raw SQL queries to stdout is now broadcasting every customer query to your production logs. Environment-specific configuration is the difference between a smooth deployment and a midnight pager duty call.
Compile-time switches vs runtime overrides
Go handles this by separating compile-time decisions from runtime behavior. Think of build tags as a factory assembly line. You design one product, but the factory installs different engines depending on the destination market. The compiler sees the tags and physically removes the wrong code before it ever reaches the binary. Runtime flags like GODEBUG work differently. They are like a master override panel on the finished machine. You can flip switches to change how the Go runtime handles HTTP/2, garbage collection, or nil pointer panics without recompiling anything.
The minimal build tag pattern
Here is the simplest way to lock environment values at compile time. Create two files in the same package. The compiler will only include the one that matches the build constraint.
//go:build dev
package config
// Env identifies the current deployment target
const Env = "development"
// Debug enables verbose logging and mock services
const Debug = true
//go:build prod
package config
// Env identifies the current deployment target
const Env = "production"
// Debug disables verbose logging and mock services
const Debug = false
How the compiler actually picks files
When you run go build, the compiler scans every file in the package. It looks for the //go:build constraint at the top. If the constraint matches the tags you passed on the command line, the file is compiled. If it does not match, the compiler ignores it entirely. The old // +build syntax still works for backward compatibility, but the new //go:build format is the standard. You build for production with go build -tags prod. You build for development with go build -tags dev. If you forget to pass a tag, neither file compiles, and the package has no Env or Debug constants. The compiler rejects the program with undefined: config.Env. This strict behavior prevents silent fallbacks to wrong defaults.
Convention aside: gofmt handles build tag formatting automatically. Do not manually align the //go:build line or add extra spaces. Run gofmt -w . and let the tool decide. Most editors run it on save, so the constraint will always sit exactly where the compiler expects it.
Loading configuration in production
Real applications rarely rely on constants alone. You need to load database URLs, API keys, and feature flags from the deployment environment. Combine build tags with environment variables to create a safe configuration loader. The build tag sets the baseline, and the environment provides the secrets.
//go:build prod
package config
import (
"errors"
"os"
)
// Config holds the runtime settings for the application
type Config struct {
DatabaseURL string
LogLevel string
}
// Load reads environment variables and applies production defaults
func Load() (Config, error) {
// Default to structured JSON logging for log aggregators
logLevel := "info"
if val := os.Getenv("LOG_LEVEL"); val != "" {
logLevel = val
}
// Database URL must be provided in production
dbURL := os.Getenv("DATABASE_URL")
if dbURL == "" {
return Config{}, errors.New("DATABASE_URL is required in production")
}
return Config{
DatabaseURL: dbURL,
LogLevel: logLevel,
}, nil
}
The development version of this file can safely hardcode a local SQLite path or a test Postgres container. The production version refuses to start without a valid DATABASE_URL. This pattern keeps secrets out of version control while locking down the environment identity at compile time.
Convention aside: Go favors explicit configuration over hidden defaults. The community expects configuration to fail fast. If a required environment variable is missing, return an error immediately. Do not fall back to empty strings. The if err != nil { return err } pattern applies to configuration loading just as much as it applies to database queries. Make the unhappy path visible.
Runtime overrides with GODEBUG
Go also lets you control low-level runtime behavior through GODEBUG. You can set it as an environment variable or bake it into your module file. The go.mod directive enforces defaults for everyone who builds or runs the module.
# go.mod
module example.com/myapp
go 1.22
godebug (
// Disable HTTP/2 client support to avoid header compression bugs
http2client=0
// Panic on nil pointer dereference instead of silently returning zero
panicnil=1
)
When the runtime starts, it reads the godebug block from go.mod and applies those values as the baseline. You can still override them at runtime by exporting GODEBUG=http2client=1. This is useful for debugging a specific deployment without changing the module file. The runtime parses the string on startup and applies the flags to the internal scheduler, garbage collector, and network stack.
Where things break
Build tags are strict. A missing space after //go:build or a typo in the tag name means the compiler ignores the constraint. The file compiles in every build, and your production binary suddenly contains development code. The compiler does not warn you about unused build tags. It only complains when symbols collide or go missing. If you define Env in both files and forget the tags, you get Env redeclared in this package.
GODEBUG flags are equally unforgiving. The runtime parses the string on startup. A typo like http2clent=0 does not fail gracefully. The runtime ignores unknown keys, which means your intended override silently does nothing. If you pass a malformed value, the program panics with GODEBUG: invalid value for http2client. Always validate your GODEBUG strings in staging before touching production.
Convention aside: Functions that perform long-running work should accept context.Context as the first parameter, conventionally named ctx. When your configuration loader triggers a remote health check or validates a database connection, pass the context through. Respect cancellation and deadlines. Context is plumbing. Run it through every long-lived call site.
Choosing your configuration strategy
Use build tags when you need to swap entire code paths, mock dependencies, or lock environment identity at compile time. Use environment variables when you need to inject secrets, connection strings, or feature flags without rebuilding the binary. Use configuration files when your deployment targets require complex nested settings that do not fit in shell variables. Use GODEBUG directives when you need to enforce runtime safety defaults across a team or fix a known standard library bug. Use plain constants when the value never changes across environments and does not contain sensitive data.
Compile-time tags lock the shape. Runtime variables fill the details. Keep them separate.