Concept
Secret Syncs are a project-level resource used to sync secrets, via an App Connection, from a particular project environment and folder path (source) to a third-party service (destination). Changes to the source will automatically be propagated to the destination, ensuring your secrets are always up-to-date.Workflow
Configuring a Secret Sync requires three components: a source location to retrieve secrets from, a destination endpoint to deploy secrets to, and configuration options to determine how your secrets should be synced. Follow these steps to start syncing:For step-by-step guides on syncing to a particular third-party service, refer to the Secret Syncs section in the Navigation Bar.
- Create App Connection: If you haven’t already done so, create an App Connection via the UI or API for the third-party service you intend to sync secrets to.
-
Create Secret Sync: Configure a Secret Sync in the desired project by specifying the following parameters via the UI or API:
- Source: The project environment and folder path you wish to retrieve secrets from.
- Destination: The App Connection to utilize and the destination endpoint to deploy secrets to. These can vary between services.
- Options: Customize how secrets should be synced, such as whether secrets should be imported from the destination on the initial sync, or whether the sync should include all subfolders beneath the source path.
Secret Syncs are the source of truth for connected third-party services. Any secret,
including associated data, not present or imported in Infisical before syncing will be
overwritten, and changes made directly in the connected service outside of infisical may also
be overwritten by future syncs.
Some third-party services don’t support importing secrets.
- Utilize Sync: Any changes to the source location will now automatically be propagated to the destination endpoint.
Infisical is continuously expanding it’s Secret Sync third-party service support. If the service you need isn’t available,
you can contact us at [email protected] to make a request.
Include all subfolders
A Secret Sync covers only the secrets in its source folder by default. Turn on Include secrets from all subfolders on the source step and the sync covers every folder beneath that path as well, however deep. Adding or changing a secret in any of those folders syncs it to the destination, the same as a change in the source folder itself. Destinations store secrets in one flat list, so the folder structure isn’t carried over. A secret namedDB_URL in /backend and a secret named DB_URL in /backend/api both map to the same destination key, and the sync fails with an error naming both folders rather than picking one. Infisical checks for these collisions while you configure the sync, so you can rename or move one of the two before you save.
A sync that includes subfolders can’t import secrets from the destination into Infisical, because there’s no single folder to import them into. Its initial sync behavior is always overwrite destination.
Key schemas
Key Schemas transform your secret keys by applying a prefix, suffix, or format pattern during sync to external destinations. This makes it clear which secrets are managed by Infisical and prevents accidental changes to unrelated secrets. Any destination secrets which don’t match the schema won’t get deleted or updated by Infisical. Key Schemas use handlebars syntax to define dynamic values. Here’s a full list of available variables:{{secretKey}}- The key of the secret{{environment}}- The environment which the secret is in (e.g. dev, staging, prod)
- Infisical key:
SECRET_1 - Schema:
INFISICAL_{{secretKey}} - Synced key:
INFISICAL_SECRET_1
When importing secrets from the destination into Infisical, the schema is stripped from imported secret keys.
Get alerted when a sync fails
If a sync, import, or remove fails after all of its retries, the sync’s failure alert notifies your team by email, Slack, webhook, or PagerDuty.- If you create a sync in the Infisical UI and can edit secret syncs in its environment and path, the alert is on by default, with an email to the project’s admins
- If a sync existed before failure alerts were available, it has the same alert
- Project admins get an in-app notification when a sync fails, even if the alert is off
1
For a new sync, go to your project’s Integrations page, open the Secret Syncs tab, and select Add Sync. For an existing sync, open the sync and select Edit Sync.
2
Go to the Alerts step and make sure Alert on Sync Failure is on. If you’re editing a sync, select Alerts under Sections to go straight to it.
3
Select Add channel and set up at least one notification channel. The Project Admins recipient emails members who have the Admin role directly on the project. If someone is an admin only through a group, add the group as a recipient too.
4
For a new sync, select Create Sync on the Review step. For an existing sync, select Save.
secret.sync as the resource type, the sync’s ID as the resource ID, and secret.sync.failed as the event.