Publish a case

Publishing does three things in one run: it pushes your case to GitHub, it registers the case with Fito, and it makes it public. After it succeeds, the refs it cut are frozen forever.

This page covers the first publish of a case. Publishing a correction to a case that is already live goes through the same command and takes a different path — see Correct or retire a published case.

Before you begin

• A Fito login. Registering and publishing are authenticated. See Log in from the terminal.
• An authenticated gh. Run gh auth login. The repository is created and pushed under this local account.
• A finished tree. The source work is done, the local case/solution-vX.Y.Z branch is built, and everything is committed. Both publish scripts refuse a dirty tree, because what is validated has to be exactly what is pushed.

What gets pushed

Three refs, in one push:

Ref	What it is
main	Your development branch
vX.Y.Z	A branch and a tag, both frozen
case/solution-vX.Y.Z	The exemplar solution, frozen

The repository is created public, at https://github.com/<owner>/<name>, and that URL is what learners clone.

Only if you push by hand

The vX.Y.Z branch and the vX.Y.Z tag share a name, which normally makes a push ambiguous. /fito-publish-case pushes every ref by its full name, so this never reaches you. If you ever have to recover a push yourself, that is what the full names look like:

git push origin refs/heads/v1.0.0:refs/heads/v1.0.0
git push origin refs/tags/v1.0.0:refs/tags/v1.0.0
git push origin refs/heads/case/solution-v1.0.0:refs/heads/case/solution-v1.0.0

Publish the case

1. Run the command from the case directory:

   /fito-publish-case

   Or name the directory and the repository:

   /fito-publish-case ~/code/my-case --repo my-org/broken-json-endpoint

2. Confirm the repository owner and name. A bare <name> takes its owner from FITO_PUBLISH_GITHUB_OWNER, or from your gh login. An organisation is fine — Fito only records the URL.

3. Approve the storefront description. This is the markdown a learner reads on the catalogue listing before opening the case. It is drafted from the situation, the task objective and the learning objectives, and never from anything under solution/. It is saved to .authoring/description-overview.md.

4. Let it set status: published in .case/manifest.yaml and commit that together with the description.

5. Let it run the publish. One run validates, pushes, registers and publishes.

The storefront pitch names the topic, never the move

The description is public and read before anyone enrols, and it is drafted from learning_objectives.yaml — which means the answer can reach it through a door the case files themselves were careful about.

Apply the same test to the drafted text:

Could a reader who saw only this page apply the fix?

If yes, rewrite it. Say what the case is about and what the learner will practise; leave the technique to the case. A tutorial is the exception — its steps are the method.

Flags

Flag	Required	What it does
(leading text)	No	The case directory. Defaults to .
--repo <owner>/<name>	No	The repository to create and push
--case-id <uuid>	No	A draft registered by an earlier attempt

When the publish stops

It is safe to re-run after any of these. The repository is never duplicated, and a registered draft is reused rather than re-minted.

What you see	What it means	What to do
“The working tree has uncommitted changes”	What would be validated is not what would be pushed	Commit or stash, then re-run
“The local solution branch … does not exist”	solution.yaml names a branch you have not built	Build it per the source plan, then re-run
“Your local gh account … is not your Fito account’s linked GitHub identity”	The two accounts differ	If that is intended, re-run with --accept-gh-mismatch. The confirmation is yours to give
“… is already a published Fito case”	This URL is live already	This is an update, not a first publish — see Correct or retire a published case
“The .case/ tree fails structural validation”	The ruleset rejected the tree	Fix the named files. See Validate the .case/ folder
A rejection from the Fito server, with an HTTP status	Usually an unresolvable reference, or a failed reachability ping	A missing component means running the knowledge pipeline; a failed ping means the refs did not land — check the repository on GitHub

After it succeeds

You get the backend case id, the PUBLISHED status, and the web URL where the case is now listed.

Open it as a learner would, with /fito-case-open <case-id>. That is the only way to see what you actually shipped.

The refs are now frozen. What you can and cannot change from here is the subject of the next page.

What’s next

• Correct or retire a published case — the two routes a correction can take.
• Open and work a case — what a learner meets.