How work ships
Team → Repository → Config. Each repository says how its code reaches its environments; SeamTrail then knows which ticket is on which environment.
SeamTrail wants to know, without anyone typing it, which ticket is on which environment. It learns it from your repositories.
It works like this: Team → Repository → Config. A team lists its repositories. Each repository says how its code reaches its environments. That is all.
Open it from the team's Settings → Code & deploys. The team's Admins and Managers set it up; everyone in the team can see it.
1. Add a repository
Add repository, pick it from your GitHub connection, and answer one question: how does code reach an environment in this repo?
| Answer | What it means | How SeamTrail knows |
|---|---|---|
| Merge to main, deploy from main | Everything merges into main. A deploy takes a commit of main to stage and prod. | A merge into main is Dev. Your deploy script (or GitHub Actions, or GitHub Deployments) tells SeamTrail when stage and prod get a commit. |
| A branch for each environment | develop runs on Dev, staging on Stage, main on Prod. | A merge or push into the branch is the deploy. |
| Release branches | Work merges into develop, a release/… branch goes to Stage, merging it into main is Prod. | The merges and the release branch. |
| Versions and tags | A tag ships a version: v1.4.0-rc1 to Stage, v1.4.0 to Prod. | The tags you push. |
| By hand | Nothing reports the deploy (a store release, a manual upload). | Merges count for Dev; someone marks the rest by hand. |
2. Check its environments
The repository's page lists the environments this repository deploys to, in order, each with one line saying how code gets there:
- Dev — when code is merged or pushed into branch
main - Stage — when your deploy reports
stage - Prod — when your deploy reports
prod
Change a name, a branch or a tag; add or remove an environment; save. A docs repository can go straight to Prod while the web repository goes Dev → Stage → Prod. When two repositories use the same environment name, it is the same environment for the team.
3. Tell SeamTrail about your deploys (only for "your deploy reports")
When an environment is reached by a deploy report, the page shows one line to add to your deploy script. It sends the repository, the environment and the commit. The key is made in the org's Settings → Tools → Deploy webhook. Instead of the script you can switch on GitHub Actions (the workflow passes the environment as input env) or GitHub Deployments.
More (optional)
- Previews: a preview environment for each pull request (GitHub Deployments named
preview-…orpr-…). Shown on the ticket, never counted. - Regions: an environment that runs in several places (prod-eu, prod-us). A deploy reported as
prod-eucounts for that region.
How a ticket moves
A pull request with SEAM-76 in its branch, title or commits is merged into main, or pushed straight to it: SEAM-76 is on Dev. Your deploy script deploys commit dc43168 to prod and tells SeamTrail: SeamTrail checks that dc43168 contains the SEAM-76 merge, so SEAM-76 is on Prod. A ticket never moves backwards by itself. Each repository's page shows What SeamTrail heard from this repo: every merge and deploy, and what it did with it.
Underneath: the rules
Each repository's setup is turned into rules SeamTrail reads. The screen does not show them: you only set the simple setup, and saving it makes the rules again. This part explains what SeamTrail does underneath.
Branch rules
A branch rule says what a branch name means, and what a merge or a push into it does:
| Part of the rule | What it says |
|---|---|
| Pattern | main, release/*, env/{environment}. * is one part, ** any depth, {name} captures a part. Several alternatives with |. Regex works too. |
| Means | Trunk, Work branch, Environment branch, Release branch, Hotfix branch, or Ignore. |
| Environment | A fixed environment, the environment named by {name} in the pattern (env/qa → QA), or none. |
| Counts when | A pull request is merged into it; merged and the branch's checks pass; a commit is pushed to it; the branch is created. |
| Ticket key from | The branch name, the pull request title, its description, the commit messages. |
| Mark | Optional: the ticket is marked release or hotfix. |
Rules are read top to bottom; the first that matches decides. A branch no rule matches is left alone and shows under What SeamTrail heard from this repo as not counted.
Deploy signals
A deploy signal says how SeamTrail hears that a commit reached an environment:
| Source | How it works |
|---|---|
| SeamTrail deploy webhook | One line in any CI posts the repository, the environment name and the commit. The environment name is matched to an environment. See the webhook. |
| GitHub Deployments | A deployment status in GitHub. The environment name is matched (production-{part} names the part). |
| GitHub Actions | A finished workflow run. The workflow name is matched; an input such as env names the environment. |
| Git tag | A tag like v* means the commit is on an environment. |
| Release | A GitHub release; pre-releases and full releases can go to different environments. |
| Any CD tool | A webhook with your tool's own body; you say which fields hold the repository, the environment and the commit. |
| By hand | Mark a deploy by hand on the repository's page, for an environment no tool reports (a store release). It is in the audit log. |
For every signal SeamTrail checks that the deployed commit contains the ticket's merge commits. A ticket with code in several repositories is on an environment when all of them reached it (or any, as the team chooses).
What SeamTrail heard
Each repository's page lists everything that reached SeamTrail for that repository, and which environment it counted for. Events are kept 90 days.
When a team changes its rules, SeamTrail reads the last 30 days of events again with the new rules. A nightly pass repairs anything a missed webhook left out.
Presets (org)
Org Admins and Managers keep saved rule sets in the org's Settings → Shipping, with a default per workspace and four switches: whether teams define their own environments, whether every release order must end in Prod or Live, whether marking a deploy by hand is allowed, and who adds repositories to a team.
Where it shows
- The feature page gets a Deployed where band: one row per team, one column per environment, with how many tickets are there, the last commit and when, and what is waiting. Below it, the recent merges and deploys, and a table by ticket.
- A ticket's drawer shows its journey: its pull requests, the environments it reached and why an environment is not reached yet.
- The promotion rules use the team's environments as their environments.
- Ask the agent: "where is SEAM-76 deployed?", "how does Hands ship?", or "mark dc43168 as deployed to Live for Mobile".
Our own setup
Add each repository to its team with Merge to main, deploy from main, and let the deploy script report each deploy. SeamTrail's own deploy script does this: it reads the deploy key from ~/seamtrail/.deploy-key on the box.