Skip to content

Build and deploy your project

The Build action turns the tables in a project (or a workspace subset) into a complete Databricks Asset Bundle: table DDL, ingest pipelines, orchestration jobs, a deployment notebook, and a continuous integration workflow. Every build is an immutable snapshot you review in the app first; nothing reaches your repository until you explicitly commit it.

Before you start

Section titled “Before you start”

Run a build

Section titled “Run a build”
  1. Open your project and switch to the Build tab. (A workspace has the same Build entry, scoped to the workspace’s member tables.)
  2. Press Build. The dialog lists the functional layers with the number of in-scope tables per layer. All five layers, landing, staging, persistent staging, data vault, and data mart, build.
  3. Confirm with Build. The run appears at the top of the run list with a live status chip.

If a naming change would move the bundle’s resource keys, a confirmation step appears before the run starts, headed Bundle resource keys will change. Choose Keep existing keys to leave the deployed resources where they are, or Adopt new keys to rename them. This step only appears when DeltaVault detects the change, so most builds go straight from the layer picker to the run.

If your organization enforces a governance gate on build generation, a blocked build explains which tables are missing required properties instead of running.

Review the snapshot

Section titled “Review the snapshot”

Select a run to open its snapshot: a file tree grouped by bundle folder, with a validation badge per file.

  • Select any file to preview its full content in a drawer, with copy to clipboard.
  • Files that failed validation carry an invalid badge and list their validation errors in the drawer.
  • A table that could not be generated at all appears as an error placeholder naming the failure; the rest of the build is unaffected.

Each Build press creates a fresh snapshot. Runs are never edited in place, so the run list doubles as a history of what was generated when.

Per-source control notebooks

Section titled “Per-source control notebooks”

If your project includes a Data Vault, the snapshot also contains one control notebook per staging source that feeds it. Each control notebook runs that source’s hubs and links first, then its satellites and link satellites, so every object loads in the right tier without you sequencing anything by hand. An object fed by more than one staging source appears in every one of those sources’ control notebooks, so each source’s notebook always runs everything it needs, regardless of what else shares that object.

Commit to git

Section titled “Commit to git”

When the snapshot looks right, press Commit to git on the run.

  • The commit pushes the exact snapshot to the main branch of your connected repository, file for file.
  • Error placeholders are never committed. If some files failed validation, the confirm dialog says so; Commit anyway commits the successfully rendered files as they are.
  • After the commit succeeds, the run’s status chip changes to committed and shows the short commit hash.

A run is committed once. To ship a fix, run Build again and commit the new snapshot.

Deploy with the generated workflow

Section titled “Deploy with the generated workflow”

The bundle ships with its own deployment path; DeltaVault never pushes to your Databricks workspace.

  1. The commit includes .github/workflows/deploy-databricks-bundle.yml. On the first run, add the DATABRICKS_HOST and DATABRICKS_TOKEN repository secrets in GitHub; DeltaVault references them by name only and never stores workspace credentials.
  2. On every push that touches the bundle folder, the workflow runs databricks bundle validate and then databricks bundle deploy against your target environment.
  3. The bundle also contains src/deploy/deploy_ddl.py, an ordered, idempotent notebook that creates catalogs, schemas, and tables before the first ingest runs. Every generated job runs it as its leading task, so a fresh environment bootstraps itself.

Troubleshooting

Section titled “Troubleshooting”
  • The Commit to git button is disabled. Only a succeeded run can be committed, and you need the editor role. A running build finishes first; a failed build needs its error fixed and a new run.
  • The commit fails with a GitHub error. Check Settings, Source Control: the connection must show as connected, and the app installation must still have access to the repository. The error message from GitHub is shown verbatim.
  • Files show invalid badges. Open the file’s drawer to see the validation errors. You can still commit the rest of the snapshot with Commit anyway; the invalid files are committed as rendered, so fix the underlying metadata and rebuild when you can.
Section titled “Related guides”