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
secret_providers:
  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"
name: "my-app"
image:
  repository: "ghcr.io/your-username/my-app"
  tag: "latest"

# Configure 1Password secret sources
secret_providers:
  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>
onepassword:<source-name>.<field-name>

<source-name>: The key defined in secret_providers.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"

secret_providers:
  onepassword:
    registry-credentials:
      vault: "Infrastructure"
      item: "GitHub Container Registry"
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"

secret_providers:
  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"

secret_providers:
  onepassword:
    api-tokens:
      vault: "Infrastructure"
      item: "Haloy API Tokens"
name: "my-app"
server: "api.haloy.dev"
api_token:
  from:
    secret: "onepassword:api-tokens.production"

secret_providers:
  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"

secret_providers:
  onepassword:
    build-secrets:
      vault: "Development"
      item: "Build Tokens"
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"

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

Multi-Target with Different Secrets

Use different secrets for different deployment targets:

name: "my-app"
secret_providers:
  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"
name: "my-app"
secret_providers:
  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
# 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
# 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
# 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.