Add Fir generation support to heroku_app_release

Author: heroku-johnny

docs/resources/app_release.md

@@ -13,22 +13,68 @@ resource.
 
 An app release represents a combination of code, config vars and add-ons for an app on Heroku.
 
+## Generation Compatibility
+
+This resource supports both Cedar and Fir generation apps with different artifact types:
+
+* **Cedar generation apps**: Use `slug_id` (traditional slugs)
+* **Fir generation apps**: Use `oci_image` (OCI container images)
+
 ~> **NOTE:**
-This resource requires the slug be uploaded to Heroku using [`heroku_slug`](slug.html)
-or with external tooling prior to running terraform.
+For Cedar apps, the slug must be uploaded to Heroku using [`heroku_slug`](slug.html) or external tooling.
+For Fir apps, the OCI image is typically created by [`heroku_build`](build.html) and can be promoted between apps.
 
 ## Example Usage
-```hcl-terraform
-resource "heroku_app" "foobar" {
-    name = "foobar"
-    region = "us"
+
+### Cedar Generation (Traditional Slugs)
+
+```hcl
+resource "heroku_app" "cedar_app" {
+  name   = "my-cedar-app"
+  region = "us"
 }
 
-# Upload your slug
+# Upload your slug using heroku_slug or external tooling
 
