.gitignore

@@ -7,3 +7,4 @@
 /bin
 dist/
 tests/integration/.bats
+.devbox

cli/app/env.go

@@ -222,7 +222,13 @@ synchronize your local app environment values with what is deployed live.`),
 			mergedEnv[k] = v
 		}
 
-		if !strings.Contains(recipeEnvVar, ":") {
+		// The recipe version is always carried by TYPE (RECIPE, when present,
+		// is a bare source pointer). Stamp the deployed version onto TYPE and
+		// leave RECIPE untouched so the two never drift apart.
+		if t, ok := mergedEnv["TYPE"]; ok {
+			name, _, _ := strings.Cut(t, ":")
+			mergedEnv["TYPE"] = fmt.Sprintf("%s:%s", name, version)
+		} else {
 			mergedEnv[recipeKey] = fmt.Sprintf("%s:%s", mergedEnv[recipeKey], version)
 		}
 

cli/app/new.go

@@ -32,6 +32,18 @@ deploy <domain>" to do so.
 You can see what recipes are available (i.e. values for the [recipe] argument)
 by running "abra recipe ls".
 
+In addition to short catalogue names, [recipe] also accepts arbitrary git
+URLs to use a recipe from outside the catalogue (e.g. a fork or work in
+progress). Any of these forms is accepted:
+
+  abra app new git.example.com/user/recipe
+  abra app new https://git.example.com/user/recipe
+  abra app new git@git.example.com:user/recipe
+
+In that case a RECIPE=<canonical name> line is written to the app's .env
+file so a subsequent "abra app deploy" (on this or another machine) will
+re-fetch the recipe from the same git source.
+
 Recipe commit hashes are supported values for "[version]".
 
 Passing the "--secrets/-S" flag will automatically generate secrets for your
@@ -295,7 +307,7 @@ func ensureDomainFlag(recipe recipePkg.Recipe, server string) error {
 	if appDomain == "" && !internal.NoInput {
 		prompt := &survey.Input{
 			Message: i18n.G("Specify app domain"),
-			Default: fmt.Sprintf("%s.%s", recipe.Name, server),
+			Default: fmt.Sprintf("%s.%s", recipe.ShortName(), server),
 		}
 		if err := survey.AskOne(prompt, &appDomain); err != nil {
 			return err
@@ -306,6 +318,10 @@ func ensureDomainFlag(recipe recipePkg.Recipe, server string) error {
 		return errors.New(i18n.G("no domain provided"))
 	}
 
+	if strings.ContainsAny(appDomain, "/\\") {
+		return errors.New(i18n.G("invalid domain '%s': must not contain '/' or '\\'", appDomain))
+	}
+
 	return nil
 }
 

cli/app/rollback.go

@@ -188,6 +188,12 @@ beforehand. See "abra app backup" for more.`),
 			appPkg.SetChaosVersionLabel(compose, stackName, chosenDowngrade)
 		}
 
+		// NOTE: stamp the deployed version label ourselves rather than relying
+		// on the value baked into the recipe's compose.yml. Git-URL/WIP recipes
+		// often carry a stale or missing label, which would otherwise leave the
+		// live deployment reporting the wrong version after a rollback.
+		appPkg.SetVersionLabel(compose, stackName, chosenDowngrade)
+
 		// Gather secrets
 		secretInfo, err := deploy.GatherSecretsForDeploy(cl, app, internal.ShowUnchanged)
 		if err != nil {

cli/app/upgrade.go

@@ -200,6 +200,12 @@ beforehand. See "abra app backup" for more.`),
 			appPkg.SetChaosVersionLabel(compose, stackName, chosenUpgrade)
 		}
 
+		// NOTE: stamp the deployed version label ourselves rather than relying
+		// on the value baked into the recipe's compose.yml. Git-URL/WIP recipes
+		// often carry a stale or missing label, which would otherwise leave the
+		// live deployment reporting the wrong version after an upgrade.
+		appPkg.SetVersionLabel(compose, stackName, chosenUpgrade)
+
 		envVars, err := appPkg.CheckEnv(app)
 		if err != nil {
 			log.Fatal(err)
@@ -346,9 +352,17 @@ func getReleaseNotes(
 		return errors.New(i18n.G("parsing chosen upgrade version failed: %s", err))
 	}
 
-	parsedDeployedVersion, err := tagcmp.Parse(deployMeta.Version)
-	if err != nil {
-		return errors.New(i18n.G("parsing deployment version failed: %s", err))
+	// The deployed version can be "unknown" (e.g. deployed without a version
+	// label, as is common for git-URL/work-in-progress recipes). In that case
+	// there is no lower bound to filter by, so we gather notes for every
+	// version below the chosen one instead of failing.
+	var parsedDeployedVersion tagcmp.Tag
+	haveDeployedVersion := deployMeta.Version != config.UNKNOWN_DEFAULT
+	if haveDeployedVersion {
+		parsedDeployedVersion, err = tagcmp.Parse(deployMeta.Version)
+		if err != nil {
+			return errors.New(i18n.G("parsing deployment version failed: %s", err))
+		}
 	}
 
 	for _, version := range internal.SortVersionsDesc(versions) {
@@ -357,7 +371,7 @@ func getReleaseNotes(
 			return errors.New(i18n.G("parsing recipe version failed: %s", err))
 		}
 
-		if parsedVersion.IsGreaterThan(parsedDeployedVersion) &&
+		if (!haveDeployedVersion || parsedVersion.IsGreaterThan(parsedDeployedVersion)) &&
 			parsedVersion.IsLessThan(parsedChosenUpgrade) {
 			note, err := app.Recipe.GetReleaseNotes(version, app.Domain)
 			if err != nil {
@@ -420,6 +434,12 @@ func validateUpgradeVersionArg(
 		return errors.New(i18n.G("'%s' is not a known version for %s", specificVersion, app.Recipe.Name))
 	}
 
+	// Without a known deployed version we cannot tell whether the requested
+	// version is an upgrade; trust the explicit choice rather than failing.
+	if deployMeta.Version == config.UNKNOWN_DEFAULT {
+		return nil
+	}
+
 	parsedDeployedVersion, err := tagcmp.Parse(deployMeta.Version)
 	if err != nil {
 		return errors.New(i18n.G("'%s' is not a known version", deployMeta.Version))

cli/internal/validate.go

@@ -59,9 +59,15 @@ func ValidateRecipe(args []string, cmdName string) recipe.Recipe {
 		log.Fatal(i18n.G("no recipe name provided"))
 	}
 
-	if _, ok := knownRecipes[recipeName]; !ok {
-		if !strings.Contains(recipeName, "/") {
-			log.Fatal(i18n.G("no recipe '%s' exists?", recipeName))
+	recipeName = recipe.NormalizeRecipeName(recipeName)
+
+	lookupName := recipeName
+	if i := strings.LastIndex(lookupName, ":"); i >= 0 {
+		lookupName = lookupName[:i]
+	}
+	if _, ok := knownRecipes[lookupName]; !ok {
+		if !strings.Contains(lookupName, "/") {
+			log.Fatal(i18n.G("no recipe '%s' exists? pass a git URL (e.g. https://git.example.com/user/recipe) to use a recipe outside the catalogue", lookupName))
 		}
 	}
 

cli/recipe/list.go

@@ -2,11 +2,13 @@ package recipe
 
 import (
 	"fmt"
+	"path"
 	"sort"
 	"strconv"
 	"strings"
 
 	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/config"
 	"coopcloud.tech/abra/pkg/formatter"
 	"coopcloud.tech/abra/pkg/i18n"
 	"coopcloud.tech/abra/pkg/log"
@@ -41,6 +43,7 @@ var RecipeListCommand = &cobra.Command{
 
 		headers := []string{
 			i18n.G("name"),
+			i18n.G("source"),
 			i18n.G("category"),
 			i18n.G("status"),
 			i18n.G("healthcheck"),
@@ -56,6 +59,7 @@ var RecipeListCommand = &cobra.Command{
 		for _, recipe := range recipes {
 			row := []string{
 				recipe.Name,
+				i18n.G("catalogue"),
 				recipe.Category,
 				strconv.Itoa(recipe.Features.Status),
 				recipe.Features.Healthcheck,
@@ -76,6 +80,23 @@ var RecipeListCommand = &cobra.Command{
 			}
 		}
 
+		externals := externalRecipes(catl)
+		sort.Strings(externals)
+		for _, name := range externals {
+			row := []string{
+				name,
+				i18n.G("external"),
+				"-", "-", "-", "-", "-", "-", "-",
+			}
+			if pattern != "" {
+				if !strings.Contains(name, pattern) {
+					continue
+				}
+			}
+			table.Row(row...)
+			rows = append(rows, row)
+		}
+
 		if len(rows) > 0 {
 			if internal.MachineReadable {
 				out, err := formatter.ToJSON(headers, rows)
@@ -93,6 +114,30 @@ var RecipeListCommand = &cobra.Command{
 	},
 }
 
+// externalRecipes returns canonical names of locally-cloned recipes that
+// were sourced from an arbitrary git URL (i.e. they carry a .abra-source
+// sidecar) and are not already listed in the catalogue.
+func externalRecipes(catl recipe.RecipeCatalogue) []string {
+	dirs, err := recipe.GetRecipesLocal()
+	if err != nil {
+		log.Debug(i18n.G("can't read local recipes: %s", err))
+		return nil
+	}
+
+	var names []string
+	for _, dir := range dirs {
+		canonical := recipe.ReadRecipeSource(path.Join(config.RECIPES_DIR, dir))
+		if canonical == "" {
+			continue
+		}
+		if _, inCatalogue := catl[canonical]; inCatalogue {
+			continue
+		}
+		names = append(names, canonical)
+	}
+	return names
+}
+
 var (
 	pattern string
 )

cli/recipe/upgrade.go

@@ -129,6 +129,9 @@ interface.`),
 			log.Fatal(err)
 		}
 
