Help us shape the future of Go! Take the 2026 Go Developer Survey

configs

package
v0.4.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 2, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

README

Environment Configuration Guide

This directory contains template files for different deployment scenarios. Copy the appropriate template to create your working configuration file.

Template Files Overview

Template File Purpose Use Case
env.yaml.example Complete reference with all variables First-time setup, documentation
env.yaml.production Production-ready template Quick deployment to production
.env.local.example Local development template Local testing and development

Note: Your actual working files (env.yaml, .env) should be created from these templates and are gitignored to protect secrets.

env.yaml.example

Location: configs/env.yaml.example

Purpose: Comprehensive reference showing ALL possible environment variables

Contents:

  • ✅ All 30+ supported variables
  • ✅ Detailed comments for each variable
  • ✅ Default values shown
  • ✅ Security best practices
  • ✅ Deployment notes
  • ✅ Local development tips

Use this when:

  • Setting up for the first time
  • Need to understand all available options
  • Want to see what features are available
  • Need reference documentation

env.yaml.production

Location: configs/env.yaml.production

Purpose: Production-ready template with sensible defaults

Contents:

  • ✅ Required variables pre-filled with MongoDB values
  • ✅ Secret Manager references (recommended approach)
  • ✅ Essential settings only
  • ✅ Audit logging enabled
  • ✅ Metrics enabled
  • ✅ Production-optimized

Use this when:

  • Deploying to production quickly
  • Want a minimal, clean configuration
  • Using Secret Manager (recommended)
  • Don't need advanced features

NOT included:

  • Slack notifications (optional)
  • MongoDB direct URI (use Secret Manager instead)
  • Advanced options (rarely needed)

.env.local.example

Location: configs/.env.local.example

Purpose: Local development template (traditional .env format)

Contents:

  • ✅ .env format (KEY=value)
  • ✅ Suitable for local testing
  • ✅ Works with godotenv
  • ✅ Can use direct secrets (not Secret Manager)

Use this when:

  • Developing locally
  • Testing without Google Cloud
  • Using go run or local server
  • Don't want to set up Secret Manager

Format difference:

# .env format (for local development)
GITHUB_APP_ID=123456
REPO_OWNER=mongodb
REPO_NAME=docs-code-examples

vs

# env.yaml format (for App Engine deployment)
env_variables:
  GITHUB_APP_ID: "123456"
  REPO_OWNER: "mongodb"
  REPO_NAME: "docs-code-examples"

Deployment Target

This service deploys to Google Cloud Run.

Cloud Run

Config file: env-cloudrun.yaml (plain YAML key-value pairs)

Format:

GITHUB_APP_ID: "123456"
REPO_OWNER: "mongodb"

Deploy:

cp configs/env.yaml.production env-cloudrun.yaml
# Edit env-cloudrun.yaml with your values
./scripts/deploy-cloudrun.sh

Usage Scenarios

Scenario 1: First-Time Production Deployment

Recommended: env.yaml.production

# Quick start
cp configs/env.yaml.production env-cloudrun.yaml
nano env-cloudrun.yaml  # Update PROJECT_NUMBER and values
./scripts/grant-secret-access.sh
./scripts/deploy-cloudrun.sh

Why: Pre-configured with production best practices, minimal setup required.

Scenario 2: Need to Understand All Options

Recommended: env.yaml.example

# Reference all options
cat configs/env.yaml.example

# Copy and customize
cp configs/env.yaml.example env.yaml
nano env.yaml  # Enable features you need

Why: Shows all available features with detailed explanations.

Scenario 3: Local Development

Recommended: .env.local.example

# Local development
cp configs/.env.local.example configs/.env
nano configs/.env  # Add your values

# Run locally
go run app.go -env configs/.env

Why: Simpler format for local testing, no Secret Manager required.

Scenario 4: Custom Production Setup

Recommended: Start with env.yaml.example, customize

# Start with full reference
cp configs/env.yaml.example env.yaml

# Enable features you need
nano env.yaml
# - Enable Slack notifications
# - Configure custom MongoDB settings
# - Set custom defaults

# Deploy
./scripts/deploy-cloudrun.sh

Why: Need advanced features not in production template.

Migration Guide

From .env to env.yaml

Use the conversion script:

./scripts/convert-env-to-yaml.sh configs/.env env.yaml

Or manually convert:

# .env format:
GITHUB_APP_ID=123456
REPO_OWNER=mongodb

# Cloud Run YAML format:
GITHUB_APP_ID: "123456"
REPO_OWNER: "mongodb"

Key difference:

  • App Engine: Requires env_variables: wrapper with 2-space indentation
  • Cloud Run: Plain YAML without wrapper
From env.yaml.production to env.yaml.example
# Start with production template
cp configs/env.yaml.production env.yaml

# Add optional features from example
# Compare files and add what you need:
diff configs/env.yaml.production configs/env.yaml.example

Best Practices

✅ DO
  • Use env.yaml.production for quick production deployment
  • Use env.yaml.example as reference documentation
  • Use .env.local.example for local development
  • Add env.yaml and .env to .gitignore
  • Use Secret Manager for production secrets
  • Keep comments in your env.yaml for team documentation
