> ## Documentation Index
> Fetch the complete documentation index at: https://infisical.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Spacelift Sync

> Learn how to configure a Spacelift Sync for Infisical.

**Prerequisites:**

* Set up and add secrets to [Infisical Cloud](https://app.infisical.com).
* Create a [Spacelift Connection](/docs/integrations/app-connections/spacelift).

<Tabs>
  <Tab title="Infisical UI">
    <Steps>
      <Step title="Add Sync">
        Navigate to **Project** > **Integrations**, select the **Secret Syncs** tab, and click **Add Sync**.

        <img src="https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/secret-syncs/spacelift/spacelift-sync-add.png" alt="Add Sync" />
      </Step>

      <Step title="Select Spacelift">
        Select **Spacelift** from the list of available secret syncs.

        <img src="https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/secret-syncs/spacelift/spacelift-sync-select.png" alt="Select Spacelift" />
      </Step>

      <Step title="Configure source">
        Configure the **Source** from where secrets should be retrieved, then click **Next**.

        * **Environment**: The project environment from which to retrieve secrets.
        * **Secret Path**: The folder path from which to retrieve secrets.

        <Tip>
          If you need to sync secrets from multiple folder locations, use [secret imports](/docs/documentation/platform/secret-reference#secret-imports).
        </Tip>

        <img src="https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/secret-syncs/spacelift/spacelift-sync-source.png" alt="Configure Source" />
      </Step>

      <Step title="Configure destination">
        Configure the **Destination** where secrets should be deployed, then click **Next**.

        * **Spacelift Connection**: Select the app connection to use for authentication.
        * **Context**: Select the Spacelift context that will receive the synced secrets.
        * **Config Type**: Choose how secrets are stored in the Spacelift context.

        Secret keys are sanitized to conform to UNIX environment variable naming rules: any characters outside `a-zA-Z0-9_` are stripped, and keys that start with a digit are prefixed with an underscore. Keys that become empty after sanitization are skipped.

        <Tabs>
          <Tab title="Environment Variables">
            Each secret is synced as an individual environment variable in the Spacelift context (default).

            <img src="https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/secret-syncs/spacelift/spacelift-sync-destination-env-vars.png" alt="Environment Variables Destination" />
          </Tab>

          <Tab title=".env File">
            All secrets are bundled into a single `.env` file and mounted at the specified path under `/mnt/workspace/`. For example, if the mount path is `secrets.env`, the file is available at `/mnt/workspace/secrets.env` during runs.

            * **File Path**: The path for the mounted `.env` file relative to `/mnt/workspace/` (e.g., `secrets.env`). Required.

                          <img src="https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/secret-syncs/spacelift/spacelift-sync-destination-dot-env.png" alt=".env File Destination" />
          </Tab>

          <Tab title="One Secret Per File">
            Each secret is stored as a separate file. The filename is the sanitized secret key and the file content is the secret value. For example, with a directory path of `secrets/`, a secret named `MY_SECRET` is available at `/mnt/workspace/secrets/MY_SECRET`.

            * **Directory Path**: The directory under `/mnt/workspace/` where secret files are created (e.g., `secrets/`). Optional -- leave empty to mount files directly in `/mnt/workspace/`.

            <Warning>
              When secret deletion protection is disabled, any files in the target directory that do not correspond to a secret in Infisical will be removed. If you have files in that directory managed outside of Infisical, enable **Disable Secret Deletion** to prevent them from being deleted.
            </Warning>

            <img src="https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/secret-syncs/spacelift/spacelift-sync-destination-secret-per-file.png" alt="One Secret Per File Destination" />
          </Tab>
        </Tabs>
      </Step>

      <Step title="Configure sync options">
        Configure the **Sync Options**, then click **Next**.

        * **Initial Sync Behavior**: Only **Overwrite Destination Secrets** is supported. Infisical cannot read secrets back from Spacelift because variables marked as secret in the Spacelift API are write-only, so importing is not possible.
        * **Key Schema**: A template that transforms secret names when syncing. Use `{{secretKey}}` for the original secret name and `{{environment}}` for the environment.
        * **Auto-Sync Enabled**: Automatically sync secrets from the source location when changes occur. Disable this to sync manually only.
        * **Disable Secret Deletion**: Prevents Infisical from removing secrets at the destination. Enable this when you intend to manage destination secrets outside Infisical.
        * **Mark as Secret**: When enabled, synced variables are marked as secrets in Spacelift. Secret values are only available to Runs and Tasks and are not accessible in the web GUI or through the API.

                  <img src="https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/secret-syncs/spacelift/spacelift-sync-options.png" alt="Configure Sync Options" />
      </Step>

      <Step title="Configure details">
        Configure the details of your Spacelift Sync, then click **Next**.

        * **Name**: A slug-friendly name for the sync.
        * **Description**: An optional description for the sync.

                  <img src="https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/secret-syncs/spacelift/spacelift-sync-details.png" alt="Configure Details" />
      </Step>

      <Step title="Review configuration">
        Review the Spacelift Sync configuration, then click **Create Sync**.

        <img src="https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/secret-syncs/spacelift/spacelift-sync-review.png" alt="Review Configuration" />
      </Step>

      <Step title="Sync created">
        If enabled, the Spacelift Sync begins syncing your secrets to the selected context.

        <img src="https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/secret-syncs/spacelift/spacelift-sync-created.png" alt="Sync Created" />
      </Step>
    </Steps>
  </Tab>

  <Tab title="API">
    To create a **Spacelift Sync**, make an API request to the [Create Spacelift Sync](/docs/api-reference/endpoints/secret-syncs/spacelift/create) API endpoint.

    ### Sample request (Environment Variables)

    ```bash Request theme={"dark"}
    curl --request POST \
      --url https://app.infisical.com/api/v1/secret-syncs/spacelift \
      --header 'Content-Type: application/json' \
      --data '{
        "name": "my-spacelift-sync",
        "projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "description": "an example sync",
        "connectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "environment": "dev",
        "secretPath": "/my-secrets",
        "isEnabled": true,
        "syncOptions": {
          "initialSyncBehavior": "overwrite-destination",
          "disableSecretDeletion": true,
          "writeOnly": false
        },
        "destinationConfig": {
          "contextId": "context-id",
          "contextName": "my-context",
          "configType": "environment-variable"
        }
      }'
    ```

    ### Sample request (File Mount - .env)

    ```bash Request theme={"dark"}
    curl --request POST \
      --url https://app.infisical.com/api/v1/secret-syncs/spacelift \
      --header 'Content-Type: application/json' \
      --data '{
        "name": "my-spacelift-file-sync",
        "projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "description": "sync secrets as a mounted .env file",
        "connectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "environment": "dev",
        "secretPath": "/my-secrets",
        "isEnabled": true,
        "syncOptions": {
          "initialSyncBehavior": "overwrite-destination",
          "disableSecretDeletion": true,
          "writeOnly": false
        },
        "destinationConfig": {
          "contextId": "context-id",
          "contextName": "my-context",
          "configType": "file-mount",
          "fileMountFormat": "dot-env",
          "mountPath": "secrets.env"
        }
      }'
    ```

    ### Sample request (File Mount - One Secret Per File)

    ```bash Request theme={"dark"}
    curl --request POST \
      --url https://app.infisical.com/api/v1/secret-syncs/spacelift \
      --header 'Content-Type: application/json' \
      --data '{
        "name": "my-spacelift-per-file-sync",
        "projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "description": "sync each secret as a separate mounted file",
        "connectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "environment": "dev",
        "secretPath": "/my-secrets",
        "isEnabled": true,
        "syncOptions": {
          "initialSyncBehavior": "overwrite-destination",
          "disableSecretDeletion": true,
          "writeOnly": false
        },
        "destinationConfig": {
          "contextId": "context-id",
          "contextName": "my-context",
          "configType": "file-mount",
          "fileMountFormat": "secret-per-file",
          "mountPath": "secrets/"
        }
      }'
    ```

    <Note>
      When using `file-mount` with `dot-env` format, all secrets are bundled into a single `.env` file and mounted at `/mnt/workspace/<mountPath>`. The `mountPath` field is required.

      When using `file-mount` with `secret-per-file` format, each secret is mounted as a separate file at `/mnt/workspace/<mountPath>/<secretKey>`. The `mountPath` field is optional -- omit it to mount files directly under `/mnt/workspace/`.
    </Note>
  </Tab>
</Tabs>