+		// digest pinned images shared between services are only checked once
+		digestChecked := make(map[string]bool)
+
 		for _, service := range config.Services {
 			img, err := reference.ParseNormalizedNamed(service.Image)
 			if err != nil {
@@ -178,6 +181,13 @@ interface.`),
 
 			sort.Sort(tagcmp.ByTagDesc(compatible))
 
+			if canonical, ok := img.(reference.Canonical); ok && !digestChecked[service.Image] {
+				digestChecked[service.Image] = true
+				if err := refreshDigest(recipe, img, image, canonical.Digest().String()); err != nil {
+					log.Fatal(err)
+				}
+			}
+
 			if len(compatible) == 0 && !allTags {
 				log.Info(i18n.G("no new versions available for %s, assuming %s is the latest (use -a/--all-tags to see all anyway)", image, tag))
 				continue // skip on to the next tag and don't update any compose files
@@ -364,6 +374,47 @@ interface.`),
 	},
 }
 
+// refreshDigest checks whether the current tag of a digest pinned image was
+// re-published upstream with a new digest and offers to update the pin.
+func refreshDigest(recipe recipePkg.Recipe, img reference.Named, image, digest string) error {
+	tag := img.(reference.NamedTagged).Tag()
+
+	registryDigest, err := client.GetRegistryDigest(img, tag)
+	if err != nil {
+		return err
+	}
+
+	if registryDigest == digest {
+		log.Debug(i18n.G("digest of %s:%s is up to date", image, tag))
+		return nil
+	}
+
+	log.Warn(i18n.G("%s:%s was re-published upstream (digest %s → %s)", image, tag, digest, registryDigest))
+
+	update := false
+	if !internal.NoInput {
+		prompt := &survey.Confirm{
+			Message: i18n.G("update digest of %s:%s?", image, tag),
+			Default: true,
+		}
+		if err := survey.AskOne(prompt, &update); err != nil {
+			return err
+		}
+	}
+
+	if !update {
+		return nil
+	}
+
+	if _, err := recipe.UpdateTag(image, tag); err != nil {
+		return err
+	}
+
+	log.Info(i18n.G("digest updated for %s:%s", image, tag))
+
+	return nil
+}
+
 var (
 	allTags      bool
 	createCommit bool

cmd/abra/main.go

@@ -16,7 +16,7 @@ func main() {
 		Version = "dev"
 	}
 	if Commit == "" {
-		Commit = "       "
+		Commit = "unknown-commit"
 	}
 
 	cli.Run(Version, Commit)

go.mod

@@ -21,6 +21,7 @@ require (
 	github.com/leonelquinteros/gotext v1.8.0
 	github.com/moby/sys/signal v0.7.1
 	github.com/moby/term v0.5.2
+	github.com/opencontainers/image-spec v1.1.1
 	github.com/pkg/errors v0.9.1
 	github.com/schollz/progressbar/v3 v3.19.1
 	github.com/spf13/cobra v1.10.1
@@ -105,7 +106,6 @@ require (
 	github.com/muesli/termenv v0.16.0 // indirect
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/opencontainers/go-digest v1.0.0 // indirect
-	github.com/opencontainers/image-spec v1.1.1 // indirect
 	github.com/opencontainers/runc v1.1.13 // indirect
 	github.com/opencontainers/runtime-spec v1.1.0 // indirect
 	github.com/pjbgf/sha1cd v0.7.0 // indirect

pkg/app/app.go

@@ -260,12 +260,30 @@ func ReadAppEnvFile(appFile AppFile, name AppName) (App, error) {
 func NewApp(env envfile.AppEnv, name string, appFile AppFile) (App, error) {
 	domain := env["DOMAIN"]
 
-	recipeName, exists := env["RECIPE"]
-	if !exists {
-		recipeName, exists = env["TYPE"]
-		if !exists {
-			return App{}, errors.New(i18n.G("%s is missing the TYPE env var?", name))
-		}
+	typeVar, hasType := env["TYPE"]
+	recipeVar, hasRecipe := env["RECIPE"]
+	if !hasType && !hasRecipe {
+		return App{}, errors.New(i18n.G("%s is missing the TYPE env var?", name))
+	}
+
+	// The recipe identity is taken from RECIPE when present (it records the
+	// canonical git source for externally-sourced recipes), otherwise from
+	// TYPE. The deployed version is always carried by TYPE when a TYPE line
+	// exists; only legacy apps that set RECIPE alone carry it there. RECIPE
+	// itself must stay a bare source pointer, never a versioned value.
+	identity := typeVar
+	if hasRecipe {
+		identity = recipeVar
+	}
+
+	versionSource := identity
+	if hasType {
+		versionSource = typeVar
+	}
+
+	recipeName, _, _ := strings.Cut(identity, ":")
+	if _, version, found := strings.Cut(versionSource, ":"); found && version != "" {
+		recipeName = fmt.Sprintf("%s:%s", recipeName, version)
 	}
 
 	return App{
@@ -392,11 +410,15 @@ func TemplateAppEnvSample(r recipe.Recipe, appName, server, domain string) error
 
 	newContents := strings.Replace(
 		string(read),
-		fmt.Sprintf("%s.example.com", r.Name),
+		fmt.Sprintf("%s.example.com", r.ShortName()),
 		domain,
 		-1,
 	)
 
+	if strings.Contains(r.Name, "/") {
+		newContents = injectRecipeLine(newContents, r.Name)
+	}
+
 	err = os.WriteFile(appEnvPath, []byte(newContents), 0)
 	if err != nil {
 		return err
@@ -407,6 +429,37 @@ func TemplateAppEnvSample(r recipe.Recipe, appName, server, domain string) error
 	return nil
 }
 
+// injectRecipeLine ensures the env file carries a RECIPE=<canonical name>
+// line so a downstream `abra app deploy` (potentially on another machine)
+// can re-fetch the recipe from its original git source. If a RECIPE= line
+// already exists in the copied .env.sample it is replaced; otherwise a new
+// line is inserted immediately after the TYPE= line, or appended at the
+// end if no TYPE= line is present.
+func injectRecipeLine(contents, canonicalName string) string {
+	lines := strings.Split(contents, "\n")
+	for i, line := range lines {
+		trimmed := strings.TrimLeft(line, " \t")
+		if strings.HasPrefix(trimmed, "RECIPE=") {
+			lines[i] = "RECIPE=" + canonicalName
+			return strings.Join(lines, "\n")
+		}
+	}
+	for i, line := range lines {
+		trimmed := strings.TrimLeft(line, " \t")
+		if strings.HasPrefix(trimmed, "TYPE=") {
+			out := make([]string, 0, len(lines)+1)
+			out = append(out, lines[:i+1]...)
+			out = append(out, "RECIPE="+canonicalName)
+			out = append(out, lines[i+1:]...)
+			return strings.Join(out, "\n")
+		}
+	}
+	if contents != "" && !strings.HasSuffix(contents, "\n") {
+		contents += "\n"
+	}
+	return contents + "RECIPE=" + canonicalName + "\n"
+}
+
 // SanitiseAppName makes a app name usable with Docker by replacing illegal
 // characters.
 func SanitiseAppName(name string) string {
@@ -514,10 +567,22 @@ func ExposeAllEnv(
 				_, exists := service.Environment[k]
 				if !exists {
 					value := v
-					if k == "TYPE" || k == "RECIPE" {
+					switch k {
+					case "TYPE":
 						// NOTE(d1): don't use the wrong version from the app env
-						//           since we are deploying a new version
-						value = toDeployVersion
+						//           since we are deploying a new version. Keep the
+						//           recipe name already recorded in TYPE and only
+						//           swap in the version being deployed.
+						name, _, _ := strings.Cut(v, ":")
+						if _, version, found := strings.Cut(toDeployVersion, ":"); found {
+							value = fmt.Sprintf("%s:%s", name, version)
+						} else {
+							value = name
+						}
+					case "RECIPE":
+						// RECIPE records the canonical git source only; the
+						// version is carried by TYPE, so keep it bare here.
+						value, _, _ = strings.Cut(toDeployVersion, ":")
 					}
 					service.Environment[k] = &value
 					log.Debug(i18n.G("%s: %s: %s", stackName, k, value))
@@ -642,60 +707,55 @@ func (a App) WriteRecipeVersion(version string, dryRun bool) error {
 	if err != nil {
 		return err
 	}
-	defer file.Close()
 
 	var (
-		dirtyVersion string
-		skipped      bool
-		lines        []string
-		scanner      = bufio.NewScanner(file)
+		lines   []string
+		hasType bool
+		scanner = bufio.NewScanner(file)
 	)
 
 	for scanner.Scan() {
 		line := scanner.Text()
-		if !strings.HasPrefix(line, "RECIPE=") && !strings.HasPrefix(line, "TYPE=") {
-			lines = append(lines, line)
-			continue
-		}
-
-		if strings.HasPrefix(line, "#") {
-			lines = append(lines, line)
-			continue
-		}
-
-		if strings.Contains(line, version) && !a.Recipe.Dirty && !strings.HasSuffix(line, config.DIRTY_DEFAULT) {
-			skipped = true
-			lines = append(lines, line)
-			continue
-		}
-
-		splitted := strings.Split(line, ":")
-
-		line = fmt.Sprintf("%s:%s", splitted[0], version)
 		lines = append(lines, line)
+		if strings.HasPrefix(line, "TYPE=") {
+			hasType = true
+		}
 	}
 
 	if err := scanner.Err(); err != nil {
+		file.Close()
+		log.Fatal(err)
+	}
+	file.Close()
+
+	// The recipe version is carried by a single field: TYPE when present (the
+	// standard recipe key), otherwise the legacy RECIPE key. When both exist
+	// (git-URL recipes) RECIPE stays a bare source pointer and only TYPE is
+	// versioned, so the two can never drift apart.
+	targetPrefix := "RECIPE="
+	if hasType {
+		targetPrefix = "TYPE="
+	}
+
+	for i, line := range lines {
+		if !strings.HasPrefix(line, targetPrefix) || strings.HasPrefix(line, "#") {
+			continue
+		}
+
+		name, _, _ := strings.Cut(line, ":")
+		lines[i] = fmt.Sprintf("%s:%s", name, version)
+	}
+
+	if dryRun {
+		log.Debug(i18n.G("skipping writing version %s because dry run", version))
+		return nil
+	}
+
+	if err := os.WriteFile(a.Path, []byte(strings.Join(lines, "\n")), os.ModePerm); err != nil {
 		log.Fatal(err)
 	}
 
-	if a.Recipe.Dirty && dirtyVersion != "" {
-		version = dirtyVersion
-	}
-
-	if !dryRun {
-		if err := os.WriteFile(a.Path, []byte(strings.Join(lines, "\n")), os.ModePerm); err != nil {
-			log.Fatal(err)
-		}
-	} else {
-		log.Debug(i18n.G("skipping writing version %s because dry run", version))
-	}
-
-	if !skipped {
-		log.Debug(i18n.G("version %s saved to %s.env", version, a.Domain))
-	} else {
-		log.Debug(i18n.G("skipping version %s write as already exists in %s.env", version, a.Domain))
-	}
+	log.Debug(i18n.G("version %s saved to %s.env", version, a.Domain))
 
 	return nil
 }

pkg/app/app_test.go

@@ -3,6 +3,8 @@ package app_test
 import (
 	"encoding/json"
 	"fmt"
+	"os"
+	"path/filepath"
 	"reflect"
 	"testing"
 
@@ -271,6 +273,60 @@ func TestWriteRecipeVersionOverwrite(t *testing.T) {
 	assert.Equal(t, "foo", app.Recipe.EnvVersion)
 }
 
+// TestWriteRecipeVersionSingleField ensures the version is written to exactly
+// one field: TYPE when present (even alongside a RECIPE source pointer, as with
+// git-URL recipes), otherwise the legacy RECIPE field. RECIPE must stay bare
+// when a TYPE line exists so the two can never drift apart.
+func TestWriteRecipeVersionSingleField(t *testing.T) {
+	cases := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{
+			name:  "git recipe: TYPE and RECIPE both present",
+			input: "TYPE=myrecipe\nRECIPE=git.example.com/user/myrecipe\nDOMAIN=x\n",
+			want:  "TYPE=myrecipe:1.2.3+4.5.6\nRECIPE=git.example.com/user/myrecipe\nDOMAIN=x",
+		},
+		{
+			name:  "git recipe: re-versioning replaces only TYPE",
+			input: "TYPE=myrecipe:0.1.0+1.0.0\nRECIPE=git.example.com/user/myrecipe\nDOMAIN=x\n",
+			want:  "TYPE=myrecipe:1.2.3+4.5.6\nRECIPE=git.example.com/user/myrecipe\nDOMAIN=x",
+		},
+		{
+			name:  "legacy recipe: only RECIPE present",
+			input: "RECIPE=test_recipe\nDOMAIN=x\n",
+			want:  "RECIPE=test_recipe:1.2.3+4.5.6\nDOMAIN=x",
+		},
+		{
+			name:  "catalogue recipe: only TYPE present",
+			input: "TYPE=nextcloud\nDOMAIN=x\n",
+			want:  "TYPE=nextcloud:1.2.3+4.5.6\nDOMAIN=x",
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			p := filepath.Join(t.TempDir(), "app.env")
+			if err := os.WriteFile(p, []byte(tc.input), 0o644); err != nil {
+				t.Fatal(err)
+			}
+
+			app := appPkg.App{Path: p, Domain: "x"}
+			if err := app.WriteRecipeVersion("1.2.3+4.5.6", false); err != nil {
+				t.Fatal(err)
+			}
+
+			got, err := os.ReadFile(p)
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			assert.Equal(t, tc.want, string(got))
+		})
+	}
+}
+
 func TestWriteRecipeVersionUnknown(t *testing.T) {
 	test.Setup()
 	t.Cleanup(func() { test.Teardown() })

pkg/app/inject_recipe_test.go

@@ -0,0 +1,30 @@
+package app
+
+import "testing"
+
+func TestInjectRecipeLineAfterType(t *testing.T) {
+	in := "DOMAIN=example.com\nTYPE=foo\nVERSION=1.0\n"
+	want := "DOMAIN=example.com\nTYPE=foo\nRECIPE=org/foo\nVERSION=1.0\n"
+	got := injectRecipeLine(in, "org/foo")
+	if got != want {
+		t.Errorf("injectRecipeLine inserted RECIPE in wrong position\nwant:\n%q\ngot:\n%q", want, got)
+	}
+}
+
+func TestInjectRecipeLineReplacesExisting(t *testing.T) {
+	in := "TYPE=foo\nRECIPE=old\nDOMAIN=example.com\n"
+	want := "TYPE=foo\nRECIPE=org/foo\nDOMAIN=example.com\n"
+	got := injectRecipeLine(in, "org/foo")
+	if got != want {
+		t.Errorf("injectRecipeLine should replace existing RECIPE line\nwant:\n%q\ngot:\n%q", want, got)
+	}
+}
+
+func TestInjectRecipeLineNoTypeAppends(t *testing.T) {
+	in := "DOMAIN=example.com\n"
+	want := "DOMAIN=example.com\nRECIPE=org/foo\n"
+	got := injectRecipeLine(in, "org/foo")
+	if got != want {
+		t.Errorf("injectRecipeLine should append when TYPE is missing\nwant:\n%q\ngot:\n%q", want, got)
+	}
+}

pkg/client/registry.go

@@ -4,18 +4,35 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"slices"
 
 	"coopcloud.tech/abra/pkg/i18n"
 	"github.com/containers/image/docker"
+	"github.com/containers/image/manifest"
 	"github.com/containers/image/types"
 	"github.com/distribution/reference"
+	imgspecv1 "github.com/opencontainers/image-spec/specs-go/v1"
 )
 
+func init() {
+	// NOTE: containers/image does not request OCI image indexes by default.
+	// Many multi-arch images (e.g. on Docker Hub) are published as OCI indexes
+	// and the registry refuses to serve them without the matching Accept header.
+	if !slices.Contains(manifest.DefaultRequestedManifestMIMETypes, imgspecv1.MediaTypeImageIndex) {
+		manifest.DefaultRequestedManifestMIMETypes = append(
+			manifest.DefaultRequestedManifestMIMETypes,
+			imgspecv1.MediaTypeImageIndex,
+		)
+	}
+}
+
 // GetRegistryTags retrieves all tags of an image from a container registry.
 func GetRegistryTags(img reference.Named) ([]string, error) {
 	var tags []string
 
-	ref, err := docker.ParseReference(fmt.Sprintf("//%s", img))
+	// NOTE: strip tag and digest, containers/image refuses references
+	// which have both (e.g. nextcloud:34.0.5-fpm@sha256:...)
+	ref, err := docker.ParseReference(fmt.Sprintf("//%s", reference.TrimNamed(img)))
 	if err != nil {
 		return tags, errors.New(i18n.G("failed to parse image %s, saw: %s", img, err.Error()))
 	}
@@ -28,3 +45,37 @@ func GetRegistryTags(img reference.Named) ([]string, error) {
 
 	return tags, nil
 }
+
+// GetRegistryDigest retrieves the manifest digest of an image tag from a
+// container registry. For multi-arch images, this is the digest of the image
+// index, which is what Docker resolves "image:tag" to.
+func GetRegistryDigest(img reference.Named, tag string) (string, error) {
+	tagged, err := reference.WithTag(reference.TrimNamed(img), tag)
+	if err != nil {
+		return "", errors.New(i18n.G("failed to parse image %s, saw: %s", img, err.Error()))
+	}
+
+	ref, err := docker.ParseReference(fmt.Sprintf("//%s", tagged))
+	if err != nil {
+		return "", errors.New(i18n.G("failed to parse image %s, saw: %s", tagged, err.Error()))
+	}
+
+	ctx := context.Background()
+	src, err := ref.NewImageSource(ctx, &types.SystemContext{})
+	if err != nil {
+		return "", err
+	}
+	defer src.Close()
+
+	manifestBytes, _, err := src.GetManifest(ctx, nil)
+	if err != nil {
+		return "", err
+	}
+
+	digest, err := manifest.Digest(manifestBytes)
+	if err != nil {
+		return "", err
+	}
+
+	return digest.String(), nil
+}

pkg/formatter/formatter.go

@@ -27,10 +27,16 @@ var BoldUnderlineStyle = lipgloss.NewStyle().
 	Underline(true)
 
 func ShortenID(str string) string {
+	if len(str) < 12 {
+		return str
+	}
 	return str[:12]
 }
 
 func SmallSHA(hash string) string {
+	if len(hash) < 8 {
+		return hash
+	}
 	return hash[:8]
 }
 

pkg/git/read.go

@@ -36,6 +36,11 @@ func IsClean(repoPath string) (bool, error) {
 		return false, err
 	}
 
+	// Ignore the abra-managed sidecar file that records the canonical
+	// source URL for externally-cloned recipes; it lives alongside the
+	// recipe but is not part of the upstream tree.
+	patterns = append(patterns, gitignore.ParsePattern(".abra-source", nil))
+
 	if len(patterns) > 0 {
 		worktree.Excludes = append(patterns, worktree.Excludes...)
 	}

pkg/git/read_test.go

@@ -2,6 +2,8 @@ package git
 
 import (
 	"errors"
+	"os"
+	"path/filepath"
 	"testing"
 
 	"github.com/go-git/go-git/v5"
@@ -13,3 +15,37 @@ func TestIsClean(t *testing.T) {
 	assert.Equal(t, isClean, false)
 	assert.True(t, errors.Is(err, git.ErrRepositoryNotExists))
 }
+
+// TestIsCleanIgnoresAbraSource confirms that the .abra-source sidecar
+// file written by abra next to externally-cloned recipes does not cause
+// IsClean to report the worktree as dirty.
+func TestIsCleanIgnoresAbraSource(t *testing.T) {
+	dir := t.TempDir()
+
+	if _, err := git.PlainInit(dir, false); err != nil {
+		t.Fatalf("git init failed: %s", err)
+	}
+
+	sidecar := filepath.Join(dir, ".abra-source")
+	if err := os.WriteFile(sidecar, []byte("git.example.com/u/recipe\n"), 0o644); err != nil {
+		t.Fatalf("writing sidecar failed: %s", err)
+	}
+
+	isClean, err := IsClean(dir)
+	if err != nil {
+		t.Fatalf("IsClean returned error: %s", err)
+	}
+	assert.True(t, isClean, "expected worktree with only .abra-source to be reported clean")
+
+	// Sanity check: an unrelated untracked file should still mark it dirty.
+	other := filepath.Join(dir, "random.txt")
+	if err := os.WriteFile(other, []byte("hello"), 0o644); err != nil {
+		t.Fatalf("writing extra file failed: %s", err)
+	}
+
+	isClean, err = IsClean(dir)
+	if err != nil {
+		t.Fatalf("IsClean returned error: %s", err)
+	}
+	assert.False(t, isClean, "expected worktree with unrelated untracked file to be reported dirty")
+}

pkg/recipe/compose.go

@@ -6,8 +6,10 @@ import (
 	"io/ioutil"
 	"os"
 	"path/filepath"
+	"regexp"
 	"strings"
 
+	"coopcloud.tech/abra/pkg/client"
 	"coopcloud.tech/abra/pkg/formatter"
 	"coopcloud.tech/abra/pkg/i18n"
 	"coopcloud.tech/abra/pkg/log"
@@ -110,7 +112,14 @@ func (r Recipe) GetVersionLabelLocal() (string, error) {
 	return label, nil
 }
 
+// getRegistryDigest is a variable so that it can be stubbed in tests.
+var getRegistryDigest = client.GetRegistryDigest
+
 // UpdateTag updates an image tag in-place on file system local compose files.
+// Images which are pinned to a digest (e.g. "nextcloud:34.0.5-fpm@sha256:...")
+// have their digest updated to the one of the new tag, as retrieved from the
+// container registry. Passing the current tag of a digest pinned image
+// refreshes the digest, e.g. when upstream re-published the same tag.
 func (r Recipe) UpdateTag(image, tag string) (bool, error) {
 	fullPattern := fmt.Sprintf("%s/compose**yml", r.Dir)
 	image = formatter.StripTagMeta(image)
@@ -122,6 +131,11 @@ func (r Recipe) UpdateTag(image, tag string) (bool, error) {
 
 	log.Debug(i18n.G("considering %s config(s) for tag update", strings.Join(composeFiles, ", ")))
 
+	var (
+		updated   bool
+		newDigest string
+	)
+
 	for _, composeFile := range composeFiles {
 		opts := stack.Deploy{Composefiles: []string{composeFile}}
 
@@ -140,7 +154,7 @@ func (r Recipe) UpdateTag(image, tag string) (bool, error) {
 				continue // may be a compose.$optional.yml file
 			}
 
-			img, _ := reference.ParseNormalizedNamed(service.Image)
+			img, err := reference.ParseNormalizedNamed(service.Image)
 			if err != nil {
 				return false, err
 			}
@@ -154,30 +168,60 @@ func (r Recipe) UpdateTag(image, tag string) (bool, error) {
 				continue
 			}
 
+			var composeDigest string
+			if canonical, ok := img.(reference.Canonical); ok {
+				composeDigest = canonical.Digest().String()
+			}
+
 			composeImage := formatter.StripTagMeta(reference.Path(img))
 
 			log.Debug(i18n.G("parsed %s from %s", composeTag, service.Image))
 
 			if image == composeImage {
-				bytes, err := ioutil.ReadFile(composeFile)
+				bytes, err := os.ReadFile(composeFile)
 				if err != nil {
 					return false, err
 				}
 
 				old := fmt.Sprintf("%s:%s", composeImage, composeTag)
 				new := fmt.Sprintf("%s:%s", composeImage, tag)
-				replacedBytes := strings.Replace(string(bytes), old, new, -1)
+
+				if composeDigest != "" {
+					if newDigest == "" {
+						newDigest, err = getRegistryDigest(img, tag)
+						if err != nil {
+							return false, errors.New(i18n.G("unable to retrieve digest for %s: %s", new, err))
+						}
+					}
+
+					old = fmt.Sprintf("%s@%s", old, composeDigest)
+					new = fmt.Sprintf("%s@%s", new, newDigest)
+				}
+
+				if old == new {
+					continue
+				}
+
+				// NOTE: only match the full image reference, so that "foo:1.2" does
+				// not match "foo:1.2.3" or the "foo:1.2" part of "foo:1.2@sha256:..."
+				pattern := regexp.MustCompile(regexp.QuoteMeta(old) + `([^@\w.\-]|$)`)
+				replaced := pattern.ReplaceAllString(string(bytes), new+"${1}")
+				if replaced == string(bytes) {
+					continue
+				}
 
 				log.Debug(i18n.G("updating %s to %s in %s", old, new, compose.Filename))
 
-				if err := os.WriteFile(compose.Filename, []byte(replacedBytes), 0o764); err != nil {
+				if err := os.WriteFile(compose.Filename, []byte(replaced), 0o764); err != nil {
 					return false, err
 				}
+
+				updated = true
 			}
 		}
 	}
 
-	return false, nil
+	return updated, nil
 }
 
 // UpdateLabel updates a label in-place on file system local compose files.

pkg/recipe/compose_test.go

@@ -0,0 +1,127 @@
+package recipe
+
+import (
+	"os"
+	"path"
+	"testing"
+
+	"github.com/distribution/reference"
+	"github.com/stretchr/testify/assert"
+)
+
+const (
+	oldDigest = "sha256:1111111111111111111111111111111111111111111111111111111111111111"
+	newDigest = "sha256:2222222222222222222222222222222222222222222222222222222222222222"
+)
+
+func setupUpdateTagRecipe(t *testing.T, compose string) (Recipe, string) {
+	t.Helper()
+
+	dir := t.TempDir()
+	composePath := path.Join(dir, "compose.yml")
+	envPath := path.Join(dir, ".env.sample")
+
+	assert.NoError(t, os.WriteFile(composePath, []byte(compose), 0o644))
+	assert.NoError(t, os.WriteFile(envPath, []byte("TYPE=foo\n"), 0o644))
+
+	return Recipe{
+		Name:          "foo",
+		Dir:           dir,
+		ComposePath:   composePath,
+		SampleEnvPath: envPath,
+	}, composePath
+}
+
+func stubRegistryDigest(t *testing.T, digest string) *[]string {
+	t.Helper()
+
+	var calls []string
+	orig := getRegistryDigest
+	getRegistryDigest = func(img reference.Named, tag string) (string, error) {
+		calls = append(calls, reference.Path(img)+":"+tag)
+		return digest, nil
+	}
+	t.Cleanup(func() { getRegistryDigest = orig })
+
+	return &calls
+}
+
+func TestUpdateTag(t *testing.T) {
+	testcases := []struct {
+		name     string
+		compose  string
+		image    string
+		tag      string
+		expected string
+		updated  bool
+		lookups  int
+	}{
+		{
+			name:     "plain tag",
+			compose:  "version: \"3.8\"\nservices:\n  app:\n    image: nginx:1.31.7\n",
+			image:    "nginx",
+			tag:      "1.31.8",
+			expected: "version: \"3.8\"\nservices:\n  app:\n    image: nginx:1.31.8\n",
+			updated:  true,
+		},
+		{
+			name:     "shorter tag does not mangle longer tag",
+			compose:  "version: \"3.8\"\nservices:\n  app:\n    image: nginx:1.31\n  web:\n    image: nginx:1.31.7\n",
+			image:    "nginx",
+			tag:      "1.32",
+			expected: "version: \"3.8\"\nservices:\n  app:\n    image: nginx:1.32\n  web:\n    image: nginx:1.32\n",
+			updated:  true,
+		},
+		{
+			name:     "digest is updated with tag",
+			compose:  "version: \"3.8\"\nservices:\n  app:\n    image: nextcloud:34.0.5-fpm@" + oldDigest + "\n",
+			image:    "nextcloud",
+			tag:      "34.0.6-fpm",
+			expected: "version: \"3.8\"\nservices:\n  app:\n    image: nextcloud:34.0.6-fpm@" + newDigest + "\n",
+			updated:  true,
+			lookups:  1,
+		},
+		{
+			name:     "digest is refreshed for same tag",
+			compose:  "version: \"3.8\"\nservices:\n  app:\n    image: \"nextcloud:34.0.5-fpm@" + oldDigest + "\"\n",
+			image:    "nextcloud",
+			tag:      "34.0.5-fpm",
+			expected: "version: \"3.8\"\nservices:\n  app:\n    image: \"nextcloud:34.0.5-fpm@" + newDigest + "\"\n",
+			updated:  true,
+			lookups:  1,
+		},
+		{
+			name:     "same tag without digest is a no-op",
+			compose:  "version: \"3.8\"\nservices:\n  app:\n    image: nextcloud:34.0.5-fpm\n",
+			image:    "nextcloud",
+			tag:      "34.0.5-fpm",
+			expected: "version: \"3.8\"\nservices:\n  app:\n    image: nextcloud:34.0.5-fpm\n",
+			updated:  false,
+		},
+		{
+			name:     "pinned and unpinned services sharing an image",
+			compose:  "version: \"3.8\"\nservices:\n  app:\n    image: nextcloud:34.0.5-fpm@" + oldDigest + "\n  cron:\n    image: nextcloud:34.0.5-fpm\n",
+			image:    "nextcloud",
+			tag:      "34.0.6-fpm",
+			expected: "version: \"3.8\"\nservices:\n  app:\n    image: nextcloud:34.0.6-fpm@" + newDigest + "\n  cron:\n    image: nextcloud:34.0.6-fpm\n",
+			updated:  true,
+			lookups:  1,
+		},
+	}
+
+	for _, tc := range testcases {
+		t.Run(tc.name, func(t *testing.T) {
+			r, composePath := setupUpdateTagRecipe(t, tc.compose)
+			calls := stubRegistryDigest(t, newDigest)
+
+			updated, err := r.UpdateTag(tc.image, tc.tag)
+			assert.NoError(t, err)
+			assert.Equal(t, tc.updated, updated)
+			assert.Len(t, *calls, tc.lookups)
+
+			content, err := os.ReadFile(composePath)
+			assert.NoError(t, err)
+			assert.Equal(t, tc.expected, string(content))
+		})
+	}
+}

pkg/recipe/git.go

@@ -4,6 +4,7 @@ import (
 	"errors"
 	"fmt"
 	"os"
+	"path"
 	"slices"
 	"sort"
 	"strings"
@@ -20,6 +21,11 @@ import (
 	"github.com/go-git/go-git/v5/plumbing"
 )
 
+// SourceFile is the sidecar file written next to an externally-cloned
+// recipe so the canonical "host/path" name can be recovered later (the
+// on-disk directory name escapes "/" and "." to "_", which is lossy).
+const SourceFile = ".abra-source"
+
 type EnsureContext struct {
 	Chaos            bool
 	Offline          bool
@@ -59,7 +65,7 @@ func (r Recipe) Ensure(ctx EnsureContext) error {
 			return errors.New(i18n.G(`cannot redeploy previous chaos version (%s), did you mean to use "--chaos"?`))
 		}
 
-		if _, err := r.EnsureVersion(r.EnvVersion); err != nil {
+		if _, err := r.EnsureVersionCtx(ctx, r.EnvVersion); err != nil {
 			return err
 		}
 
@@ -79,6 +85,12 @@ func (r Recipe) EnsureExists() error {
 		if err := gitPkg.Clone(r.Dir, r.GitURL); err != nil {
 			return err
 		}
+		if strings.Contains(r.Name, "/") {
+			sidecar := path.Join(r.Dir, SourceFile)
+			if err := os.WriteFile(sidecar, []byte(r.Name+"\n"), 0o644); err != nil {
+				log.Debug(i18n.G("failed to write recipe source sidecar %s: %s", sidecar, err))
+			}
+		}
 	}
 
 	if err := gitPkg.EnsureGitRepo(r.Dir); err != nil {
@@ -88,6 +100,18 @@ func (r Recipe) EnsureExists() error {
 	return nil
 }
 
+// ReadRecipeSource returns the canonical name recorded in the .abra-source
+// sidecar inside the given recipe directory, or the empty string if no
+// sidecar exists. This lets callers recover the unescaped "host/path"
+// form for externally-cloned recipes.
+func ReadRecipeSource(recipeDir string) string {
+	data, err := os.ReadFile(path.Join(recipeDir, SourceFile))
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(data))
+}
+
 // IsChaosCommit determines if a version sttring is a chaos commit or not.
 func (r Recipe) IsChaosCommit(version string) (bool, error) {
 	isChaosCommit := false
@@ -125,6 +149,13 @@ func (r Recipe) IsChaosCommit(version string) (bool, error) {
 
 // EnsureVersion checks whether a specific version exists for a recipe.
 func (r Recipe) EnsureVersion(version string) (bool, error) {
+	return r.EnsureVersionCtx(EnsureContext{}, version)
+}
+
+// EnsureVersionCtx is like EnsureVersion but is aware of the surrounding
+// EnsureContext, so that e.g. offline mode can skip network fetches when
+// resolving a branch name that isn't already available locally.
+func (r Recipe) EnsureVersionCtx(ctx EnsureContext, version string) (bool, error) {
 	isChaosCommit := false
 
 	if err := gitPkg.EnsureGitRepo(r.Dir); err != nil {
@@ -159,30 +190,46 @@ func (r Recipe) EnsureVersion(version string) (bool, error) {
 	}
 
 	var opts *git.CheckoutOptions
+	var checkedOutRef string
 	if tagRef.String() == "" {
 		log.Debug(i18n.G("attempting to checkout '%s' as chaos commit", version))
 
-		hash, err := repo.ResolveRevision(plumbing.Revision(version))
-		if err != nil {
-			log.Fatal(i18n.G("unable to resolve '%s': %s", version, err))
-		}
+		hash, hashErr := repo.ResolveRevision(plumbing.Revision(version))
+		if hashErr != nil {
+			branchHash, found, branchErr := resolveBranch(repo, version, ctx.Offline)
+			if errors.Is(branchErr, errOfflineBranchUnresolved) {
+				return isChaosCommit, errors.New(i18n.G("'%s' is not available locally and cannot be fetched in offline mode; retry without --offline", version))
+			}
+			if branchErr != nil {
+				return isChaosCommit, branchErr
+			}
+			if !found {
+				return isChaosCommit, errors.New(i18n.G("unable to resolve '%s': %s", version, hashErr))
+			}
 
-		opts = &git.CheckoutOptions{Hash: *hash, Create: false, Force: true}
-		isChaosCommit = true
+			opts = &git.CheckoutOptions{Hash: branchHash, Create: false, Force: true}
+			isChaosCommit = true
+			checkedOutRef = version
+		} else {
+			opts = &git.CheckoutOptions{Hash: *hash, Create: false, Force: true}
+			isChaosCommit = true
+			checkedOutRef = hash.String()
+		}
 	} else {
 		opts = &git.CheckoutOptions{Branch: tagRef, Create: false, Force: true}
+		checkedOutRef = tagRef.Short()
 	}
 
 	worktree, err := repo.Worktree()
 	if err != nil {
-		return isChaosCommit, nil
+		return isChaosCommit, err
 	}
 
 	if err := worktree.Checkout(opts); err != nil {
-		return isChaosCommit, nil
+		return isChaosCommit, err
 	}
 
-	log.Debug(i18n.G("successfully checked %s out to %s in %s", r.Name, tagRef.Short(), r.Dir))
+	log.Debug(i18n.G("successfully checked %s out to %s in %s", r.Name, checkedOutRef, r.Dir))
 
 	return isChaosCommit, nil
 }
@@ -485,6 +532,51 @@ func (r Recipe) GetRecipeVersions() (RecipeVersions, []string, error) {
 	return versions, uniqueWarnings, nil
 }
 
+// resolveBranch resolves name as a branch on the "origin" remote, fetching
+// it on demand into a remote-tracking ref (never into refs/heads/*, which
+// would corrupt GetDefaultBranch's local-branch-name heuristic). It returns
+// (hash, true, nil) if name is a branch, (_, false, nil) if name is
+// confirmed not to be a branch, and a non-nil error for any other failure
+// (e.g. network/auth issues) that should not be silently treated as "not a
+// branch". When offline is true, no fetch is attempted and only an
+// already-fetched remote-tracking ref is consulted.
+func resolveBranch(repo *git.Repository, name string, offline bool) (plumbing.Hash, bool, error) {
+	remoteTrackingRef := plumbing.NewRemoteReferenceName("origin", name)
+
+	if !offline {
+		refSpec := gitCfg.RefSpec(fmt.Sprintf("+refs/heads/%s:%s", name, remoteTrackingRef))
+		err := repo.Fetch(&git.FetchOptions{
+			RemoteName: "origin",
+			RefSpecs:   []gitCfg.RefSpec{refSpec},
+			Force:      true,
+		})
+		if err != nil {
+			var noMatch git.NoMatchingRefSpecError
+			switch {
+			case errors.Is(err, git.NoErrAlreadyUpToDate):
+			case errors.As(err, &noMatch):
+				return plumbing.ZeroHash, false, nil
+			default:
+				return plumbing.ZeroHash, false, errors.New(i18n.G("unable to fetch branch '%s': %s", name, err))
+			}
+		}
+	}
+
+	ref, err := repo.Reference(remoteTrackingRef, true)
+	if err != nil {
+		if offline {
+			return plumbing.ZeroHash, false, errOfflineBranchUnresolved
+		}
+		return plumbing.ZeroHash, false, errors.New(i18n.G("unable to resolve fetched branch '%s': %s", name, err))
+	}
+
+	return ref.Hash(), true, nil
+}
+
+// errOfflineBranchUnresolved is returned by resolveBranch when offline mode
+// prevents fetching a branch that isn't already available locally.
+var errOfflineBranchUnresolved = errors.New(i18n.G("not fetched and cannot resolve offline"))
+
 // Head retrieves latest HEAD metadata.
 func (r Recipe) Head() (*plumbing.Reference, error) {
 	repo, err := git.PlainOpen(r.Dir)

pkg/recipe/git_test.go

@@ -6,6 +6,8 @@ import (
 	"testing"
 
 	"coopcloud.tech/abra/pkg/test"
+	"github.com/go-git/go-git/v5"
+	"github.com/go-git/go-git/v5/plumbing"
 	"github.com/stretchr/testify/assert"
 )
 
@@ -36,3 +38,122 @@ func TestIsDirty(t *testing.T) {
 
 	assert.True(t, dirty)
 }
+
+func TestEnsureVersionBranch(t *testing.T) {
+	test.SetupWithUpstream()
+	t.Cleanup(func() { test.Teardown() })
+
+	upstream, err := git.PlainOpen(test.UpstreamRecipeDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	featureRef, err := upstream.Reference(plumbing.NewBranchReferenceName(test.FeatureBranch), true)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	r := Get(test.RecipeName)
+
+	isChaosCommit, err := r.EnsureVersion(test.FeatureBranch)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assert.True(t, isChaosCommit)
+
+	head, err := r.Head()
+	if err != nil {
+		t.Fatal(err)
+	}
+	assert.Equal(t, featureRef.Hash(), head.Hash())
+}
+
+func TestEnsureVersionBranchRefetchesOnRedeploy(t *testing.T) {
+	test.SetupWithUpstream()
+	t.Cleanup(func() { test.Teardown() })
+
+	r := Get(test.RecipeName)
+
+	if _, err := r.EnsureVersion(test.FeatureBranch); err != nil {
+		t.Fatal(err)
+	}
+
+	if err := test.CreateBranchWithCommit(test.UpstreamRecipeDir, test.FeatureBranch, "feature2.txt", "more feature work"); err != nil {
+		t.Fatal(err)
+	}
+
+	upstream, err := git.PlainOpen(test.UpstreamRecipeDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	featureRef, err := upstream.Reference(plumbing.NewBranchReferenceName(test.FeatureBranch), true)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if _, err := r.EnsureVersion(test.FeatureBranch); err != nil {
+		t.Fatal(err)
+	}
+
+	head, err := r.Head()
+	if err != nil {
+		t.Fatal(err)
+	}
+	assert.Equal(t, featureRef.Hash(), head.Hash())
+}
+
+func TestEnsureVersionOfflineUnfetchedBranch(t *testing.T) {
+	test.SetupWithUpstream()
+	t.Cleanup(func() { test.Teardown() })
+
+	r := Get(test.RecipeName)
+
+	headBefore, err := r.Head()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = r.EnsureVersionCtx(EnsureContext{Offline: true}, test.FeatureBranch)
+	assert.ErrorContains(t, err, "offline")
+
+	headAfter, err := r.Head()
+	if err != nil {
+		t.Fatal(err)
+	}
+	assert.Equal(t, headBefore.Hash(), headAfter.Hash())
+}
+
+func TestEnsureVersionUnknownNameErrors(t *testing.T) {
+	test.SetupWithUpstream()
+	t.Cleanup(func() { test.Teardown() })
+
+	r := Get(test.RecipeName)
+
+	_, err := r.EnsureVersion("does-not-exist-anywhere")
+	assert.Error(t, err)
+}
+
+func TestEnsureBranchPinnedRecipe(t *testing.T) {
+	test.SetupWithUpstream()
+	t.Cleanup(func() { test.Teardown() })
+
+	upstream, err := git.PlainOpen(test.UpstreamRecipeDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	featureRef, err := upstream.Reference(plumbing.NewBranchReferenceName(test.FeatureBranch), true)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	r := Get(test.RecipeName + ":" + test.FeatureBranch)
+
+	if err := r.Ensure(EnsureContext{}); err != nil {
+		t.Fatal(err)
+	}
+
+	head, err := r.Head()
+	if err != nil {
+		t.Fatal(err)
+	}
+	assert.Equal(t, featureRef.Hash(), head.Hash())
+}

pkg/recipe/recipe.go

@@ -8,6 +8,7 @@ import (
 	"net/url"
 	"os"
 	"path"
+	"regexp"
 	"sort"
 	"strconv"
 	"strings"
@@ -121,7 +122,84 @@ type Features struct {
 	SSO         string `json:"sso"`
 }
 
+// scpURLPattern matches SCP-style git URLs like git@host:path or git@host:port/path.
+// Captures: 1=host(:port)?, 2=path.
+var scpURLPattern = regexp.MustCompile(`^[\w.-]+@([\w.-]+(?::\d+)?):(.+)$`)
+
+// NormalizeRecipeName canonicalizes a recipe identifier to a stable
+// "host/path" form (or returns short catalog names unchanged). Accepts:
+//
+//   - https://host/path[.git][:version]
+//   - http://host/path[.git][:version]
+//   - ssh://git@host[:port]/path[.git][:version]
+//   - git@host:path[.git][:version]            (SCP-style)
+//   - host/path[.git][:version]                (already canonical)
+//   - short-name[:version]                     (catalog recipe, pass through)
+//
+// The optional trailing :version suffix is preserved verbatim. The .git
+// suffix and trailing slashes on the path are stripped so the four URL
+// forms of the same repository collapse to one canonical value.
+func NormalizeRecipeName(input string) string {
+	input = strings.TrimSpace(input)
+
+	// Split off the version suffix first, but only if it's not part of a
+	// scheme (https://) or SCP-style git@host: prefix. The simplest way is
+	// to detect those prefixes and treat the rest as the path-with-version.
+	var (
+		body    = input
+		version string
+	)
+
+	switch {
+	case strings.HasPrefix(input, "https://") || strings.HasPrefix(input, "http://") || strings.HasPrefix(input, "ssh://"):
+		u, err := url.Parse(input)
+		if err != nil {
+			return input
+		}
+		host := u.Hostname() // strip port to keep canonical form colon-free
+		p := strings.TrimPrefix(u.Path, "/")
+		p, version = splitVersion(p)
+		body = host + "/" + p
+	case scpURLPattern.MatchString(input):
+		m := scpURLPattern.FindStringSubmatch(input)
+		host := m[1]
+		if i := strings.Index(host, ":"); i >= 0 {
+			host = host[:i] // strip port
+		}
+		p, v := splitVersion(m[2])
+		body = host + "/" + p
+		version = v
+	default:
+		body, version = splitVersion(input)
+	}
+
+	body = strings.TrimSuffix(body, "/")
+	body = strings.TrimSuffix(body, ".git")
+
+	if version != "" {
+		return body + ":" + version
+	}
+	return body
+}
+
+// splitVersion separates a trailing ":version" suffix from a recipe path.
+// It only treats the final colon-separated segment as a version when it is
+// non-empty and contains no slash (a slash means the colon belonged to the
+// path, e.g. a host:port or scheme separator).
+func splitVersion(s string) (string, string) {
+	idx := strings.LastIndex(s, ":")
+	if idx < 0 {
+		return s, ""
+	}
+	candidate := s[idx+1:]
+	if candidate == "" || strings.Contains(candidate, "/") {
+		return s, ""
+	}
+	return s[:idx], candidate
+}
+
 func Get(name string) Recipe {
+	name = NormalizeRecipeName(name)
 	version := ""
 	versionRaw := ""
 	if strings.Contains(name, ":") {
@@ -209,6 +287,16 @@ func (r Recipe) String() string {
 	return out
 }
 
+// ShortName returns the final path segment of the recipe name, i.e. the
+// bare recipe name without any "host/org/" prefix carried by externally
+// sourced (git URL) recipes. For catalogue recipes it returns Name unchanged.
+func (r Recipe) ShortName() string {
+	if i := strings.LastIndex(r.Name, "/"); i >= 0 {
+		return r.Name[i+1:]
+	}
+	return r.Name
+}
+
 func escapeRecipeName(recipeName string) string {
 	recipeName = strings.ReplaceAll(recipeName, "/", "_")
 	recipeName = strings.ReplaceAll(recipeName, ".", "_")

pkg/recipe/recipe_test.go

@@ -88,6 +88,88 @@ func TestGet(t *testing.T) {
 				AbraShPath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/abra.sh"),
 			},
 		},
+		{
+			name: "https://mygit.org/myorg/cool-recipe",
+			recipe: Recipe{
+				Name:          "mygit.org/myorg/cool-recipe",
+				Dir:           path.Join(cfg.GetAbraDir(), "/recipes/mygit_org_myorg_cool-recipe"),
+				GitURL:        "https://mygit.org/myorg/cool-recipe.git",
+				SSHURL:        "ssh://git@mygit.org/myorg/cool-recipe.git",
+				ComposePath:   path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/compose.yml"),
+				ReadmePath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/README.md"),
+				SampleEnvPath: path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/.env.sample"),
+				AbraShPath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/abra.sh"),
+			},
+		},
+		{
+			name: "https://mygit.org/myorg/cool-recipe.git",
+			recipe: Recipe{
+				Name:          "mygit.org/myorg/cool-recipe",
+				Dir:           path.Join(cfg.GetAbraDir(), "/recipes/mygit_org_myorg_cool-recipe"),
+				GitURL:        "https://mygit.org/myorg/cool-recipe.git",
+				SSHURL:        "ssh://git@mygit.org/myorg/cool-recipe.git",
+				ComposePath:   path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/compose.yml"),
+				ReadmePath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/README.md"),
+				SampleEnvPath: path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/.env.sample"),
+				AbraShPath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/abra.sh"),
+			},
+		},
+		{
+			name: "https://mygit.org/myorg/cool-recipe.git:1.2.4",
+			recipe: Recipe{
+				Name:          "mygit.org/myorg/cool-recipe",
+				EnvVersion:    "1.2.4",
+				EnvVersionRaw: "1.2.4",
+				Dir:           path.Join(cfg.GetAbraDir(), "/recipes/mygit_org_myorg_cool-recipe"),
+				GitURL:        "https://mygit.org/myorg/cool-recipe.git",
+				SSHURL:        "ssh://git@mygit.org/myorg/cool-recipe.git",
+				ComposePath:   path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/compose.yml"),
+				ReadmePath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/README.md"),
+				SampleEnvPath: path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/.env.sample"),
+				AbraShPath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/abra.sh"),
+			},
+		},
+		{
+			name: "ssh://git@mygit.org/myorg/cool-recipe.git",
+			recipe: Recipe{
+				Name:          "mygit.org/myorg/cool-recipe",
+				Dir:           path.Join(cfg.GetAbraDir(), "/recipes/mygit_org_myorg_cool-recipe"),
+				GitURL:        "https://mygit.org/myorg/cool-recipe.git",
+				SSHURL:        "ssh://git@mygit.org/myorg/cool-recipe.git",
+				ComposePath:   path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/compose.yml"),
+				ReadmePath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/README.md"),
+				SampleEnvPath: path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/.env.sample"),
+				AbraShPath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/abra.sh"),
+			},
+		},
+		{
+			name: "git@mygit.org:myorg/cool-recipe.git",
+			recipe: Recipe{
+				Name:          "mygit.org/myorg/cool-recipe",
+				Dir:           path.Join(cfg.GetAbraDir(), "/recipes/mygit_org_myorg_cool-recipe"),
+				GitURL:        "https://mygit.org/myorg/cool-recipe.git",
+				SSHURL:        "ssh://git@mygit.org/myorg/cool-recipe.git",
+				ComposePath:   path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/compose.yml"),
+				ReadmePath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/README.md"),
+				SampleEnvPath: path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/.env.sample"),
+				AbraShPath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/abra.sh"),
+			},
+		},
+		{
+			name: "git@mygit.org:myorg/cool-recipe:1.2.4",
+			recipe: Recipe{
+				Name:          "mygit.org/myorg/cool-recipe",
+				EnvVersion:    "1.2.4",
+				EnvVersionRaw: "1.2.4",
+				Dir:           path.Join(cfg.GetAbraDir(), "/recipes/mygit_org_myorg_cool-recipe"),
+				GitURL:        "https://mygit.org/myorg/cool-recipe.git",
+				SSHURL:        "ssh://git@mygit.org/myorg/cool-recipe.git",
+				ComposePath:   path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/compose.yml"),
+				ReadmePath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/README.md"),
+				SampleEnvPath: path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/.env.sample"),
+				AbraShPath:    path.Join(cfg.GetAbraDir(), "recipes/mygit_org_myorg_cool-recipe/abra.sh"),
+			},
+		},
 	}
 
 	for _, tc := range testcases {
@@ -101,6 +183,49 @@ func TestGet(t *testing.T) {
 	}
 }
 
+func TestNormalizeRecipeName(t *testing.T) {
+	cases := []struct {
+		in, want string
+	}{
+		// catalog short names pass through
+		{"foo", "foo"},
+		{"foo:1.2.3", "foo:1.2.3"},
+
+		// bare host/path form
+		{"mygit.org/myorg/cool-recipe", "mygit.org/myorg/cool-recipe"},
+		{"mygit.org/myorg/cool-recipe.git", "mygit.org/myorg/cool-recipe"},
+		{"mygit.org/myorg/cool-recipe.git:1.2.3", "mygit.org/myorg/cool-recipe:1.2.3"},
+		{"mygit.org/myorg/cool-recipe/", "mygit.org/myorg/cool-recipe"},
+
+		// https://
+		{"https://mygit.org/myorg/cool-recipe", "mygit.org/myorg/cool-recipe"},
+		{"https://mygit.org/myorg/cool-recipe.git", "mygit.org/myorg/cool-recipe"},
+		{"https://mygit.org/myorg/cool-recipe.git:1.2.3", "mygit.org/myorg/cool-recipe:1.2.3"},
+		{"http://mygit.org/myorg/cool-recipe", "mygit.org/myorg/cool-recipe"},
+
+		// ssh://, with and without port
+		{"ssh://git@mygit.org/myorg/cool-recipe.git", "mygit.org/myorg/cool-recipe"},
+		{"ssh://git@mygit.org:2222/myorg/cool-recipe.git", "mygit.org/myorg/cool-recipe"},
+
+		// SCP-style git@host:path
+		{"git@mygit.org:myorg/cool-recipe", "mygit.org/myorg/cool-recipe"},
+		{"git@mygit.org:myorg/cool-recipe.git", "mygit.org/myorg/cool-recipe"},
+		{"git@mygit.org:myorg/cool-recipe:1.2.3", "mygit.org/myorg/cool-recipe:1.2.3"},
+
+		// whitespace
+		{"  https://mygit.org/myorg/cool-recipe  ", "mygit.org/myorg/cool-recipe"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.in, func(t *testing.T) {
+			got := NormalizeRecipeName(tc.in)
+			if got != tc.want {
+				t.Errorf("NormalizeRecipeName(%q) = %q, want %q", tc.in, got, tc.want)
+			}
+		})
+	}
+}
+
 func TestGetVersionLabelLocalDoesNotUseTimeoutLabel(t *testing.T) {
 	test.Setup()
 	t.Cleanup(func() { test.Teardown() })

pkg/test/test.go

@@ -8,6 +8,9 @@ import (
 
 	gitPkg "coopcloud.tech/abra/pkg/git"
 	"git.coopcloud.tech/toolshed/godotenv"
+	"github.com/go-git/go-git/v5"
+	"github.com/go-git/go-git/v5/plumbing"
+	"github.com/go-git/go-git/v5/plumbing/object"
 )
 
 var (
@@ -76,6 +79,126 @@ func Setup() {
 	}
 }
 
+// UpstreamRecipeDir is the "remote" repo used by SetupWithUpstream, kept
+// outside recipes/ so Teardown's blanket removal of $ABRA_DIR still cleans
+// it up.
+var UpstreamRecipeDir = os.ExpandEnv("$ABRA_DIR/_upstream/test_recipe")
+
+// FeatureBranch is the non-default branch created by SetupWithUpstream.
+const FeatureBranch = "feature"
+
+// SetupWithUpstream is like Setup, but the recipe under $ABRA_DIR/recipes
+// is a real clone of a separate "upstream" repo (UpstreamRecipeDir) rather
+// than a git-inited copy of the fixture. The upstream repo additionally has
+// a FeatureBranch with one extra commit not present on main, so tests can
+// exercise resolving/fetching a non-default branch as a recipe :version.
+func SetupWithUpstream() {
+	Teardown()
+
+	if err := os.Mkdir(os.ExpandEnv("$ABRA_DIR"), 0764); err != nil {
+		if !os.IsExist(err) {
+			log.Fatal(err)
+		}
+	}
+
+	if err := os.Mkdir(os.ExpandEnv("$ABRA_DIR/servers"), 0700); err != nil {
+		if !os.IsExist(err) {
+			log.Fatal(err)
+		}
+	}
+
+	if err := os.Mkdir(os.ExpandEnv("$ABRA_DIR/recipes"), 0764); err != nil {
+		if !os.IsExist(err) {
+			log.Fatal(err)
+		}
+	}
+
+	serverSrcDir := os.ExpandEnv("$PWD/../../tests/resources/test_server")
+	serverDestDir := os.ExpandEnv("$ABRA_DIR/servers/test_server")
+	if err := os.CopyFS(serverDestDir, os.DirFS(serverSrcDir)); err != nil {
+		log.Fatal(err)
+	}
+
+	if err := os.MkdirAll(path.Dir(UpstreamRecipeDir), 0764); err != nil {
+		log.Fatal(err)
+	}
+
+	recipeSrcDir := os.ExpandEnv("$PWD/../../tests/resources/test_recipe")
+	if err := os.CopyFS(UpstreamRecipeDir, os.DirFS(recipeSrcDir)); err != nil {
+		log.Fatal(err)
+	}
+
+	if err := os.WriteFile(path.Join(UpstreamRecipeDir, ".env.sample"), []byte("TYPE=test_recipe\n"), 0o644); err != nil {
+		log.Fatal(err)
+	}
+
+	if err := gitPkg.Init(UpstreamRecipeDir, true, "tester", "helo@coopcloud.tech"); err != nil {
+		log.Fatal(err)
+	}
+
+	if err := CreateBranchWithCommit(UpstreamRecipeDir, FeatureBranch, "feature.txt", "feature work"); err != nil {
+		log.Fatal(err)
+	}
+
+	recipeDestDir := os.ExpandEnv("$ABRA_DIR/recipes/test_recipe")
+	if err := gitPkg.Clone(recipeDestDir, UpstreamRecipeDir); err != nil {
+		log.Fatal(err)
+	}
+}
+
+// CreateBranchWithCommit checks out branchName in repoPath (creating it off
+// the current HEAD if it doesn't exist yet, or extending it if it does),
+// writes fileName with contents, commits it, then returns to the repo's
+// default branch (leaving the new commit reachable only via the branch's
+// ref, matching how a contributor would push a feature branch upstream
+// without switching the repo's HEAD away from main).
+func CreateBranchWithCommit(repoPath, branchName, fileName, contents string) error {
+	repo, err := git.PlainOpen(repoPath)
+	if err != nil {
+		return err
+	}
+
+	head, err := repo.Head()
+	if err != nil {
+		return err
+	}
+
+	worktree, err := repo.Worktree()
+	if err != nil {
+		return err
+	}
+
+	branchRef := plumbing.NewBranchReferenceName(branchName)
+	create := true
+	if _, err := repo.Reference(branchRef, true); err == nil {
+		create = false
+	}
+
+	checkoutOpts := &git.CheckoutOptions{Branch: branchRef, Create: create}
+	if create {
+		checkoutOpts.Hash = head.Hash()
+	}
+	if err := worktree.Checkout(checkoutOpts); err != nil {
+		return err
+	}
+
+	if err := os.WriteFile(path.Join(repoPath, fileName), []byte(contents), 0o644); err != nil {
+		return err
+	}
+
+	if _, err := worktree.Add(fileName); err != nil {
+		return err
+	}
+
+	if _, err := worktree.Commit(fileName, &git.CommitOptions{
+		Author: &object.Signature{Name: "tester", Email: "helo@coopcloud.tech"},
+	}); err != nil {
+		return err
+	}
+
+	return worktree.Checkout(&git.CheckoutOptions{Branch: head.Name()})
+}
+
 func AddEnv(envKey, envValue string) error {
 	filePath := os.ExpandEnv(fmt.Sprintf("$ABRA_DIR/servers/%s/%s.env", ServerName, AppName))