Gabriel Brown
89761a7da3
Agent instructions, skills, SSH host aliases and expansion triggers are worth having identical on every machine one person owns, and belong in none of the shared configuration. They live in user/ now, with a manifest saying where each piece goes and a link-user stage that puts it there. That stage does nothing unless the machine said yes. Somebody who clones Panama to try the desktop keeps their own ~/.claude/CLAUDE.md exactly where it was; the question names the destinations and defaults to no. Anything displaced goes to config/old rather than being deleted. ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md were byte-identical copies of one file, which is the drift this exists to prevent. Also adds the vitals toggles for the battery and Claude usage readouts, which had preferences and no way to reach them.
3.7 KiB
Secret Syncs Overview
What are Secret Syncs?
Secret Syncs are project-level resources that automatically push secrets from an Infisical source (environment + folder path) to third-party services. When secrets change in Infisical, the sync propagates those changes to the destination.
Infisical is the source of truth. Secrets at the destination not present in Infisical may be overwritten depending on the initial sync behavior setting.
Prerequisites
Every sync requires an App Connection — an authenticated connection to the target service with the correct permissions. Create the App Connection first, then create the sync.
Common Setup Workflow
- Create App Connection for the target service (one-time setup, reusable across syncs)
- Navigate to Project → Integrations → Secret Syncs tab → Add Sync
- Select destination (e.g., AWS Secrets Manager, GitHub, etc.)
- Configure Source:
- Environment: project environment slug (e.g.,
dev,staging,prod) - Secret Path: folder path (e.g.,
/,/api-keys,/database)
- Environment: project environment slug (e.g.,
- Configure Destination: provider-specific fields (region, vault URL, repo, etc.)
- Configure Sync Options:
- Initial Sync Behavior
- Key Schema (recommended)
- Auto-Sync toggle
- Disable Secret Deletion toggle
- Name the sync and create
Key Concepts
Initial Sync Behavior
Controls what happens on the first sync:
| Option | Behavior |
|---|---|
| Overwrite Destination | Removes any secrets at the destination not present in Infisical |
| Import (Prioritize Infisical) | Imports existing destination secrets into Infisical first, Infisical values win on conflict |
| Import (Prioritize Destination) | Imports existing destination secrets into Infisical first, destination values win on conflict |
Not all destinations support importing. GitHub only supports "Overwrite Destination."
Key Schema
A template that transforms secret names when syncing. Uses {{secretKey}} as a placeholder for the original name and {{environment}} for the environment slug.
Example: Key schema INFISICAL_{{secretKey}} transforms Infisical key DATABASE_URL into INFISICAL_DATABASE_URL at the destination.
Why use it: Prevents Infisical from accidentally managing secrets it didn't create. Highly recommended for all syncs.
When importing secrets, the key schema is stripped from keys before importing into Infisical.
Mapping Behavior (AWS Secrets Manager only)
- One-to-One: Each Infisical secret becomes a separate secret in the destination
- Many-to-One: All Infisical secrets are packed into a single destination secret (as JSON key-value pairs)
Auto-Sync
Enabled by default. Secrets automatically sync when changes occur in the Infisical source. Disable for manual-only syncing.
Disable Secret Deletion
When enabled, Infisical will not remove secrets from the destination. Use this if you manage some secrets manually outside of Infisical.
Supported Destinations (38+)
Cloud Secret Managers: AWS Secrets Manager, AWS Parameter Store, GCP Secret Manager, Azure Key Vault, OCI Vault, HashiCorp Vault
CI/CD & Platforms: GitHub, GitLab, Bitbucket, Vercel, Netlify, Cloudflare Workers, Cloudflare Pages, Railway, Render, Fly.io, Heroku, Northflank, Digital Ocean, Supabase
DevOps & Monitoring: TeamCity, CircleCI, Jenkins (via Octopus Deploy), Terraform Cloud, Humanitec, Chef, Camunda, Checkly, Windmill, Zabbix, Databricks, Laravel Forge
Other: 1Password, Azure DevOps, Azure Entra ID (SCIM), External Infisical instance
Secret Imports for Multiple Paths
If you need to sync secrets from multiple folder locations into a single sync, use Infisical's Secret Imports feature to consolidate them into one path first, then sync that path.