# Ship a Config with Your Repo

> Commit a .testlane.toml so everyone who adds your project gets working setup, env and commands, and see how users approve, override and keep up with it.

By the end of this guide, your repository ships a `.testlane.toml`, and anyone can add the project with one command and no TOML:

```bash
testlane config add https://github.com/my-org/my-project
```

Every Testlane user writes a project file for each repository they work on, and most of it is the same for everyone: how to install, which env to set and which commands start the app. When each person writes it by hand, it drifts. Think of a new teammate copying an old config from a chat message, a `dev` command that works for one person and not the next, or a setup step nobody updated after the repository moved to pnpm. A `.testlane.toml` at the repository's root carries that shared part for everyone.

## Before you start

You'll need:

- Testlane installed, as [Installation](https://testlane.dev/docs/getting-started/installation) covers.
- Push access to the repository's default branch, to commit the file.

## Write the file

The file holds what describes the repository, so it's the same on every machine. Here's how a maintainer adds it:

::steps{level="3"}

### Start from a draft

You don't have to start from a blank file. In your checkout, `config detect --repo-file` reads the repository's files, like its lockfile, workspace packages and dev scripts, and prints a draft with only the keys this file may hold:

```bash
testlane config detect --repo-file > .testlane.toml
```

It reads files and runs nothing. Every line ends with why it's there: `# detected:` for a fact it read, `# guess:` for a choice the files don't settle, and `# note:` for something it leaves to you, like a build step run by nx or vite-plus. Read every guess and note, fix what's wrong and delete the comments you don't want to keep. [`config detect`](https://testlane.dev/docs/cli/top-level-verbs#config-detect) lists the rules it follows.

### Add `.testlane.toml` at the repository's root

Whether you started from the draft or not, the file ends up looking something like this:

```toml [my-project/.testlane.toml]
ports = 2
default_command = "dev"

[setup]
run = "pnpm install --frozen-lockfile"
cache_key = ["pnpm-lock.yaml"]

[env]
API_URL = "http://localhost:{port+1}"

[commands.dev]
run = "pnpm dev --port {port}"

[commands.test]
run = "pnpm test"

[hooks]
post_checkout = "echo ready: {path}"
```

It takes the same keys as a [project file](https://testlane.dev/docs/configuration/project-file), apart from the ones about a person's machine:

| Allowed | User-only, rejected here |
| --- | --- |
| `ports`, `default_command`, `setup.run`, `setup.cache_key`, `setup.seed_files`, `[env]`, `[commands]` and `[hooks]` | `repo`, `repo_path`, `worktrees_path`, `default_branch`, `editor`, `base_port` and `setup.seed_from` |

The [template variables](https://testlane.dev/docs/configuration/environment-and-templates), like `{port}` and `{path}`, work here as they do in a project file.

### Commit it to the default branch

Testlane reads the file only from the tip of the default branch, so a copy on a feature branch does nothing until it merges. Once it's on `main`, users get it the next time Testlane fetches `main`.

### Check it once it's merged

Testlane checks the file when it reads it from the default branch, and a file with an error stops every run until it's fixed. So once it's merged, run this on a machine where you've added the project:

```bash
testlane config trust my-project
```

It fetches the default branch, then shows the file and asks you to trust it. When the file has a problem, it lists every problem at once instead, each naming the repository's file and, for a user-only key, the file to move it to:

```
error(E_CONFIG): my-project:.testlane.toml: editor: user-only key; set it in my-project.toml
my-project:.testlane.toml: base_port: user-only key; set it in my-project.toml
```

::

## Add the project

On the user's side, one command writes the project file, clones the repository and shows you its `.testlane.toml`:

```bash
testlane config add https://github.com/my-org/my-project
```

```
→ wrote /home/you/.testlane/my-project.toml
→ cloning https://github.com/my-org/my-project.git (bare, partial)
my-project:.testlane.toml on origin/main would run:
  setup.run            pnpm install --frozen-lockfile
  commands.dev.run     pnpm dev --port {port}
  commands.test.run    pnpm test
  hooks.post_checkout  echo ready: {path}
--- my-project:.testlane.toml (origin/main) ---
ports = 2
default_command = "dev"
…
---
Trust my-project:.testlane.toml? [y/N] y
→ trusted my-project:.testlane.toml (sha256 b07a0b275b7f)
→ next: testlane my-project main
```

Your project file holds one line, `repo = "https://github.com/my-org/my-project.git"`, and everything else comes from the repository. The URL can also be an ssh URL like `git@github.com:my-org/my-project.git`, or a `/pull/<n>` link. The project is named after the repository, and `--name <name>` calls it something else.

On a new machine, add `--root ~/dev/testlane`, or any directory you like, so Testlane knows where to keep its clones. It creates the config directory and sets `root` in `defaults.toml` for you, as `testlane setup` does. If the repository has no `.testlane.toml`, `config add` writes the starter file instead and opens your editor.

## Approve it

The question at the end of `config add` is the trust check. A repository's file can run anything your shell can, so Testlane runs its setup, hooks and commands only after you approve that exact content. Read the summary before you answer, since it lists every command the file would run, with its `cwd`. Then answer:

- **Yes** stores the approval in the project's state file, never in the repository: the file's content and its sha256.
- **No** leaves your project file working on its own, and Testlane asks again next time.
- **`--yes`** approves without asking.

With no terminal to ask on, Testlane can't ask, so without `--yes`, `config add` or a command that checks out a workspace stops with exit `3`:

```
error(E_CONFIG): my-project:.testlane.toml is not trusted
hint: testlane config trust my-project
```

`config trust` itself gives the hint `re-run on a terminal, or pass --yes` there.

Keep this in mind for scripts and CI. Once a repository commits a `.testlane.toml`, `checkout`, `code`, `run`, `exec`, `shell`, `start` and `sync --fresh` stop until you approve it. Plain `sync` doesn't ask, and runs only the `post_sync` you approved. `list`, `info`, `ps`, `rm`, `clean` and `--dry-run` aren't affected. The approval is stored on each machine, so run `testlane config trust my-project` once on yours, and pass `--yes` on a fresh CI runner where you trust the repository's default branch.

Note that the repository's commands don't exist for Testlane until you approve the file. Before then, `testlane my-project main run dev` fails with `unknown command 'dev'`, so approve first with `config add` or `config trust`.

## Override a key

Your project file always wins, so you can change anything the repository set without touching the repository. Say you want `dev` to open a browser:

```toml [~/.testlane/my-project.toml]
repo = "https://github.com/my-org/my-project.git"

[commands.dev]
run = "pnpm dev --port {port} --open"
```

Each kind of key merges its own way:

| Keys | Rule |
| --- | --- |
| `ports`, `default_command` and `setup.run` | Your value replaces the repository's |
| `setup.cache_key` and `setup.seed_files` | Your list replaces the repository's, and the two are never combined |
| `[env]` | Merged by key |
| `[commands]` | Merged by name. Your command replaces the whole repository command, `cwd` and `env` included |
| `[hooks]` | Merged by hook name |

A key comes from your file first, then the repository's, then `defaults.toml`, then the built-in default. To see what a run will use, and where each value came from:

```bash
testlane config show my-project
```

```
default_command = "dev"                             # repo
ports = 2                                           # repo
commands.dev.run = "pnpm dev --port {port} --open"  # user
commands.test.run = "pnpm test"                     # repo
```

That's an excerpt, since the real output lists every key. Add `--json` for one object your scripts can read.

## When the file changes

When a maintainer changes the file, you approve the change before it runs. Testlane adds no fetch for it: it compares the copy on `origin/main` that your last fetch left with the version you approved. So it sees the change on the first run that fetches the default branch, like `testlane my-project main checkout --fetch`, or `config trust`. It then shows you only what changed, and asks again:

```
my-project:.testlane.toml on origin/main changed since you trusted it:
diff --git trusted/.testlane.toml origin/main/.testlane.toml
index ebed28b..40e7fe4 100644
--- trusted/.testlane.toml
+++ origin/main/.testlane.toml
@@ -12,7 +12,7 @@ API_URL = "http://localhost:{port+1}"
 run = "pnpm dev --port {port}"
 
 [commands.test]
-run = "pnpm test"
+run = "pnpm test --run"
 
 [hooks]
 post_checkout = "echo ready: {path}"
Trust my-project:.testlane.toml? [y/N]
```

If you say no, Testlane keeps running the version you approved before. With no terminal to ask on, the command stops with `changed since you trusted it` and the same `config trust` hint. `testlane doctor` shows where each project stands:

```
WARN project my-project: repo file: .testlane.toml on origin/main changed since approval — run `testlane config trust my-project`
```

When the file is deleted upstream, Testlane drops the approval and goes back to your project file on its own.

## Why a pull request can't change what runs

Testlane reads `.testlane.toml` only from the tip of the default branch in its own clone, `origin/<default>`. It never reads it from the branch, pull request or commit you check out, and checking out a pull request or another branch never moves that tip. So a pull request that edits `.testlane.toml`, even one from a fork, changes nothing on your machine: `testlane my-project 42 run dev` runs the `dev` you approved, with the setup and hooks you approved.

The change reaches you only after it merges, and then only as a diff you approve.

Keep in mind that this protects Testlane's config, not the code the commands run. `pnpm dev` still runs the scripts in the pull request's own `package.json`, so read a stranger's changes before you run them.

## Where to go next

Here's where to go from here:

- [Commands and Hooks](https://testlane.dev/docs/configuration/commands-and-hooks#from-the-repository) has the merge rules for `[commands]` and `[hooks]`.
- [Top-level verbs](https://testlane.dev/docs/cli/top-level-verbs#config) has every flag of `config add`, `config show` and `config trust`.
- [Project file](https://testlane.dev/docs/configuration/project-file) says which keys a repository can set.
- [Troubleshooting](https://testlane.dev/docs/guides/troubleshooting) starts with `doctor` when something doesn't work.
