# Connect your product

> Connect your product to Ondaclip: install the Ondaclip GitHub App, then follow the seven steps in the studio through to your first shoot.

Connecting a product takes seven steps in the studio wizard. Each step is
checked automatically, and you can come back to any of them.

## Before you start

- A web app deployed to an environment Ondaclip is allowed to film (DEV by
  default).
- Its repository on GitHub.
- A place for the shoots to run: **Ondaclip Cloud** (nothing to prepare), or
  **your infrastructure**, meaning a Google Cloud project of your own
  (usually the one for that environment) and a project admin to run one
  command. See [where it runs](/docs/where-it-runs/).

## 1. The product

Give it a name, choose the languages for its videos (`en-US`, `fr-CA`,
`es-MX`) and the environment to film: `dev`, `staging` or `production`. DEV
is the safe default. On a live environment, only film screens without real
customer data.

## 2. GitHub

Install the **Ondaclip GitHub App** on your app's repository. The studio
reads the code and proposes changes as pull requests. A person always merges
them.

Then choose the branch and the Ondaclip folder: `.ondaclip` at the root, like
`.github` (in a monorepo, `apps/web/.ondaclip`).

- No folder yet? The studio proposes a starter folder in a pull request, with
  `config.yaml`, one example tutorial, `publication.yaml` and a `.gitignore`
  for `output/`.
- Already have a `config.yaml`? The next steps are prefilled from it. Run
  each check to confirm.

Ondaclip never asks for a branch of its own. The branches it creates are
named `ondaclip/…`: `ondaclip/setup-<product>`, `ondaclip/spec-…`,
`ondaclip/testids-…`.

## 3. Where it runs

Choose one of two options ([compare them](/docs/where-it-runs/)).

**Ondaclip Cloud.** Select it and the step is done. Ondaclip hosts the
shoots, the demo accounts and the videos, and there's nothing for you to run.
The Free plan and the trial use this option.

**Your infrastructure.** Enter the Google Cloud project where the shoots will
run. The studio needs setup permissions once: it shows one command for an
admin to run in Cloud Shell (you can email it to them). It then shows its
plan (two accounts with narrow roles, a private storage space, a machine
template and a secret for the demo accounts), creates whatever is missing,
and **gives the setup permissions back**. It keeps only what it needs day to
day: starting runs and reading results. Then choose where to publish the
videos: a folder in a private storage space in your project. If your app
already reads videos from a folder, use that folder.

## 4. Demo accounts

Fictitious accounts the videos sign in with, one per role (for example
`client`). They're stored encrypted (by Ondaclip on Ondaclip Cloud, or in
your project's Secret Manager on your infrastructure), used only to sign in
during your shoots, and never shown again, not even to you. A tutorial picks
an account by its role. If your app has no sign-in, you don't need an
account.

## 5. App to film

The URL of the deployed app. Ondaclip is allowed to open only this URL. Say
who can access it: anyone (the app has its own sign-in), or Google accounts
only (Identity-Aware Proxy). Describe the sign-in form, then run the test:
the studio signs in off camera and opens the home page. Does your app only
support Google or Microsoft sign-in through Firebase? Use
[a signed token](/docs/signed-token/) (your infrastructure only).

## 6. AI assistant

The assistant fixes failed shoots, reviews clips and drafts new tutorials.
On Ondaclip Cloud, Ondaclip runs it. On your infrastructure, its model runs
in your project: `agy` (Gemini) or `claude-code` (Claude; enable it in Model
Garden first).

## 7. Go live

Once every step is done, set the product live. You can then film, review and
publish its tutorials. Next: [your first tutorial](/docs/first-tutorial/).

## Film a branch on a preview

New features often live on a branch, deployed to a preview URL (a Firebase
Hosting preview channel, for example). Ondaclip can film them before they
reach DEV.

1. **Allow the live host and its previews, once.** In `.ondaclip/config.yaml`,
   write the DEV guard so it matches both:

   ```yaml
   devGuard:
     appHostPattern: '^my-site(--[a-z0-9-]+)?\.web\.app$'
   ```

   `my-site.web.app` and `my-site--my-feature-abc123.web.app` both pass.
   Any other host still stops the shoot.
2. **Let your API accept the previews.** If the app calls an API from the
   browser, the API's CORS rules must accept the preview origins. Add a
   pattern to your API code once (same idea as the guard). Make sure a
   regular API release doesn't remove it, or every preview shoot will fail.
3. **Keep the preview alive.** Preview channels expire. Deploy with a long
   expiry (for example `--expires 30d`) and reuse the same channel name, so
   the URL stays the same between deploys.
4. **Check and film the branch for a single run.** Since v0.74.0, `check` and
   `film` accept `ref` (the branch) and `appUrl` (the preview URL). The
   product keeps its usual branch and URL.
5. **Or change the filmed URL.** `update_product {appUrl}` changes the URL
   Ondaclip films for every run, until you switch back to the live host.
   Ready to film checks that the guard allows it.
6. **Don't publish too early.** Clips filmed on a branch show up in the
   product's review like any other clip. Review them, but only publish them
   after the branch is merged.

To film a new feature in a single language first, give the tutorial
`locales: [en-US]` (since v0.74.0). See [the tutorial file](/docs/tutorial-format/).

## Add a product to a repository with several products

A monorepo (a dashboard, an admin panel, mobile apps) keeps a single
`.ondaclip/` folder. To add another app as a product:

1. **Add its block under `products:`** in `.ondaclip/config.yaml`:
   - `name`: the name shown in the studio;
   - `tutorials` and `publication`: its folders (default `<id>/tutorials/`
     and `<id>/publication.yaml`);
   - `locales`: only if it differs from the shared setting;
   - `devGuard.appHostPattern`: the host of this app only (and its previews);
   - `cloud.appUrl`: the URL to film;
   - `publish.targets`: its own destination (your infrastructure only; never
     another product's destination);
   - `freshness.appPaths`: the folders of this app and the packages it uses.

   See [several products in one repository](/docs/configuration/#several-products-in-one-repository).
2. **Check the file**: `validate_config` shows what each product gets.
3. **Merge it** into the branch Ondaclip watches.
4. **Add the product**: `add_product` (or Add a product in the studio).
5. **Connect GitHub**: `setup_product` step `github` with `product`, the id
   of its block.
6. **Where it runs**: `setup_product` step `gcp` (your infrastructure).
   Since v0.74.0, if another product in the workspace uses the same Google
   Cloud project, its setup is reused, so the admin doesn't have to run
   another command. Or use step `cloud` for Ondaclip Cloud.
7. **Demo accounts**: reuse another product's accounts in the workspace with
   `update_product {accountsFrom}` (since v0.73.0), or go to Settings, Demo
   accounts in the studio.
8. **The app**: `setup_product` step `app` (URL, sign-in), then the test
   sign-in.
9. **Ready to film**: `readiness` lists what's left. Once every check
   passes, film the first tutorial.

Source: https://ondaclip.com/docs/connect-your-product/