Guides

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:

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 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:

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:

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 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:

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, apart from the ones about a person's machine:

AllowedUser-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, 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:

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:

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:

~/.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:

KeysRule
ports, default_command and setup.runYour value replaces the repository's
setup.cache_key and setup.seed_filesYour 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:

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:

Copyright © 2026