Enable release_id support for pipeline promotions

- Flow team has added Promotion#release_id API support
- Remove error check that blocked release_id usage
- Add release_id to API call when provided
- Update documentation with release_id examples and remove outdated notes
- Remove obsolete unit test for release_id validation
- Pipeline promotions now support both latest and specific release promotion
- Validated with local terraform config - both promotion types work perfectly

Author: heroku-johnny

docs/resources/pipeline_promotion.md

@@ -15,19 +15,26 @@ A pipeline promotion allows you to deploy releases from one app to other apps wi
 pipeline. This enables infrastructure-as-code workflow for promoting code between pipeline stages
 such as staging to production.
 
-Currently promotes the latest release from the source app. Support for promoting specific releases
-(`release_id` parameter) requires additional API support from the Heroku platform team.
+You can promote either the latest release from the source app, or specify a particular release by ID.
 
 ## Example Usage
 
 ```hcl
-# Basic promotion from staging to production
+# Basic promotion from staging to production (latest release)
 resource "heroku_pipeline_promotion" "staging_to_prod" {
   pipeline      = heroku_pipeline.my_app.id
   source_app_id = heroku_app.staging.id
   targets       = [heroku_app.production.id]
 }
 
+# Promotion of a specific release
+resource "heroku_pipeline_promotion" "specific_release" {
+  pipeline      = heroku_pipeline.my_app.id
+  source_app_id = heroku_app.staging.id
+  release_id    = "01234567-89ab-cdef-0123-456789abcdef"
+  targets       = [heroku_app.production.id]
+}
+
 # Promotion to multiple target apps
 resource "heroku_pipeline_promotion" "staging_to_multiple" {
   pipeline      = heroku_pipeline.my_app.id
@@ -46,8 +53,7 @@ The following arguments are supported:
 * `pipeline` - (Required) The UUID of the pipeline containing the apps.
 * `source_app_id` - (Required) The UUID of the source app to promote from.
 * `targets` - (Required) Set of UUIDs of target apps to promote to.
-* `release_id` - (Optional) **Not yet supported**. The UUID of a specific release to promote. 
-  Currently returns an error as this requires additional Heroku platform API support.
+* `release_id` - (Optional) The UUID of a specific release to promote. If not specified, promotes the latest release from the source app.
 
 ## Attributes Reference
 
@@ -64,9 +70,5 @@ The following attributes are exported:
 * All apps (source and targets) must be in the same pipeline.
 * All apps must have the same generation (Cedar or Fir). See [`heroku_pipeline`](./pipeline.html) for generation compatibility requirements.
 * The source app must have at least one release to promote.
-* Promotions copy the latest release from the source app to all target apps.
-
-## Future Enhancement
+* Promotions copy either the latest release (if no `release_id` specified) or the specified release to all target apps.
 
-The `release_id` parameter will be supported once the Heroku platform team adds the necessary API
-functionality. This will enable promoting specific releases rather than just the latest release.

heroku/resource_heroku_pipeline_promotion.go

@@ -1,10 +1,7 @@
 // Pipeline Promotion Resource
 //
 // This resource allows promoting releases between apps in a Heroku Pipeline.
-// Currently promotes the latest release from the source app to target apps.
-//
-// DEPENDENCY: The 'release_id' field requires Flow team to add Promotion#release_id
-// API support. Until then, only latest release promotion is supported.
+// Supports promoting either the latest release or a specific release by ID.
 package heroku
 
 import (
@@ -45,7 +42,7 @@ func resourceHerokuPipelinePromotion() *schema.Resource {
 				Optional:     true,
 				ForceNew:     true,
 				ValidateFunc: validation.IsUUID,
-				Description:  "Specific release ID to promote (requires Flow team API update)",
+				Description:  "Specific release ID to promote (optional, defaults to latest release)",
 			},
 
 			"targets": {
@@ -86,12 +83,7 @@ func resourceHerokuPipelinePromotionCreate(d *schema.ResourceData, meta interfac
 
 	log.Printf("[DEBUG] Creating pipeline promotion")
 
-	// Check if release_id is specified - this requires Flow team API support
-	if releaseID, ok := d.GetOk("release_id"); ok {
-		return fmt.Errorf("release_id parameter (%s) is not yet supported - waiting for Flow team to add Promotion#release_id API support", releaseID.(string))
-	}
-
-	// Build promotion options using current API
+	// Build promotion options with release_id support
 	pipelineID := d.Get("pipeline").(string)
 	sourceAppID := d.Get("source_app_id").(string)
 	targets := d.Get("targets").(*schema.Set)
@@ -102,6 +94,15 @@ func resourceHerokuPipelinePromotionCreate(d *schema.ResourceData, meta interfac
 		ID *string `json:"id,omitempty" url:"id,omitempty,key"`
 	}{ID: &sourceAppID}
 
+	// Add release_id if specified
+	if releaseID, ok := d.GetOk("release_id"); ok {
+		releaseIDStr := releaseID.(string)
+		opts.Source.Release = &struct {
+			ID *string `json:"id,omitempty" url:"id,omitempty,key"`
+		}{ID: &releaseIDStr}
+		log.Printf("[DEBUG] Promoting specific release: %s", releaseIDStr)
+	}
+
 	// Convert targets set to slice
 	for _, target := range targets.List() {
 		targetAppID := target.(string)

heroku/resource_heroku_pipeline_promotion_test.go

@@ -1,7 +1,6 @@
 package heroku
 
 import (
-	"strings"
 	"testing"
 
 	"github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
@@ -55,26 +54,3 @@ func TestResourceHerokuPipelinePromotion_Schema(t *testing.T) {
 	}
 }
 
-func TestResourceHerokuPipelinePromotion_ReleaseIdValidation(t *testing.T) {
-	// This test validates that release_id parameter currently returns an error
-	// Once Flow team adds API support, this test should be updated
-
-	d := schema.TestResourceDataRaw(t, resourceHerokuPipelinePromotion().Schema, map[string]interface{}{
-		"pipeline":      "01234567-89ab-cdef-0123-456789abcdef",
-		"source_app_id": "01234567-89ab-cdef-0123-456789abcdef",
-		"release_id":    "01234567-89ab-cdef-0123-456789abcdef",
-		"targets":       []interface{}{"01234567-89ab-cdef-0123-456789abcdef"},
-	})
-
-	meta := &Config{} // Mock config
-
-	err := resourceHerokuPipelinePromotionCreate(d, meta)
-	if err == nil {
-		t.Error("Expected error when release_id is provided, but got none")
-	}
-
-	expectedError := "release_id parameter"
-	if err != nil && !strings.Contains(err.Error(), expectedError) {
-		t.Errorf("Expected error to contain '%s', got: %s", expectedError, err.Error())
-	}
-}