CertSafari
    Databricks Certified Data Engineer Associate· Lessons

    Domain 5 · Lesson 24/33

    Databricks CLI bundle commands: validate, deploy, run, bind

    Understand the Databricks CLI to validate, deploy, and manage Declarative Automation Bundles (formerly Databricks Asset Bundles) and other workspace assets in automated CI/CD workflows

    20 min read
    2.5% of exam
    8 sources
    Published 22 Oct 2026
    Docs as of 17 Oct 2026

    What you will be able to do

    • Explain how bundle commands pick up authentication, and when to use --profile or DATABRICKS_BUNDLE_ROOT
    • Describe what databricks bundle validate checks and what it reports
    • Predict which target a deploy or run uses with and without -t
    • Explain how deployment state tracks resources by ID, and what renaming or removing a resource does
    • Choose the right deploy flag: --force, --force-lock, --auto-approve, --fail-on-active-runs or --select
    • Bring existing workspace resources under bundle management with bind, and release them with unbind
    • Set up the CLI in a CI/CD pipeline that authenticates as a service principal

    Key concept

    Bundle deployment state (tracked by ID) — Each deployment records the IDs of the resources it created and stores that state in the workspace. Name, target and root path decide which deployment a bundle is. Later deploys create, update or delete resources by matching those IDs, never by name.

    1.The bundle command group and how it authenticates

    Declarative Automation Bundles (formerly Databricks Asset Bundles) are a feature of the Databricks CLI. You describe jobs, pipelines and other resources in YAML next to your code. Then one command group, databricks bundle, checks that YAML, pushes it to a workspace and starts what it defines. The core lifecycle is init to scaffold a project, validate to check it, deploy to push it to a target, and run to start a deployed job or pipeline. Bundle work needs CLI version v0.218.0 or above, and the remote workspace must have workspace files enabled.

    Authentication follows the folder you run the command in. Inside the bundle folder, bundle commands take their workspace and credentials from databricks.yml, so a bundle whose dev target names a dev host talks to that host. To use different credentials from inside the folder, pass a configuration profile with --profile (or -p) and leave out --target. Commands that don't need the bundle's authentication can run from outside the folder. For a person working at a laptop, Databricks recommends OAuth user-to-machine (U2M) authentication.

    The CLI finds the bundle by searching the current working directory. A script that runs somewhere else can point at the project by setting the DATABRICKS_BUNDLE_ROOT environment variable. The legacy BUNDLE_ROOT name still works.

    Checkpoint 1 of 11· Check yourself

    You are inside a bundle folder whose databricks.yml sets the dev target's host to the dev workspace. You want a bundle command to use the credentials from a different configuration profile. What should you do?

    Sources123

    2.What databricks bundle validate checks

    databricks bundle validate checks that the bundle configuration files are syntactically correct, and it changes nothing in the workspace. It resolves the configuration for the chosen target and then prints a summary of the bundle's identity: the bundle name, the target, the workspace host, the deploying user, and the workspace path the bundle would deploy to.

    Default output of databricks bundle validate: the bundle identity, then the resulttext
    Name: MyBundle
    Target: dev
    Workspace:
      Host: https://my-host.cloud.databricks.com
      User: someone@example.com
      Path: /Users/someone@example.com/.bundle/MyBundle/dev
    
    Validation OK!

    Validate also checks the structure of the configuration against each resource's schema. A misspelled job property, for example, shows up as a warning because it isn't in the object's schema. In a CI/CD flow, validate is the step that catches misconfigurations such as missing libraries before anything is deployed.

    Validate stops at the configuration. It doesn't upload notebooks or build artifacts, which is deploy's job. It doesn't compare the configuration with what is already deployed. And it doesn't execute any code, so a notebook that passes validate can still fail when it runs. When you only want the identity and resource summary, databricks bundle summary prints it on its own.

    Checkpoint 2 of 11· Check yourself

    A CI pipeline runs databricks bundle validate -t staging on every pull request, and the latest run printed the bundle identity followed by "Validation OK!". What can the team conclude from this?

    Checkpoint 3 of 11· Exam question

    A data engineer runs databricks bundle validate against their project before opening a pull request. What does this command actually verify?

    Sources14

    3.Deploying to a target, and the default target

    databricks bundle deploy pushes the bundle to a remote workspace, and -t (or --target) chooses which target from the configuration to deploy. databricks bundle deploy -t dev deploys the dev target. Without -t, the CLI uses the target marked default: true. It doesn't fall back to the last target in the file, it doesn't deploy every target, and it doesn't fail for lack of a flag.

    Two targets: dev is the default, prod is used only when named with -t prodyaml
    targets:
      dev:
        default: true
      prod:
        workspace:
          host: https://<production-workspace-url>

    Settings inside a target take precedence over the top-level workspace, artifacts and resources mappings, and a target can override the value of any top-level variable. Suppose the bundle declares a warehouse_id variable with a default value. Setting warehouse_id under the variables key of the prod target changes it only for -t prod deployments. There is no need for a second variable or a separate file. How variables are declared and referenced is covered in bundle variables and target overrides.

    Checkpoint 4 of 11· Check yourself

    Your databricks.yml declares two targets: dev first, with default: true, and prod last, with its own production workspace host. A release script runs databricks bundle deploy with no -t flag. What happens?

    Checkpoint 5 of 11· Exam question

    A team's databricks.yml defines a dev target with default: true and a prod target with no default flag. An engineer runs databricks bundle deploy with no additional flags from their laptop. Which target receives the deployment?

    Checkpoint 6 of 11· Exam question

    A bundle defines a warehouse_id variable with a default value, and the prod target overrides it to point at a larger production SQL warehouse. Which mechanism in databricks.yml is being used here?

    Sources5

    4.Deployment identity and state tracked by ID

    The root_path property determines which deployment a bundle is. It defaults to ~/.bundle/${bundle.name}/${bundle.target}, so by default a deployment is identified by three things: who deploys it, the bundle name, and the target name. This is why one bundle can be deployed to dev, staging and production workspaces side by side. It also means two different bundles with the same name, target and deployer will interfere with each other.

    Each deployment records the IDs of the resources it creates and stores that state in the workspace file system. Names play no part in the matching. On the next deploy, each resource in the configuration is compared with the recorded state:

    What deploy does to each resource, based on the recorded state
    SituationWhat deploy does
    In the configuration, but not in the target workspaceCreates it
    In the configuration and already in the target workspaceUpdates it in place, including a rename
    Removed from the configuration after an earlier deployDeletes it from the target workspace

    The third row catches people out. Deleting a job's YAML block and deploying again deletes the job. A bundle forgets a resource only when you change the bundle name, the target or the workspace, and validate prints those three values so you can check them before a deploy. To remove everything a bundle deployed, databricks bundle destroy permanently deletes its previously deployed jobs, pipelines and artifacts. This can't be undone.

    Checkpoint 7 of 11· Match them up

    A team redeploys the same bundle to the same target after editing databricks.yml. Match each change to what the next deploy does in the workspace.

    Tap a term, then the definition that fits it.

    Sources13

    5.Deploy flags for checks, locks and prompts

    A deploy can be blocked by safety checks, by a lock or by a confirmation prompt. Each one has a flag that overrides it, and each flag is meant for a specific situation:

    databricks bundle deploy flags and when to use them
    FlagWhat it doesWhen to use it
    --forceOverrides validations that block a deployment, including the Git branch check and the check that protects dashboards edited in the workspaceWhen you deliberately deploy from a branch other than the target's git.branch, or want local dashboards to replace remote edits
    --force-lockForces the deployment lock to be taken, turning off the protection against concurrent deploymentsOnly after a crashed or interrupted deployment has left a stale lock file
    --auto-approveSkips interactive approvals the deployment might otherwise ask forNon-interactive runs such as a CI/CD pipeline
    --fail-on-active-runsFails the deploy if jobs or pipelines in the deployment are runningWhen a deploy must not change resources that are in the middle of a run
    -c, --cluster-idReplaces the clusters in the deployment with the given cluster IDDevelopment iteration on an existing cluster
    --selectDeploys only the named resources and their upstream dependenciesDevelopment workspaces only, not production

    --force and --force-lock are easy to mix up. --force concerns checks on what is being deployed. In production mode, a target can pin git.branch: main, and a deploy from any other branch then fails until you add --force. For dashboards, --force overwrites a dashboard that was edited in the workspace since the last deploy. Without it, that deploy fails so the remote edits aren't lost. --force-lock concerns who is deploying. The lock stops two deployments from interfering with each other, so forcing it is only safe when the earlier deploy has actually died. Development-mode targets turn the lock off for faster iteration, so stale locks are mostly a problem on shared and production targets. The other development and production mode behaviours are covered in deployment modes.

    Checkpoint 8 of 11· Match them up

    Each situation below blocks or affects a databricks bundle deploy. Match each one to the deploy flag meant for it.

    Tap a term, then the definition that fits it.

    Sources16

    6.Running a deployed job or pipeline

    databricks bundle run starts a job or pipeline that has already been deployed. You identify it by its resource key, the top-level element of the resource's YAML block, not by its display name. If you give no key, the CLI prompts you to pick from the resources available. Like deploy, run uses the default target unless -t names another one.

    Run the job with key hello_job in the dev targetbash
    databricks bundle run -t dev hello_job

    Checkpoint 9 of 11· Check yourself

    After a GitHub Actions workflow has deployed a bundle to its staging target, the next step has to start the deployed job whose resource key is integration_tests. Which command does that step run?

    Sources3

    7.Binding existing resources to a bundle, and unbinding them

    Many teams already have jobs and pipelines that were built by hand in the workspace. databricks bundle deployment bind KEY RESOURCE_ID links a resource defined in the bundle to one of these existing objects, so the bundle manages the object instead of creating a duplicate. The command shows a diff and lets you refuse the binding. Once you confirm, the next bundle deploy updates the existing object to match the bundle's configuration. Run bind with --target, and check the resource in the workspace before you bind it.

    Bind the bundle resource hello_job to an existing job by its numeric IDbash
    databricks bundle deployment bind hello_job 6565621249

    The format of RESOURCE_ID depends on the resource type, because bind looks the object up through its GET REST API endpoint. A job takes its numeric ID and a pipeline its UUID. Unity Catalog objects take their full name instead: catalog.schema for a schema, catalog.schema.volume for a volume, and catalog.schema.table for a quality monitor.

    Binding doesn't recreate data. A bound pipeline that has already written tables into a catalog keeps them, and its materialized views don't have to be recomputed. A common way to adopt an existing job is databricks bundle generate with its --bind option, which writes the job's configuration into the bundle and binds it in one step. databricks bundle deployment unbind KEY reverses this. It removes only the link between the bundle resource and the workspace object, so later deploys stop managing that object. Both commands accept --force-lock for the same stale-lock case as deploy.

    Checkpoint 10 of 11· Fill the gap

    A team built a job by hand in the workspace (job ID 6565621249) and now wants the bundle resource hello_job to manage that same job, without creating a duplicate. Which subcommand completes this command?

    databricks bundle deployment  ?  hello_job 6565621249

    Sources1

    8.Running the CLI in CI/CD as a service principal

    In a CI/CD pipeline, the CLI runs the same commands with no person at the keyboard. A typical flow runs databricks bundle validate on a pull request or a commit to main. Once validation passes, databricks bundle deploy pushes the bundle to staging or production, and databricks bundle run can start the deployed resources. GitHub Actions, Azure DevOps and Jenkins can all run these steps. In GitHub, the databricks/setup-cli action installs the CLI in the workflow.

    The pipeline should authenticate as a service principal, not as a user. Databricks also recommends service principals for production deployments, and setting a target's run_as to a service principal enforces this. For the credentials themselves, workload identity federation is the recommended method. The CI system's own identity token is exchanged for Databricks access, so no Databricks secret has to be stored. In GitHub Actions this needs three environment variables: DATABRICKS_HOST for the workspace, DATABRICKS_CLIENT_ID for the service principal's UUID, and an auth type of github-oidc.

    GitHub Actions job environment for workload identity federation with a service principalyaml
    env:
          DATABRICKS_AUTH_TYPE: github-oidc
          DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
          DATABRICKS_CLIENT_ID: ${{ secrets.DATABRICKS_CLIENT_ID }} # This is the service principal UUID.

    The older alternative stores a service principal access token as a repository secret, for example SP_TOKEN, and passes it to the CLI as DATABRICKS_TOKEN. That works, but the stored token is a secret someone has to rotate and protect, and federation removes it. Whichever method you use, a non-interactive deploy also needs --auto-approve, because a CI runner has nobody to answer an approval prompt.

    Checkpoint 11 of 11· Fill the gap

    Your GitHub Actions workflow must deploy as a service principal through workload identity federation, so no Databricks secret is stored in the repository. Which auth type completes the job environment?

    env:
          DATABRICKS_AUTH_TYPE:  ? 
          DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
          DATABRICKS_CLIENT_ID: ${{ secrets.DATABRICKS_CLIENT_ID }} # This is the service principal UUID.

    Sources4768

    Practise it for real

    Take a bundle with a job keyed hello_job through validate, deploy and run against the dev target

    1. 1.From the bundle root, run databricks bundle validate.

      Why: It catches configuration errors and shows which target, workspace host, user and path the deploy will use.

      You should see: An identity summary with Name, Target and Workspace details, ending in Validation OK!

    2. 2.Run databricks bundle deploy -t dev.

      Why: It pushes the bundle's files and resource definitions to the dev target and records each resource's ID in the deployment state.

      You should see: The job appears in the dev workspace. In development mode its name has a [dev your-short-name] prefix.

    3. 3.Run databricks bundle run -t dev hello_job.

      Why: run starts a resource that has already been deployed, and it takes the resource key, not the display name.

      You should see: A run of the deployed job starts in the dev workspace.

    4. 4.Change the job's name in the YAML, then deploy to dev again.

      Why: It shows that deployment state matches resources by ID, not by name.

      You should see: The same job is renamed, and no second job is created.

    Stuck? Get a nudge

    If deploy reports a lock held by an earlier deploy, first make sure no other deploy is still running. Only then retry with --force-lock.

    Sources

    (8)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 1.
      “Bundle commands use the settings in databricks.yml for authentication when run from inside the bundle folder.”
      ↩︎ The bundle command group and how it authenticates
      “specify a configuration profile using the --profile (or -p) flag and do not specify a --target”
      ↩︎ The bundle command group and how it authenticates
      “By default this command returns a summary of the bundle identity”
      ↩︎ What databricks bundle validate checks
      “outputs warnings if resource properties are defined in the bundle configuration files that are not found in the corresponding object's schema”
      ↩︎ What databricks bundle validate checks
      “the root_path property is what determines a bundle's unique identity”
      ↩︎ Deployment identity and state tracked by ID
      “can only be forgotten if you change the bundle name, the bundle target, or the workspace”
      ↩︎ Deployment identity and state tracked by ID
      “--force overrides Git branch validation”
      ↩︎ Deploy flags for checks, locks and prompts
      “Skip interactive approvals that might be required for deployment.”
      ↩︎ Deploy flags for checks, locks and prompts
      “It is not intended for use in production.”
      ↩︎ Deploy flags for checks, locks and prompts
      “The bind command should be used with the --target flag.”
      ↩︎ Binding existing resources to a bundle, and unbinding them
      “It's a good idea to confirm the resource in the workspace before running bind.”
      ↩︎ Binding existing resources to a bundle, and unbinding them
      “Remove the link between the resource in a bundle and its remote counterpart in a workspace.”
      ↩︎ Binding existing resources to a bundle, and unbinding them
      “tracks the resources it creates in the target workspace by their IDs”
      ↩︎ Key concept
      “Validate bundle configuration files are syntactically correct.”
      ↩︎ Exam trap 1
      “If no command options are specified, the default target as declared within the bundle configuration files is used.”
      ↩︎ Exam trap 2
      “If a resource is removed from the bundle configuration, it is removed from the target workspace if it was previously deployed.”
      ↩︎ Exam trap 3
      “It should only be used if the previous deployment crashed or was interrupted and left a stale lock file.”
      ↩︎ Exam trap 4
      “Bind does not recreate data.”
      ↩︎ Exam trap 5
      “If no command options are specified, the default target as declared within the bundle configuration files is used.”
      ↩︎ Checkpoint
      “Resource names are not used to correlate between a bundle deployment and a resource instance”
      ↩︎ Prediction
      “If a resource is removed from the bundle configuration, it is removed from the target workspace if it was previously deployed.”
      ↩︎ Checkpoint
      “It should only be used if the previous deployment crashed or was interrupted and left a stale lock file.”
      ↩︎ Checkpoint
    2. 2.
      “You must install the Databricks CLI, version v0.218.0 or above.”
      ↩︎ The bundle command group and how it authenticates
    3. 3.
      “You can run databricks bundle commands outside of the bundle root by setting the DATABRICKS_BUNDLE_ROOT environment variable.”
      ↩︎ The bundle command group and how it authenticates
      “Destroying a bundle permanently deletes a bundle's previously-deployed jobs, pipelines, and artifacts.”
      ↩︎ Deployment identity and state tracked by ID
      “The resource key is the top-level element of the resource's YAML block.”
      ↩︎ Running a deployed job or pipeline
      “you are prompted to select a resource to run from a list of available resources”
      ↩︎ Running a deployed job or pipeline
    4. 4.
      “This step ensures that misconfigurations, for example, missing libraries, are caught early.”
      ↩︎ What databricks bundle validate checks
      “Databricks recommends workload identity federation for CI/CD authentication.”
      ↩︎ Running the CLI in CI/CD as a service principal
      “Run databricks bundle validate to ensure that the databricks.yml configuration is correct. This step ensures that misconfigurations, for example, missing libraries, are caught early.”
      ↩︎ Checkpoint
    5. 5.
      “is the default target used when no target is specified for bundle commands”
      ↩︎ Deploying to a target, and the default target
      “A target can also override the values of any top-level variables.”
      ↩︎ Deploying to a target, and the default target
    6. 6.
      “Disables the deployment lock for faster iteration.”
      ↩︎ Deploy flags for checks, locks and prompts
      “Databricks recommends that you use service principals for production deployments.”
      ↩︎ Running the CLI in CI/CD as a service principal
    7. 7.
      “Use service principals, instead of users, with CI/CD.”
      ↩︎ Running the CLI in CI/CD as a service principal
      “Run: Use the Databricks CLI with Declarative Automation Bundles to automate runs in your Databricks workspaces. Run bundle resources using databricks bundle run.”
      ↩︎ Checkpoint
    8. 8.
      “A composite action that sets up the Databricks CLI in a GitHub Actions workflow.”
      ↩︎ Running the CLI in CI/CD as a service principal
      “The DATABRICKS_TOKEN unified authentication environment variable is set in the action to the SP_TOKEN you configured.”
      ↩︎ Running the CLI in CI/CD as a service principal

    Spotted a mistake, or was something unclear? Tell us.