❌ DON'T
  • Don't commit env.yaml or .env with actual secrets
  • Don't use direct secrets in production (use Secret Manager)
  • Don't mix .env and env.yaml formats
  • Don't remove all comments (they help future you)
  • Don't use env.yaml.production as-is (update values first)

File Locations

github-copier/
├── configs/
│   ├── env.yaml.example          # ← Complete reference (all variables)
│   ├── env.yaml.production       # ← Production template (essential only)
│   └── .env.local.example        # ← Local development template
├── env.yaml                      # ← App Engine config (create from template, gitignored)
├── env-cloudrun.yaml             # ← Cloud Run config (create from template, gitignored)
└── .env                          # ← Local config (create from template, gitignored)

Working files (not in repo):

  • env.yaml - App Engine deployment (YAML with env_variables: wrapper)
  • env-cloudrun.yaml - Cloud Run deployment (plain YAML, no wrapper)
  • .env - Local development (KEY=value format)

Quick Reference

Need to deploy quickly? → Use env.yaml.production

Need to understand all options? → Read env.yaml.example

Need to develop locally? → Use .env.local.example

Need advanced features? → Start with env.yaml.example, customize

Need to convert formats? → Use ./scripts/convert-env-to-yaml.sh

See Also

Documentation

Index

Constants

