Allow digests in docker images

For the nextcloud update we need to be able to indicate the
digest of the docker image, as the docker tag is the same
for the vulnerable and the fixed docker image.
This avoids 'abra update' to re-install with a warning an
old image if the connection to docker hub fails.

.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))