> ## Documentation Index > Fetch the complete documentation index at: https://docs.getinteract.com/llms.txt > Use this file to discover all available pages before exploring further. # Custom models > Add your own semantic models to Interact by syncing Ossie YAML files from a dbt or Dataform repository on GitHub. ## Overview Custom models let you add your own tables, metrics and dimensions to the semantic layer, next to the built-in [Interact models](https://docs.getinteract.com/org-settings/semantic-layer/data-mapping.md). You write them as **Ossie YAML** files (`*.ossie.yaml`) in a GitHub repository, usually the dbt or Dataform repository that builds the tables. Interact reads the files when you sync. Keeping the models in Git means they are reviewed and versioned together with the transformations that produce the tables. **Prerequisites:** * You are an organization admin * [Data mapping](https://docs.getinteract.com/org-settings/semantic-layer/data-mapping.md) has a **Warehouse - read** connector that can read the tables your models use * A GitHub repository with one or more `*.ossie.yaml` files (see [Ossie model reference](https://docs.getinteract.com/org-settings/semantic-layer/ossie-reference.md)) * A GitHub personal access token with read access to that repository An organization has one custom semantic layer, connected to one repository. *** ## Step 1: Add a GitHub connector **1. Create a personal access token** In GitHub, go to **Settings → Developer settings → Personal access tokens** and create a token. A fine-grained token only needs **Contents: Read-only** on the repository that holds your models. > [!WARNING] > > Treat the token like a password. Interact stores it encrypted. **2. Add the connector in Interact** Go to **Settings → Connectors**, click **Add connector** and choose **GitHub**. Paste the token in **Personal access token**. **Organization** is optional. **3. Save the connector** Click **Save connector**. *** ## Step 2: Configure the semantic layer Go to **Settings → Semantic layer** and click **Configure semantic layer**. > [!NOTE] > > The button is disabled until there is an active GitHub connector. | Field | Required | Description | | - | - | - | | **Name** | Yes | A name for this semantic layer, for example `Datahub models`. | | **Framework** | Yes | The transformation tool the repository uses: **Dataform** or **dbt**. | | **GitHub connector** | Yes | The connector from step 1. | | **Repository** | Yes | `owner/repo`, or the full GitHub URL. | | **Branch** | Yes | The branch to read from. Defaults to `main`. | | **Model path** | Yes | The folder that holds the models. Defaults to `semantic_layer`. Subfolders are included. | | **Active** checkbox | No | *This semantic layer will be active and available for queries.* When unchecked, the custom models are not used in queries. Checked by default. | Click **Save**. You return to the semantic layer list. *** ## Step 3: Sync the models Click **Sync** on the **Custom models** tab. Interact reads every `*.ossie.yaml` and `*.ossie.yml` file under the model path on the chosen branch, checks it, and loads the models. Other YAML files in the folder, such as dbt `schema.yml`, are ignored. A message tells you how many files loaded and how many were skipped. > [!WARNING] > > Sync is manual. Push your changes to the branch first, then click **Sync** in Interact. Each sync replaces all custom models with what is on the branch at that moment. *** ## The Custom models tab Each dataset from your files is listed with: | Column | Description | | - | - | | **Model** | The dataset name. Badges flag problems (see below). | | **Engine** | The model format, **Ossie**. | | **Repo** | The connected repository. | | **File** | The file the dataset came from. | | **Dimensions** / **Metrics** | Number of visible dimensions and metrics. Hidden members are not counted. | | **Last sync** | When the repository was last synced. | Click a row to see the dataset's source, dimensions, metrics and relationships. ### Badges and errors | Shown | Meaning | Fix | | - | - | - | | **Unused** badge | An Interact model already has this dataset name, so your dataset is ignored. | Rename the dataset in your file and sync again. | | **N missing columns** badge | Some fields or metrics point to a column that does not exist in the source table. | Fix the expression or add the column, then sync again. | | **Something went wrong** banner | The last sync skipped invalid files, the combined model has errors, or GitHub could not be reached. The banner shows the first error. | Fix the file named in the message, push and sync again. | The column check only works for datasets whose `source` is a plain table reference (`project.dataset.table`). Datasets with a `SELECT` as source are not checked. *** ## Edit or remove the semantic layer Click **Edit** on the Semantic layer page to change the repository, branch or path. Sync again after changing them. To remove it, open **Edit** and use **Delete semantic layer** in the **Danger Zone**. This deletes the configuration and the synced models. Your Git repository is not touched. *** ## Troubleshooting > [accordion] Branch was not found > > Check the branch name and that the token can access the repository. Private repositories need a token with access to that repository. > [accordion] Repository tree is too large > > Interact reads the repository tree in one request. Very large repositories go over GitHub's limit. Use a narrower **Model path**. > [accordion] Sync loaded 0 files > > Files must end in `.ossie.yaml` or `.ossie.yml` and live under the model path. Check the path has no typo and the files are pushed to the selected branch. > [accordion] Skipped invalid Ossie files > > The message names the file and the first problem, for example a missing `datasets` list or invalid YAML. See the [Ossie model reference](https://docs.getinteract.com/org-settings/semantic-layer/ossie-reference.md). > [accordion] Cannot combine datasets: no relationship path connects these datasets > > A query asked for members from two datasets that have no relationship between them. Add a relationship from the detailed dataset to the one it looks up. See [Relationships](https://docs.getinteract.com/org-settings/semantic-layer/ossie-reference.md#relationships). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.