Add promoted_release_ids attribute to pipeline promotion resource

Add new promoted_release_ids computed attribute that returns the list of
release IDs created by a promotion (one for each target app).

The existing promoted_release_id attribute incorrectly returned the source
release ID instead of the promoted release IDs. This attribute is now
deprecated and returns the first value from promoted_release_ids for
backwards compatibility.

Changes:
- Add promoted_release_ids as computed list attribute
- Fetch promotion targets via PipelinePromotionTargetList API
- Extract release IDs from each target
- Deprecate promoted_release_id with clear messaging
- Set promoted_release_id to first value of promoted_release_ids
- Update documentation with examples
- Add schema tests for new attribute and deprecation

Testing:
- Schema test validates both attributes exist
- Schema test validates promoted_release_id is deprecated
- Schema test validates promoted_release_ids is a List
- All unit tests pass
- Manual test confirmed correct release IDs returned

Author: heroku-johnny

docs/resources/pipeline_promotion.md

@@ -46,6 +46,19 @@ resource "heroku_pipeline_promotion" "staging_to_multiple" {
     heroku_app.demo.id
   ]
 }
+
+# Access the promoted release information
+output "promoted_releases" {
+  value = heroku_pipeline_promotion.staging_to_multiple.promoted_release_ids
+}
+
+# Access a specific target's release ID
+output "production_release_id" {
+  value = [
+    for release in heroku_pipeline_promotion.staging_to_multiple.promoted_release_ids :
+    release.release_id if release.app_id == heroku_app.production.id
+  ][0]
+}
 ```
 
 ## Argument Reference
@@ -65,4 +78,7 @@ The following attributes are exported:
 * `id`: The UUID of the pipeline promotion.
 * `status`: The status of the promotion (`pending`, `completed`).
 * `created_at`: When the promotion was created.
-* `promoted_release_id`: The UUID of the release that was promoted.
+* `promoted_release_ids`: List of objects containing information about each promoted release. Each object has:
+  * `app_id`: The UUID of the target app that received the promotion.
+  * `release_id`: The UUID of the release created on that target app.
+* `promoted_release_id`: **(Deprecated)** The UUID of the first promoted release. Use `promoted_release_ids` instead. This attribute is maintained for backwards compatibility and will be removed in a future major version.

heroku/resource_heroku_pipeline_promotion.go

@@ -72,7 +72,28 @@ func resourceHerokuPipelinePromotion() *schema.Resource {
 			"promoted_release_id": {
 				Type:        schema.TypeString,
 				Computed:    true,
-				Description: "ID of the release that was actually promoted",
+				Deprecated:  "Use promoted_release_ids instead. This attribute contains the first release ID from promoted_release_ids for backwards compatibility.",
+				Description: "ID of the first promoted release (deprecated, use promoted_release_ids)",
+			},
+
+			"promoted_release_ids": {
+				Type:        schema.TypeList,
+				Computed:    true,
+				Description: "List of promoted releases with their associated target app IDs",
+				Elem: &schema.Resource{
+					Schema: map[string]*schema.Schema{
+						"app_id": {
+							Type:        schema.TypeString,
+							Computed:    true,
+							Description: "ID of the target app that received the promotion",
+						},
+						"release_id": {
+							Type:        schema.TypeString,
+							Computed:    true,
+							Description: "ID of the release created on the target app",
+						},
+					},
+				},
 			},
 		},
 	}
@@ -142,16 +163,48 @@ func resourceHerokuPipelinePromotionRead(d *schema.ResourceData, meta interface{
 	d.Set("status", promotion.Status)
 	d.Set("created_at", promotion.CreatedAt.String())
 
-	// Set the release that was actually promoted
-	if promotion.Source.Release.ID != "" {
-		d.Set("promoted_release_id", promotion.Source.Release.ID)
-	}
-
 	// Set configuration from API response
 	d.Set("pipeline", promotion.Pipeline.ID)
 	d.Set("source_app_id", promotion.Source.App.ID)
 
-	log.Printf("[DEBUG] Pipeline promotion read completed for: %s", d.Id())
+	// Fetch promotion targets to get the resulting release IDs
+	targets, err := client.PipelinePromotionTargetList(context.TODO(), d.Id(), nil)
+	if err != nil {
+		return fmt.Errorf("error retrieving pipeline promotion targets: %s", err)
+	}
+
+	// Build list of promoted releases with app associations
+	var promotedReleases []map[string]interface{}
+	var firstReleaseID string
+	for _, target := range targets {
+		if target.Release != nil && target.Release.ID != "" {
+			promotedRelease := map[string]interface{}{
+				"app_id":     target.App.ID,
+				"release_id": target.Release.ID,
+			}
+			promotedReleases = append(promotedReleases, promotedRelease)
+
+			// Capture first release ID for backwards compatibility
+			if firstReleaseID == "" {
+				firstReleaseID = target.Release.ID
+			}
+
+			log.Printf("[DEBUG] Found promoted release ID: %s for app: %s", target.Release.ID, target.App.ID)
+		}
+	}
+
+	// Set promoted_release_ids (new structured attribute)
+	if err := d.Set("promoted_release_ids", promotedReleases); err != nil {
+		return fmt.Errorf("error setting promoted_release_ids: %s", err)
+	}
+
+	// Set promoted_release_id (deprecated, for backwards compatibility)
+	// Contains the first release ID from the list
+	if firstReleaseID != "" {
+		d.Set("promoted_release_id", firstReleaseID)
+	}
+
+	log.Printf("[DEBUG] Pipeline promotion read completed for: %s with %d promoted releases", d.Id(), len(promotedReleases))
 	return nil
 }
 

heroku/resource_heroku_pipeline_promotion_test.go

@@ -24,7 +24,7 @@ func TestResourceHerokuPipelinePromotion_Schema(t *testing.T) {
 	}
 
 	// Test computed fields
-	computedFields := []string{"status", "created_at", "promoted_release_id"}
+	computedFields := []string{"status", "created_at", "promoted_release_id", "promoted_release_ids"}
 	for _, field := range computedFields {
 		if _, ok := resource.Schema[field]; !ok {
 			t.Errorf("Computed field %s not found in schema", field)
@@ -34,6 +34,30 @@ func TestResourceHerokuPipelinePromotion_Schema(t *testing.T) {
 		}
 	}
 
+	// Test promoted_release_id is deprecated
+	if resource.Schema["promoted_release_id"].Deprecated == "" {
+		t.Errorf("promoted_release_id should be marked as deprecated")
+	}
+
+	// Test promoted_release_ids is a List of objects
+	if resource.Schema["promoted_release_ids"].Type != schema.TypeList {
+		t.Errorf("promoted_release_ids field should be TypeList")
+	}
+
+	// Test promoted_release_ids contains objects with app_id and release_id
+	promotedReleaseIdsElem, ok := resource.Schema["promoted_release_ids"].Elem.(*schema.Resource)
+	if !ok {
+		t.Fatal("Expected promoted_release_ids.Elem to be a Resource (object)")
+	}
+
+	if _, hasAppID := promotedReleaseIdsElem.Schema["app_id"]; !hasAppID {
+		t.Fatal("Expected promoted_release_ids objects to have app_id field")
+	}
+
+	if _, hasReleaseID := promotedReleaseIdsElem.Schema["release_id"]; !hasReleaseID {
+		t.Fatal("Expected promoted_release_ids objects to have release_id field")
+	}
+
 	// Test targets field is a Set
 	if resource.Schema["targets"].Type != schema.TypeSet {
 		t.Errorf("targets field should be TypeSet")