Secret Providers

Haloy integrates with external secret management services to securely manage credentials and sensitive data.Currently supports 1Password, with additional providers planned.

1Password Integration

Configure 1Password as a secret provider to pull secrets during deployment.

Prerequisites

  • 1Password CLI (op) installed and authenticated
  • The 1Password vault and item must exist with the referenced field names

Configuration

Define secret sources in your haloy.yaml:

name: "my-app"
image:
  repository: "ghcr.io/your-username/my-app"
  tag: "latest"

# Configure 1Password secret sources
secretProviders:
  onepassword:
    production-db: # Source name referenced in env vars
      account: "my-account" # Optional: 1Password account
      vault: "Production"
      item: "Database Credentials"
    api-keys:
      vault: "API Services"
      item: "Third-party APIs"

# Use secrets from 1Password and add them to the environment variables available in the container
env:
  - name: "DB_PASSWORD"
    from:
      secret: "onepassword:production-db.password" # References vault item field
  - name: "DB_USERNAME"
      from:
        secret: "onepassword:production-db.username"
  - name: "STRIPE_API_KEY"
      from:
        secret: "onepassword:api-keys.stripe-key"
  - name: "SENDGRID_API_KEY"
    from:
      secret: "onepassword:api-keys.sendgrid-key"

Secret Reference Format

onepassword:<source-name>.<field-name>
  • <source-name>: The key defined in secretProviders.onepassword
  • <field-name>: The field name in the 1Password item

1Password Item Structure

Your 1Password items should have fields matching your references:

Example Item: “Database Credentials”

  • Field: username → Value: db_user
  • Field: password → Value: super_secret_password
  • Field: host → Value: db.example.com

Example Item: “Third-party APIs”

  • Field: stripe-key → Value: sk_live_...
  • Field: sendgrid-key → Value: SG....

Registry Authentication with Secrets

Use 1Password to store registry credentials:

name: "my-app"
image:
  repository: "ghcr.io/your-org/private-app"
  tag: "latest"
  registry:
    username:
      from:
        secret: "onepassword:registry-credentials.username"
    password:
      from:
        secret: "onepassword:registry-credentials.password"

secretProviders:
  onepassword:
    registry-credentials:
      vault: "Infrastructure"
      item: "GitHub Container Registry"

API Token with Secrets

Store your Haloy API token in 1Password:

name: "my-app"
server: "api.haloy.dev"
api_token:
  from:
    secret: "onepassword:api-tokens.production"

secretProviders:
  onepassword:
    api-tokens:
    vault: "Infrastructure"
    item: "Haloy API Tokens"

Build Arguments with Secrets

Pass secrets to Docker build as build arguments:

name: "my-app"
image:
  repository: "my-app"
  tag: "latest"
  builder:
    context: "."
    args:
      - name: "NPM_TOKEN"
        from:
          secret: "onepassword:build-secrets.npm-token"
      - name: "GITHUB_TOKEN"
        from:
          secret: "onepassword:build-secrets.github-token"

secretProviders:
  onepassword:
    build-secrets:
    vault: "Development"
    item: "Build Tokens"

Multi-Target with Different Secrets

Use different secrets for different deployment targets:

name: "my-app"
secretProviders:
  onepassword:
    prod-db:
      vault: "Production"
      item: "Database"
    staging-db:
      vault: "Staging"
      item: "Database"

targets:
  production:
    server: "prod.myapp.com"
    env:
      - name: "DB_PASSWORD"
        from:
          secret: "onepassword:prod-db.password"

  staging:
    server: "staging.myapp.com"
    env: - name: "DB_PASSWORD"
      from:
        secret: "onepassword:staging-db.password"

Validation

Validate your configuration and verify secrets are resolved correctly:

# Validate config (doesn't show secret values)
haloy validate-config

# Show resolved config with secrets (use with caution!)
haloy validate-config --show-resolved-config

Warning: --show-resolved-config displays all secrets in plain text. Only use in secure environments.

Troubleshooting

1Password CLI Not Authenticated

# Check authentication status
op account list

# Sign in if needed
op signin

Secret Not Found

# Verify the item exists
op item get "Database Credentials" --vault "Production"

# List item fields

op item get "Database Credentials" --vault "Production" --fields label

Permission Denied

Ensure your 1Password account has access to the specified vault and item.

Next Steps