Skip to content

Getting Started

Dataface Cloud

This page describes Dataface Cloud, the hosted product — these features are not part of the open source dft engine.

Setting up Dataface Cloud takes three steps: connect the git repository that holds your Dataface project, create a project pointing at it, and connect your warehouse. At the end, every dashboard in your repo is live, shared, and updating on every push.

Before you start you need:

  • A git repository containing a Dataface project — a dataface.yml and a faces/ directory of dashboards. If you don't have one yet, build it locally first with the open source engine: see Installation and the Quick Guide.
  • A warehouse that Cloud can reach over the internet (see Data connections).

Sign in and create an organization

Sign up with an email address and password, or with Google or GitHub sign-in where offered (social sign-in is used only to authenticate you — it does not grant Cloud access to your repositories).

Everything in Cloud belongs to an organization: members, projects, and warehouse connections are all org-scoped. Create one with a name and a URL slug, and you become its owner. Invite teammates by email — each invitation is a single-use link that expires after seven days. Members hold one of three org roles:

  • Owner — everything, including managing other owners. An org always keeps at least one.
  • Admin — manages members, the git connection, and warehouse connections.
  • Member — uses projects and dashboards, subject to access control.

Connect your git repository

Cloud reads dashboards straight from git — the repository stays the source of truth. There are two ways to connect one:

GitHub (recommended). An org admin installs the Dataface GitHub App and picks which repositories to grant access to. If you don't have owner rights on the GitHub organization, the install becomes a request that a GitHub org owner approves; Cloud picks it up automatically once approved. After installation the granted repositories are available to projects, and every push syncs automatically via webhook.

Git URL. Any other git host works via a plain https:// remote URL. The remote must be publicly reachable (private hosts and non-HTTP schemes are rejected), and syncing is by periodic poll or an on-demand sync rather than push webhooks.

A repository connects to one organization, and each repository backs at most one project per org.

Disconnecting GitHub

Disconnecting the GitHub App (via Settings → GitHub → Disconnect) removes the GitHub connection for all projects in the org — the projects themselves are not deleted. Their git data, branches, and dashboard history are preserved.

After disconnecting you can:

  • Reconnect from the same GitHub org (re-install the App for the same GitHub organization). Cloud will automatically re-link each project to its matching repository — no manual re-configuration needed.
  • Move to a different Dataface org — disconnect, then install from the new Dataface org. The projects from the previous org stay in that org and are not re-linked to the new installation (each org is isolated).
  • Delete a project from Settings → Projects if you no longer need it. This removes all dashboard and git data and cannot be undone.

Create a project

A project binds one repository (or one subdirectory of it) to a set of dashboards. Any org member can create one.

GitHub (two-step). A table lists all repositories the GitHub App has access to — pick one and click Continue. Cloud reads the repo's default branch and tree to pre-fill the form: the project name and slug derive from the repository name, and the subdirectory is inferred from the location of your dataface.yml (or faces/ directory) in the tree.

Git URL (one step). Follow the "Use a Git URL instead" link on the repository picker, and fill in all fields manually.

In either case you can edit the pre-filled values before saving. The fields are:

  • Name and slug — the slug becomes part of the project's URLs.
  • Repository — a granted GitHub repo, or the git URL.
  • Subdirectory (optional) — where the Dataface project lives inside the repo, e.g. data/dashboards. This is what makes monorepos work: several projects can share one repo with different subdirectories.
  • Default branch — the branch your team merges to (your repo's default branch if left blank on GitHub). It must exist. Cloud treats it as pull-only: Cloud never commits to it directly.
  • Work branch (optional, defaults to dataface/<slug>) — the Cloud-owned branch where edits made in Cloud land. It must not already exist on the remote; Cloud creates it. Changes reach your default branch the same way any change does — through a pull request, which Cloud opens and keeps updated for you.

On creation Cloud runs a first sync: it fetches the default branch, registers every dashboard in faces/, and discovers the source names your YAML references. If the sync fails (bad branch, unreachable remote), nothing is half-created — fix the issue and try again.

Connect your warehouse

Dashboards name their sources in YAML (source: warehouse); Cloud maps each name to an org-level warehouse connection. After the first sync, an admin is prompted to map any unmapped sources — create a connection (PostgreSQL, Snowflake, BigQuery, or Redshift), test it, and pick the sources it serves. The full flow, per-warehouse fields, and security notes are on Data connections.

What you'll see

Once a project has a synced repo and mapped sources, its dashboards are live:

  • Dashboards track git. The dashboard list is exactly the face files in faces/ on the synced branch. Push a change and it shows up; on GitHub, sync is immediate via webhook.
  • Edits made in Cloud land on the work branch, visible immediately to the team and mergeable into the default branch via the rolling pull request. Dashboards under _drafts/ stay in a private working area until promoted — see access control.
  • Branch previews: append ?branch=<name> to preview any branch's YAML — see branch previews.
  • Freshness is governed by refresh policy — see Refresh.