Lightning.Projects.Sandboxes (Lightning v2.14.14-pre1)

View Source

Manage sandbox projects - isolated copies of existing projects for safe experimentation.

Sandboxes allow developers to test changes, experiment with workflows, and collaborate without affecting production projects. They share credentials with their parent but maintain separate workflow execution environments.

What gets copied to a sandbox

  • Project settings: retention policies, concurrency limits, MFA requirements
  • Workflow structure: jobs, triggers (disabled), edges, and node positions
  • Credentials: references to parent credentials (no secrets duplicated)
  • Keychain metadata: cloned for jobs that use them
  • Version history: latest workflow version per workflow
  • Optional dataclips: named clips of specific types can be selectively copied

Operations

Authorization

  • Provisioning: Requires :owner or :admin role on the parent project or superuser
  • Updates/Deletion: Requires :owner or :admin role on the sandbox itself,
                      or `:owner` or `:admin` on the root project, or superuser

Transaction safety

All operations are performed within database transactions to ensure consistency. Failed operations leave no partial state behind.

Summary

Types

provision_attrs()

Attributes for creating a new sandbox via provision/3.

Functions

delete_sandbox(sandbox, actor)

Deletes a sandbox and all its descendant projects.

provision(parent, actor, attrs)

Creates a new sandbox project by cloning from a parent project.

update_sandbox(sandbox, actor, attrs)

Updates a sandbox project's basic attributes.

Types

provision_attrs()

@type provision_attrs() :: %{
  :name => String.t(),
  optional(:color) => String.t() | nil,
  optional(:env) => String.t() | nil,
  optional(:collaborators) => [
    %{user_id: Ecto.UUID.t(), role: :admin | :editor | :viewer}
  ],
  optional(:dataclip_ids) => [Ecto.UUID.t()]
}

Attributes for creating a new sandbox via provision/3.

Required

  • :name - Sandbox name (must be unique within the parent project)

Optional

  • :color - UI color hex string (e.g. "#336699")
  • :env - Environment identifier (e.g. "staging", "dev")

  • :collaborators - List of %{user_id: UUID, role: :admin | :editor | :viewer} Note: :owner roles and duplicate users are automatically filtered out

  • :dataclip_ids - UUIDs of dataclips to copy (only copies named dataclips of types :global, :saved_input, or :http_request)

Functions

delete_sandbox(sandbox, actor)

@spec delete_sandbox(
  Lightning.Projects.Project.t() | Ecto.UUID.t(),
  Lightning.Accounts.User.t()
) ::
  {:ok, Lightning.Projects.Project.t()}
  | {:error, :unauthorized | :not_found | term()}

Deletes a sandbox and all its descendant projects.

Warning: This permanently removes the sandbox and any nested sandboxes within it. This action cannot be undone.

Parameters

  • sandbox - Sandbox project to delete (or sandbox ID as string)
  • actor - User performing the deletion (needs :owner or :admin role on sandbox)

Returns

  • {:ok, deleted_sandbox} - Successfully deleted sandbox and descendants
  • {:error, :unauthorized} - Actor lacks permission on sandbox
  • {:error, :not_found} - Sandbox ID not found (when using string ID)
  • {:error, reason} - Database or other deletion error

Example

{:ok, deleted} = Sandboxes.delete_sandbox(sandbox, user)

provision(parent, actor, attrs)

@spec provision(
  Lightning.Projects.Project.t(),
  Lightning.Accounts.User.t(),
  provision_attrs()
) ::
  {:ok, Lightning.Projects.Project.t()}
  | {:error, :unauthorized | Ecto.Changeset.t() | term()}

Creates a new sandbox project by cloning from a parent project.

The creator becomes the sandbox owner, and all workflow triggers are disabled. Credentials are shared (not duplicated) between parent and sandbox.

Parameters

  • parent - Project to clone from
  • actor - User creating the sandbox (needs :owner or :admin role on parent)
  • attrs - Creation attributes (see provision_attrs/0)

Returns

  • {:ok, sandbox_project} - Successfully created sandbox
  • {:error, :unauthorized} - Actor lacks permission on parent
  • {:error, changeset} - Validation or database error

Example

{:ok, sandbox} = Sandboxes.provision(parent_project, user, %{
  name: "test-environment",
  color: "#336699",
  collaborators: [%{user_id: other_user.id, role: :editor}]
})

update_sandbox(sandbox, actor, attrs)

@spec update_sandbox(
  Lightning.Projects.Project.t() | Ecto.UUID.t(),
  Lightning.Accounts.User.t(),
  map()
) ::
  {:ok, Lightning.Projects.Project.t()}
  | {:error, :unauthorized | :not_found | Ecto.Changeset.t()}

Updates a sandbox project's basic attributes.

Parameters

  • sandbox - Sandbox project to update (or sandbox ID as string)
  • actor - User performing the update (needs :owner or :admin role on sandbox)
  • attrs - Map with :name, :color, and/or :env keys

Returns

  • {:ok, updated_sandbox} - Successfully updated sandbox
  • {:error, :unauthorized} - Actor lacks permission on sandbox
  • {:error, :not_found} - Sandbox ID not found (when using string ID)
  • {:error, changeset} - Validation error

Example

= Sandboxes.update_sandbox(sandbox, user, %{

name: "new-name",
color: "#ff6b35"

})