-resource "heroku_app_release" "foobar-release" {
-    app_id = heroku_app.foobar.id
-    slug_id = "01234567-89ab-cdef-0123-456789abcdef"
+resource "heroku_app_release" "cedar_release" {
+  app_id      = heroku_app.cedar_app.id
+  slug_id     = "01234567-89ab-cdef-0123-456789abcdef"
+  description = "Deploy version 1.2.3"
+}
+```
+
+### Fir Generation (OCI Images)
+
+```hcl
+resource "heroku_space" "fir_space" {
+  name         = "my-fir-space"
+  organization = "my-org"
+  region       = "virginia"
+  generation   = "fir"
+}
+
+resource "heroku_app" "fir_app" {
+  name   = "my-fir-app"
+  region = heroku_space.fir_space.region
+  space  = heroku_space.fir_space.name
+  organization {
+    name = heroku_space.fir_space.organization
+  }
+}
+
+# Build creates an OCI image in Fir generation
+resource "heroku_build" "fir_build" {
+  app_id = heroku_app.fir_app.id
+  source {
+    path = "."
+  }
+}
+
+# Promote the OCI image to another app or environment
+resource "heroku_app_release" "fir_release" {
+  app_id      = heroku_app.fir_app.id
+  oci_image   = "7f668938-7999-48a7-ad28-c24cbd46c51b"  # From build or promotion
+  description = "Deploy version 1.2.3 with CNB"
 }
 ```
 
@@ -37,16 +83,91 @@ resource "heroku_app_release" "foobar-release" {
 The following arguments are supported:
 
 * `app_id` - (Required) Heroku app ID (do not use app name)
-* `slug_id` - unique identifier of slug
-* `description` - description of changes in this release
+* `slug_id` - (Optional) Unique identifier of slug. Required for Cedar generation apps. Conflicts with `oci_image`.
+* `oci_image` - (Optional) OCI image identifier (UUID or SHA256 digest). Required for Fir generation apps. Conflicts with `slug_id`.
+* `description` - (Optional) Description of changes in this release
+
+### Artifact Type Requirements
+
+Exactly one artifact type must be specified based on your app's generation:
+
+| Generation | Required Field | Field Type | Example |
+|------------|----------------|------------|---------|
+| Cedar | `slug_id` | UUID | `"01234567-89ab-cdef-0123-456789abcdef"` |
+| Fir | `oci_image` | UUID or SHA256 | `"7f668938-7999-48a7-ad28-c24cbd46c51b"` or `"sha256:abc123..."` |
 
 ## Attributes Reference
 
 The following attributes are exported:
 
 * `id` - The ID of the app release
+* `slug_id` - The slug ID (for Cedar generation apps)
+* `oci_image` - The OCI image identifier (for Fir generation apps)
+
+## Validation
+
+The provider automatically validates that the correct artifact type is used for your app's generation:
+
+* **Cedar apps**: Must use `slug_id`, cannot use `oci_image`
+* **Fir apps**: Must use `oci_image`, cannot use `slug_id`
+
+If you specify the wrong artifact type, you'll receive a clear error message during `terraform plan`.
+
+## OCI Image Formats
+
+The `oci_image` field accepts multiple formats:
+
+* **UUID format**: `"7f668938-7999-48a7-ad28-c24cbd46c51b"` (most common)
+* **SHA256 with prefix**: `"sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"`
+* **Bare SHA256**: `"abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"`
+
+## Best Practices
+
+### Artifact Promotion Workflow
+
+1. **Build once**: Create your build in one environment
+2. **Promote everywhere**: Use `heroku_app_release` to deploy the same artifact to other environments
+3. **Immutable artifacts**: Never modify artifacts, always create new ones for changes
+
+### Cedar Example Workflow
+```hcl
+# 1. Upload slug (external process)
+# 2. Deploy to staging
+resource "heroku_app_release" "staging" {
+  app_id  = heroku_app.staging.id
+  slug_id = var.slug_id
+}
+
+# 3. Promote to production
+resource "heroku_app_release" "production" {
+  app_id  = heroku_app.production.id
+  slug_id = var.slug_id  # Same slug as staging
+}
+```
+
+### Fir Example Workflow
+```hcl
+# 1. Build in development
+resource "heroku_build" "dev_build" {
+  app_id = heroku_app.development.id
+  source { path = "." }
+}
+
+# 2. Promote to staging
+resource "heroku_app_release" "staging" {
+  app_id    = heroku_app.staging.id
+  oci_image = var.oci_image_id  # From dev build
+}
+
+# 3. Promote to production
+resource "heroku_app_release" "production" {
+  app_id    = heroku_app.production.id
+  oci_image = var.oci_image_id  # Same OCI image
+}
+```
 
 ## Import
+
 The most recent app release can be imported using the application name.
 
 For example:

heroku/resource_heroku_app_release.go

@@ -15,10 +15,11 @@ import (
 
 func resourceHerokuAppRelease() *schema.Resource {
 	return &schema.Resource{
-		Create: resourceHerokuAppReleaseCreate,
-		Read:   resourceHerokuAppReleaseRead,
-		Update: resourceHerokuAppReleaseUpdate,
-		Delete: resourceHerokuAppReleaseDelete,
+		Create:        resourceHerokuAppReleaseCreate,
+		Read:          resourceHerokuAppReleaseRead,
+		Update:        resourceHerokuAppReleaseUpdate,
+		Delete:        resourceHerokuAppReleaseDelete,
+		CustomizeDiff: resourceHerokuAppReleaseCustomizeDiff,
 
 		Importer: &schema.ResourceImporter{
 			State: resourceHerokuAppReleaseImport,
@@ -33,9 +34,18 @@ func resourceHerokuAppRelease() *schema.Resource {
 			},
 
 			"slug_id": { // An existing Heroku release cannot be updated so ForceNew is required
-				Type:     schema.TypeString,
-				Required: true,
-				ForceNew: true,
+				Type:          schema.TypeString,
+				Optional:      true,
+				ForceNew:      true,
+				ConflictsWith: []string{"oci_image"},
+			},
+
+			"oci_image": { // OCI image identifier for Fir generation apps
+				Type:          schema.TypeString,
+				Optional:      true,
+				ForceNew:      true,
+				ConflictsWith: []string{"slug_id"},
+				ValidateFunc:  validateOCIImage,
 			},
 
 			"description": {
@@ -58,6 +68,11 @@ func resourceHerokuAppRelease() *schema.Resource {
 func resourceHerokuAppReleaseCreate(d *schema.ResourceData, meta interface{}) error {
 	client := meta.(*Config).Api
 
+	// Validate artifact type for app generation at apply time
+	if err := validateArtifactForApp(client, d); err != nil {
+		return err
+	}
+
 	opts := heroku.ReleaseCreateOpts{}
 
 	appName := getAppId(d)
@@ -68,6 +83,12 @@ func resourceHerokuAppReleaseCreate(d *schema.ResourceData, meta interface{}) er
 		opts.Slug = vs
 	}
 
+	if v, ok := d.GetOk("oci_image"); ok {
+		vs := v.(string)
+		log.Printf("[DEBUG] OCI Image: %s", vs)
+		opts.OciImage = &vs
+	}
+
 	if v, ok := d.GetOk("description"); ok {
 		vs := v.(string)
 		log.Printf("[DEBUG] description: %s", vs)
@@ -101,6 +122,75 @@ func resourceHerokuAppReleaseCreate(d *schema.ResourceData, meta interface{}) er
 	return resourceHerokuAppReleaseRead(d, meta)
 }
 
+// validateArtifactForAppGeneration validates artifact type (slug_id vs oci_image) against the target app's generation
+func validateArtifactForAppGeneration(ctx context.Context, diff *schema.ResourceDiff, v interface{}) error {
+	hasSlug := diff.Get("slug_id").(string) != ""
+	hasOci := diff.Get("oci_image").(string) != ""
+
+	// Get the app ID to check its generation
+	appID := diff.Get("app_id").(string)
+	if appID == "" {
+		// During plan phase, the app_id might not be available yet if the app is being created
+		// in the same configuration. Skip validation for now - it will be caught at apply time.
+		return nil
+	}
+
+	config := v.(*Config)
+	client := config.Api
+
+	// Fetch app info to determine its generation
+	app, err := client.AppInfo(ctx, appID)
+	if err != nil {
+		// If we can't fetch the app (it might not exist yet during plan), skip validation
+		// It will be caught at apply time
+		return nil
+	}
+
+	// Validate artifact type against app generation
+	return validateArtifactForGeneration(app.Generation.Name, hasSlug, hasOci)
+}
+
+// validateArtifactForGeneration validates artifact type compatibility with a specific generation
+func validateArtifactForGeneration(generationName string, hasSlug bool, hasOci bool) error {
+	switch generationName {
+	case "cedar":
+		if hasOci {
+			return fmt.Errorf("cedar generation apps must use slug_id, not oci_image")
+		}
+		if !hasSlug {
+			return fmt.Errorf("cedar generation apps require slug_id")
+		}
+	case "fir":
+		if hasSlug {
+			return fmt.Errorf("fir generation apps must use oci_image, not slug_id")
+		}
+		if !hasOci {
+			return fmt.Errorf("fir generation apps require oci_image")
+		}
+	default:
+		// Unknown generation - let the API handle it
+		return nil
+	}
+
+	return nil
+}
+
+// validateArtifactForApp validates artifact type for the target app at apply time
+func validateArtifactForApp(client *heroku.Service, d *schema.ResourceData) error {
+	hasSlug := d.Get("slug_id").(string) != ""
+	hasOci := d.Get("oci_image").(string) != ""
+	appID := d.Get("app_id").(string)
+
+	// Fetch app info to determine its generation
+	app, err := client.AppInfo(context.TODO(), appID)
+	if err != nil {
+		return fmt.Errorf("error fetching app info: %s", err)
+	}
+
+	// Validate artifact type against app generation
+	return validateArtifactForGeneration(app.Generation.Name, hasSlug, hasOci)
+}
+
 func resourceHerokuAppReleaseRead(d *schema.ResourceData, meta interface{}) error {
 	client := meta.(*Config).Api
 
@@ -113,7 +203,20 @@ func resourceHerokuAppReleaseRead(d *schema.ResourceData, meta interface{}) erro
 	}
 
 	d.Set("app_id", appRelease.App.ID)
-	d.Set("slug_id", appRelease.Slug.ID)
+
+	// Handle Cedar releases (with slugs)
+	if appRelease.Slug != nil {
+		d.Set("slug_id", appRelease.Slug.ID)
+	}
+
+	// Handle Fir releases (with OCI images)
+	for _, artifact := range appRelease.Artifacts {
+		if artifact.Type == "oci-image" {
+			d.Set("oci_image", artifact.ID)
+			break
+		}
+	}
+
 	d.Set("description", appRelease.Description)
 
 	return nil
@@ -168,6 +271,26 @@ func resourceHerokuAppReleaseImport(d *schema.ResourceData, meta interface{}) ([
 	return []*schema.ResourceData{d}, nil
 }
 
+func resourceHerokuAppReleaseCustomizeDiff(ctx context.Context, diff *schema.ResourceDiff, v interface{}) error {
+	hasSlug := diff.Get("slug_id").(string) != ""
+	hasOci := diff.Get("oci_image").(string) != ""
+
+	// Must have exactly one artifact type
+	if !hasSlug && !hasOci {
+		return fmt.Errorf("either slug_id or oci_image must be provided")
+	}
+	if hasSlug && hasOci {
+		return fmt.Errorf("slug_id and oci_image are mutually exclusive")
+	}
+
+	// Validate artifact type compatibility with app generation during plan phase
+	if err := validateArtifactForAppGeneration(ctx, diff, v); err != nil {
+		return err
+	}
+
+	return nil
+}
+
 func resourceHerokuAppReleaseV0() *schema.Resource {
 	return &schema.Resource{
 		Schema: map[string]*schema.Schema{