> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/build/v1/get-started/prerequisites/repository-setup.md).

# Repository setup

Vulcan projects live in a Git repository. When you deploy a Data Product, DataOS reads the deploy manifest rendered from `config.yaml`, which points at that repository, and pulls your files at runtime through a process called git-sync. For that to work securely, you store your Git credentials as a Secret in DataOS and reference it from `config.yaml`'s `deployment:` block.

## Prerequisites

* The DataOS CLI is installed. See [CLI setup](/build/v1/get-started/prerequisites/cli-setup.md).
* Your repository is on a supported provider: **GitHub**, **Bitbucket**, or **AWS CodeCommit**.
* You have a **personal access token** (or app password for Bitbucket) with at least read access to the repository.

## 1. Configure the `deployment:` block

Set the repo details, compute, and run-as user under `deployment:` in `config.yaml`, using `snake_case` keys:

```yaml
deployment:
  repo:
    url: <git repo url>
    base_dir: <repo-name>/<path-to-the-project>
    secret_id: <workspace>:<secret-name>   # the Git credentials Secret, created below
    sync_flags:
      - '--ref=main'           # the branch to deploy
      - '--submodules=off'
  compute: <compute-resource-name>
  run_as_user: <service-user>
```

`repo.url`, `repo.base_dir`, `compute`, and `run_as_user` are required; `repo.secret_id` and `repo.sync_flags` only apply to private repos and non-default sync behavior.

From the project root, render the manifest:

```bash
cd my-vulcan-project
vulcan create_deploy_yaml
```

This renders the DataOS Vulcan resource manifest deterministically from `config.yaml`: engine, schedule, and the API surface are all derived from the project or the `deployment:` block. There's nothing to hand-edit in the output; if a value is wrong, fix `config.yaml` and re-render. You configure the full block in [Git & deploy](/build/v1/productize/git-and-deploy.md); here you only need to wire up credentials.

## 2. Create a Git credentials Secret

Create `git-sync-secret.yml`:

```yaml
name: git-sync
version: v2alpha
type: secret
workspace: system
layer: user
description: "Secret for git-sync authentication"
secret:
  type: key-value
  data:
    GITSYNC_USERNAME: "<your-git-username>"
    GITSYNC_PASSWORD: "<your-personal-access-token>"
```

Where to get the token:

* **GitHub:** Settings → Developer settings → Personal access tokens. Grant `repo` (read) scope.
* **Bitbucket:** Personal Bitbucket settings → App passwords. Grant `read:repository:bitbucket`.
* **AWS CodeCommit:** Use your IAM username and an HTTPS Git credential from the AWS IAM console.

{% hint style="warning" %}
Do not commit this file. Once applied, the credentials are stored encrypted in DataOS. Add `git-sync-secret.yml` to your `.gitignore`.
{% endhint %}

## 3. Lint the deploy manifest

Before applying, render the manifest and validate it with `-l` (lint / dry-run) instead of creating it for real. This catches a missing required field, an unsupported engine, or an unknown key under `deployment:` before anything reaches DataOS:

```bash
vulcan create_deploy_yaml -o - | dataos-ctl resource apply --in -l
```

Fix any errors it reports in `config.yaml` and re-run this command until it passes clean.

## 4. Apply and verify

```sh
dataos-ctl resource apply -f git-sync-secret.yml
dataos-ctl resource get -t secret -n git-sync
```

## Best practices

* Use a **dedicated service account** or bot user for `GITSYNC_USERNAME`, not a personal account, so access does not break when team members leave.
* **Scope the token narrowly:** read-only access to the one repository is enough. Never grant write access unless your workflow pushes back to the repo.
* **Rotate tokens regularly** and re-apply the Secret manifest to update them.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/build/v1/get-started/prerequisites/repository-setup.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.