onepassword-cli-coder

Core Patterns

Secret Reference Format

op://<vault>/<item>/<field>

Examples:

op://Development/AWS/access_key_id
op://Production/Database/password
op://Shared/Stripe/secret_key

Item Naming Conventions

Format: {environment}-{service} with kebab-case. One item per environment.

Pattern	Example	Bad Alternative
{env}-{service}	production-rails	Production Rails
{env}-{provider}	production-dockerhub	API Key
{env}-{provider}-{resource}	production-hetzner-s3	Mixed env items

Field Naming

Use semantic field names that describe the credential type:

Good	Bad	Why
access_token	value	Self-documenting
master_key	secret	Specific purpose clear
secret_access_key	key	Matches AWS naming
api_token	token	Distinguishes from other tokens

Field naming rules:

• Match the provider's terminology when possible (AWS uses access_key_id, secret_access_key)
• Use snake_case for consistency
• Be specific: database_password not just password when item has multiple credentials

Environment File (.op.env)

Create .op.env in project root:

AWS_ACCESS_KEY_ID=op://Infrastructure/AWS/access_key_id
AWS_SECRET_ACCESS_KEY=op://Infrastructure/AWS/secret_access_key
DIGITALOCEAN_TOKEN=op://Infrastructure/DigitalOcean/api_token
DATABASE_URL=op://Production/PostgreSQL/connection_string
STRIPE_SECRET_KEY=op://Production/Stripe/secret_key

Critical: Add to .gitignore:

# 1Password - NEVER commit
.op.env
*.op.env

Running Commands with Secrets

op run --env-file=.op.env -- terraform plan
op run --env-file=.op.env -- rails server

Integration Patterns

Makefile Integration

OP ?= op
OP_ENV_FILE ?= .op.env

# Prefix for all commands needing secrets
CMD = $(OP) run --env-file=$(OP_ENV_FILE) --

deploy:
	$(CMD) kamal deploy

console:
	$(CMD) rails console

migrate:
	$(CMD) rails db:migrate

Docker Compose

op run --env-file=.op.env -- docker compose up

Kamal Deployment

# config/deploy.yml
env:
  secret:
    - RAILS_MASTER_KEY
    - DATABASE_URL
    - REDIS_URL

# .kamal/secrets
RAILS_MASTER_KEY=$(op read "op://Production/Rails/master_key")
DATABASE_URL=$(op read "op://Production/PostgreSQL/url")
REDIS_URL=$(op read "op://Production/Redis/url")

CI/CD (GitHub Actions)

# .github/workflows/deploy.yml
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: 1password/load-secrets-action@v2
        with:
          export-env: true
        env:
          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
          AWS_ACCESS_KEY_ID: op://CI/AWS/access_key_id
          AWS_SECRET_ACCESS_KEY: op://CI/AWS/secret_access_key

      - run: terraform apply -auto-approve

CLI Commands

Reading Secrets

op read "op://Vault/Item/field"
op read "op://Vault/Item/field" --format json
op read "op://Vault/TLS/private_key" > /tmp/key.pem && chmod 600 /tmp/key.pem

Injecting into Commands

DATABASE_URL=$(op read "op://Production/DB/url") rails db:migrate
op run --env-file=.op.env -- ./deploy.sh
op run --account my-team --env-file=.op.env -- terraform apply

Managing Items

op vault list
op item list --vault Infrastructure
op item get "AWS" --vault Infrastructure
op item create --category login --vault Infrastructure \
  --title "New Service" --field username=admin --field password=secret123

Project Setup

Initial Configuration

op signin
op vault list

cat > .op.env << 'EOF'
AWS_ACCESS_KEY_ID=op://Infrastructure/AWS/access_key_id
AWS_SECRET_ACCESS_KEY=op://Infrastructure/AWS/secret_access_key
DATABASE_URL=op://Production/Database/url
REDIS_URL=op://Production/Redis/url
EOF

op run --env-file=.op.env -- env | grep -E '^(AWS|DATABASE|REDIS)'

Placeholder Workflow

Create items with placeholder values upfront, populate with real credentials later:

op item create --vault myproject --category login \
  --title "production-rails" --field master_key="PLACEHOLDER_UPDATE_BEFORE_DEPLOY"

cat > .kamal/secrets << 'EOF'
RAILS_MASTER_KEY=$(op read "op://myproject/production-rails/master_key")
EOF

# Later: update with real value
op item edit "production-rails" --vault myproject \
  master_key="actual_secret_value_here"

Vault Organization

Single-Vault Approach (Simpler)

Use one vault with naming conventions for environment separation:

Vault: myproject
Items:
  - production-rails
  - production-dockerhub
  - production-hetzner-s3
  - staging-rails
  - staging-dockerhub
  - development-rails

Multi-Vault Approach (Team Scale) -- use when teams need different access controls:

Vault	Purpose	Access
Infrastructure	Cloud provider credentials	DevOps team
Production	Production app secrets	Deploy systems
Staging	Staging environment	Dev team
Development	Local dev secrets	Individual devs

Security Rules

• Add .op.env and *.op.env to .gitignore -- never commit
• Use service accounts for CI/CD, not personal accounts
• Never pipe op read to logs or echo
• Never store session tokens in scripts
• Use variables for vault/item names in automation

Troubleshooting

op signin                  # Re-authenticate expired session
op whoami                  # Check current session
op vault list              # Verify vault access
op item list --vault Infrastructure | grep -i aws   # Search for items
op item get "AWS" --vault Infrastructure --format json | jq '.fields[].label'  # Check field names

Multiple Accounts

Always specify account in automation -- never rely on "last signed in":

op vault list --account acme.1password.com
export OP_ACCOUNT=acme.1password.com
op run --account acme.1password.com --env-file=.op.env -- ./deploy.sh

Multi-Environment Pattern

Use per-environment env files: .op.env.production, .op.env.staging, .op.env.development

ENV ?= development
OP_ENV_FILE = .op.env.$(ENV)

deploy:
	op run --env-file=$(OP_ENV_FILE) -- kamal deploy
# Usage: make deploy ENV=production

References

• references/multiple-accounts.md - Cross-account workflows and Makefile integration