View Source 
const (
	EnvFile                         = "ENV"
	Port                            = "PORT"
	ConfigRepoName                  = "CONFIG_REPO_NAME"
	ConfigRepoOwner                 = "CONFIG_REPO_OWNER"
	AppId                           = "GITHUB_APP_ID"
	AppClientId                     = "GITHUB_APP_CLIENT_ID"
	InstallationId                  = "INSTALLATION_ID"
	CommitterName                   = "COMMITTER_NAME"
	CommitterEmail                  = "COMMITTER_EMAIL"
	ConfigFile                      = "CONFIG_FILE"
	MainConfigFile                  = "MAIN_CONFIG_FILE"
	UseMainConfig                   = "USE_MAIN_CONFIG"
	DeprecationFile                 = "DEPRECATION_FILE"
	WebserverPath                   = "WEBSERVER_PATH"
	ConfigRepoBranch                = "CONFIG_REPO_BRANCH"
	PEMKeyName                      = "PEM_NAME"            // #nosec G101 -- env var name, not a credential
	WebhookSecretName               = "WEBHOOK_SECRET_NAME" // #nosec G101 -- env var name, not a credential
	WebhookSecret                   = "WEBHOOK_SECRET"      // #nosec G101 -- env var name, not a credential
	CopierLogName                   = "COPIER_LOG_NAME"
	GoogleCloudProjectId            = "GOOGLE_CLOUD_PROJECT_ID"
	DefaultRecursiveCopy            = "DEFAULT_RECURSIVE_COPY"
	DefaultPRMerge                  = "DEFAULT_PR_MERGE"
	DefaultCommitMessage            = "DEFAULT_COMMIT_MESSAGE"
	DryRun                          = "DRY_RUN"
	AuditEnabled                    = "AUDIT_ENABLED"
	MongoURI                        = "MONGO_URI"
	MongoURISecretName              = "MONGO_URI_SECRET_NAME" // #nosec G101 -- env var name, not a credential
	AuditDatabase                   = "AUDIT_DATABASE"
	AuditCollection                 = "AUDIT_COLLECTION"
	MetricsEnabled                  = "METRICS_ENABLED"
	SlackWebhookURL                 = "SLACK_WEBHOOK_URL" // #nosec G101 -- env var name, not a credential
	SlackChannel                    = "SLACK_CHANNEL"
	SlackUsername                   = "SLACK_USERNAME"
	SlackIconEmoji                  = "SLACK_ICON_EMOJI"
	SlackEnabled                    = "SLACK_ENABLED"
	SlackPlainText                  = "SLACK_PLAIN_TEXT"       // Use for Workflow Builder webhooks
	SlackMessageVariable            = "SLACK_MESSAGE_VARIABLE" // Variable name for Workflow Builder (default: "text")
	GitHubAPIMaxRetries             = "GITHUB_API_MAX_RETRIES"
	GitHubAPIInitialRetryDelay      = "GITHUB_API_INITIAL_RETRY_DELAY"
	PRMergePollMaxAttempts          = "PR_MERGE_POLL_MAX_ATTEMPTS"
	PRMergePollInterval             = "PR_MERGE_POLL_INTERVAL"
	ConfigCacheTTLSeconds           = "CONFIG_CACHE_TTL_SECONDS"
	WebhookProcessingTimeoutSeconds = "WEBHOOK_PROCESSING_TIMEOUT_SECONDS"
	WebhookMaxRetries               = "WEBHOOK_MAX_RETRIES"
	WebhookRetryInitialDelay        = "WEBHOOK_RETRY_INITIAL_DELAY" //nolint:gosec // env var name, not a credential
	OperatorUIEnabled               = "OPERATOR_UI_ENABLED"
	OperatorAuthRepo                = "OPERATOR_AUTH_REPO" // repo for GitHub PAT permission check
	OperatorRepoSlug                = "OPERATOR_REPO_SLUG"
	OperatorReleaseGitHubToken      = "OPERATOR_RELEASE_GITHUB_TOKEN" // #nosec G101 -- env var name
	OperatorReleaseTargetBranch     = "OPERATOR_RELEASE_TARGET_BRANCH"
	LLMProvider                     = "LLM_PROVIDER"
	LLMBaseURL                      = "LLM_BASE_URL"
	LLMModel                        = "LLM_MODEL"
	AnthropicAPIKey                 = "ANTHROPIC_API_KEY"             // #nosec G101 -- env var name, not a credential
	AnthropicAPIKeySecretName       = "ANTHROPIC_API_KEY_SECRET_NAME" // #nosec G101 -- env var name, not a credential
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Config 

type Config struct {
	EnvFile              string
	Port                 string
	ConfigRepoName       string // Repository where config file is stored
	ConfigRepoOwner      string // Owner of repository where config file is stored
	AppId                string
	AppClientId          string
	InstallationId       string
	CommitterName        string
	CommitterEmail       string
	ConfigFile           string
	MainConfigFile       string // Main config file with workflow references (optional)
	UseMainConfig        bool   // Whether to use main config format
	DeprecationFile      string
	WebserverPath        string
	ConfigRepoBranch     string // Branch to fetch config file from
	PEMKeyName           string
	WebhookSecretName    string
	WebhookSecret        string
	CopierLogName        string
	GoogleCloudProjectId string
	DefaultRecursiveCopy bool
	DefaultPRMerge       bool
	DefaultCommitMessage string

	// Optional features
	DryRun             bool
	AuditEnabled       bool
	MongoURI           string
	MongoURISecretName string
	AuditDatabase      string
	AuditCollection    string
	MetricsEnabled     bool

	// Slack notifications
	SlackWebhookURL      string
	SlackChannel         string
	SlackUsername        string
	SlackIconEmoji       string
	SlackEnabled         bool
	SlackPlainText       bool   // Use plain text only (required for Workflow Builder webhooks)
	SlackMessageVariable string // Variable name for Workflow Builder webhooks (default: "text")

	// GitHub API retry configuration
	GitHubAPIMaxRetries        int
	GitHubAPIInitialRetryDelay int // in milliseconds

	// PR merge polling configuration
	PRMergePollMaxAttempts int
	PRMergePollInterval    int // in milliseconds

	// Config cache TTL in seconds (0 = disabled)
	ConfigCacheTTLSeconds int

	// Webhook background processing timeout in seconds (0 = no timeout)
	WebhookProcessingTimeoutSeconds int

	// Webhook retry configuration
	WebhookMaxRetries        int // max retry attempts for failed webhook processing
	WebhookRetryInitialDelay int // initial delay between retries in seconds (doubles each attempt)

	// Operator web UI — off unless OPERATOR_UI_ENABLED=true. Works with any HTTP
	// origin (local dev, Cloud Run, etc.). Access is gated by GitHub PATs:
	// each user authenticates with their personal token, and the role
	// (operator or writer) is determined by their permission on OPERATOR_AUTH_REPO.
	OperatorUIEnabled           bool
	OperatorAuthRepo            string // "owner/repo" — user permissions here determine role (required when UI is enabled)
	OperatorRepoSlug            string // "owner/repo" for GitHub links in audit/trace rows (optional)
	OperatorReleaseGitHubToken  string // PAT with contents:write to create a version tag (optional)
	OperatorReleaseTargetBranch string // branch SHA used when creating a tag (default main)

	// AI rule suggestion (optional) — LLM-powered rule generation in the operator UI.
	// The feature is available whenever the LLM provider is reachable at runtime;
	// operators can change the active model and base URL from the UI without restart.
	LLMProvider string // "ollama" (local) or "anthropic" (hosted)
	LLMBaseURL  string // initial default; overridable from the UI
	LLMModel    string // initial default; overridable from the UI

	// Anthropic API key — required when LLMProvider="anthropic". Loaded from
	// Secret Manager via AnthropicAPIKeySecretName, or directly via
	// ANTHROPIC_API_KEY for local dev.
	AnthropicAPIKey           string
	AnthropicAPIKeySecretName string
}

Config holds all environment configuration

func LoadEnvironment 

func LoadEnvironment(envFile string) (*Config, error)

LoadEnvironment loads environment variables and returns populated Config

func NewConfig 

func NewConfig() *Config

NewConfig returns a new Config instance with default values

func (*Config) EffectiveConfigFile 

func (c *Config) EffectiveConfigFile() string

EffectiveConfigFile returns the config file path that the app will actually use. If MainConfigFile is set (USE_MAIN_CONFIG=true), it takes precedence over ConfigFile.

func (*Config) SecretPath 

func (c *Config) SecretPath(secretName string) string

SecretPath resolves a secret name to a fully-qualified GCP Secret Manager resource path. If the name already contains "projects/", it is returned as-is (for backward compatibility). Otherwise, it builds the full path using the configured GoogleCloudProjectId.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.