Plant Git and Imports

How a change to your plant reaches the floor: commit, push, import and promote, and what to do when a step doesn't go through.

Most teams change a routing or an instruction and hope the floor picks up the right version. In Threaded, your plant lives in a git repo that Threaded hosts, and every version the floor runs is a commit you can point to. A change reaches the floor in four steps: commit, push, import and promote. Each step is separate, so you can share work in progress without touching the floor, and choose when the floor moves.

#What it is

  • Your workspace. Everyone who opens Plant gets their own workspace. Edits there are drafts that only you can see.
  • Commit shares your changes with your organization. Commits go to the repo’s working branch, dev. Everyone sees them in Plant. Run doesn’t.
  • Push takes everything committed since the last push and puts it on the repo’s main branch as one commit. Each push starts an import into Run.
  • Import reads a commit from main, checks it with plantformat and loads it into Run. An imported commit is Ready.
  • Promote makes a Ready commit the plant’s Head. The head is the version the floor runs.
Your workspace ──Commit──▶ dev ──Push──▶ main ──Import──▶ Ready ──Promote──▶ Head (the floor)

#Rules

  • Only Owners and Editors can commit, push, import and promote. View All members can change their own workspace, but can’t commit.
  • Push, imports and promoting need Run, which is turned on per organization. See Feature Access and Billing.
  • main changes only by Push in Threaded. A direct git push to main is refused, from the app, the AI or your own computer. Push to dev instead.
  • A push is refused when the committed plant has errors. Warnings don’t block it.
  • Pushing doesn’t promote. The floor keeps running the current head until someone promotes the new commit.
  • The repo must hold exactly one plant.yaml.
  • Work orders stay on the plant version they were created on. Promoting changes what new work orders, Run › Instructions and the floor map use. The floor keeps showing older versions while they still have open work orders.
  • Each push is named by the short SHA of its commit on main, such as Push 3f2a91c.

#In the app

#Commit

As you edit in Code, each file saves to your workspace after a moment and the editor shows Draft saved. Only you can see drafts.

When you’re ready to share, click Commit in Plant’s toolbar. The Commit Changes page lists every file you changed since you last committed, with its line changes. Add a Commit note and click Commit. Everyone in your organization then sees your changes in Plant.

Your workspace picks up other people’s commits about once a minute, and says Updated with changes from {names}. If you and someone else changed the same lines, Commit asks what to keep:

  • Keep mine: where you both changed the same lines, keep your version.
  • Use theirs: keep the committed version.
  • Ask the assistant to combine: the AI merges both versions line by line, checks the plant and commits.

Everything else is combined for you.

#Push

Click Push in Plant’s toolbar. The Push Changes page shows everything committed since the last push: the commits and their notes, each changed file with its diff, and the plant’s Checks.

  1. Check the changes. If the plant doesn’t pass its checks, Push is blocked: fix the errors in Plant, commit, then come back.
  2. Edit the Push notes if you want. They start from the commit notes.
  3. Click Push.

The page then follows the import: Push {sha} is merged. Importing it into Run…, then Push {sha} is imported into Run. Promote it from the plant git imports when you are ready. If you have uncommitted changes, the page warns that they won’t be in this push.

#Import

Every push to main is imported by itself. Threaded fetches the commit, finds the plant, checks it with plantformat and loads it. If a newer push arrives first, the older import is cancelled.

To import a commit by hand, open Admin › Plant git imports, click Import SHA, paste the 40-character commit SHA and click Import SHA.

Importing doesn’t change the floor.

#Promote

In Admin › Plant git imports, find the commit and click Promote. Only a Ready commit that isn’t already the head can be promoted.

#Admin › Plant git imports

Open the Admin gear and choose Plant git imports. Each row is a commit:

  • SHA, with Head on the live commit and Tip on the latest pushed commit when it isn’t the head.
  • Branch, Commit message, Summary (plant name, nodes and parts), Updated and Error.
  • Status: In progress while it’s queued, fetching, validating or loading, then Ready or Failed. A cancelled import shows Failed with Cancelled under it.

Row actions:

  • View logs: the import’s status timeline, log lines, validation issues and summary.
  • Promote: make a Ready commit the head.
  • Retry: import a commit again after it failed or was cancelled.

The page refreshes by itself while an import is in progress. Click Refresh to check now.

#When an import fails

The person who pushed, or who clicked Import SHA or Retry, gets an email if they’re an Owner or Editor. It says which phase failed and that the plant was not updated. Click View import log in the email to see why.

Fix the problem in Plant, commit and push again, or click Retry.

#Troubleshooting

A commit shows Ready, but Promote does nothing. The import record says Ready, but the plant commit behind it is missing, for example after Run’s records were cleared. Click Import SHA and paste that commit’s SHA. Threaded imports it again, and you can then promote it. Committing or pushing again doesn’t fix it, because the commit that’s already on main is the one that needs its plant rebuilt.

Push says there’s nothing new to push. Nothing has been committed since the last push. Commit your changes in Plant first.

Push says someone else just pushed. Another push landed while you were reviewing. Click Review again to see the new changes, then push.

Push says the plant did not pass its checks. The committed plant has errors. Open Validate in Plant’s toolbar, fix each error, commit, and push again.

A push went through, but Run hasn’t picked it up. Click Refresh, or Open imports to check the import on Admin › Plant git imports.

#From the CLI or API

  • Validate a plant. threaded plantformat validate <plant-folder> checks a plant on your computer. It prints issues and exits with an error when there’s at least one error. Warnings aren’t failures.
  • Work on the repo with git. threaded plant remote prints your organization’s plant repo URL. threaded plant setup-git sets up a git credential helper for it. Push your work to dev (git push origin HEAD:refs/heads/dev). main only moves by Push in Threaded.
  • Imports and promote. No dedicated commands yet. Use threaded api call with these operations:
    • run_format_plant_commits_list: every commit the importer has found, with its status (ready, failed, cancelled, or queued, fetching, validating, loading while in progress).
    • run_format_plant_commits_import: import a SHA (the same as Import SHA).
    • run_format_plant_commits_promote: promote a commit. It takes the plant commit’s UUID from the list, not the SHA.
    • run_format_plant_import_attempts_logs and run_format_plant_import_attempts_retry: read an import’s logs, or retry it.
  • Push. run_format_plant_releases_preview shows what a push would include, run_format_plant_releases_list lists past pushes, and run_format_plant_releases_retrieve reads one push. Preview, the push list, reading one push, and Push all need a person signed in as an Owner or Editor. API tokens and the AI assistant can’t use them.

For example, to list imports:

threaded api call --operation-id run_format_plant_commits_list --path organization_uuid=<org_uuid>