diff --git a/docs/src/content/docs/reference/frontmatter-full.md b/docs/src/content/docs/reference/frontmatter-full.md
index 70993cac0b5..8647effe0f4 100644
--- a/docs/src/content/docs/reference/frontmatter-full.md
+++ b/docs/src/content/docs/reference/frontmatter-full.md
@@ -3167,6 +3167,10 @@ safe-outputs:
     # (optional)
     staged: true
 
+    # Reason for closing the issue (default: completed)
+    # (optional)
+    state-reason: "completed"
+
   # Option 2: Enable issue closing with default configuration
   close-issue: null
 
diff --git a/pkg/parser/schemas/main_workflow_schema.json b/pkg/parser/schemas/main_workflow_schema.json
index 118e679d68c..09c87aa5414 100644
--- a/pkg/parser/schemas/main_workflow_schema.json
+++ b/pkg/parser/schemas/main_workflow_schema.json
@@ -5468,6 +5468,12 @@
                   "type": "boolean",
                   "description": "If true, emit step summary messages instead of making GitHub API calls for this specific output type (preview mode)",
                   "examples": [true, false]
+                },
+                "state-reason": {
+                  "type": "string",
+                  "enum": ["completed", "not_planned", "duplicate"],
+                  "default": "completed",
+                  "description": "Reason for closing the issue (default: completed)"
                 }
               },
               "additionalProperties": false,