From d7ee855e49260c936312526b3d76076c1de5d40b Mon Sep 17 00:00:00 2001
From: Valentin Maerten <maerten.valentin@gmail.com>
Date: Fri, 12 Dec 2025 21:23:37 +0100
Subject: [PATCH] feat: emit error annotations in GitHub Actions (#2568)

---
 cmd/task/task.go          | 16 ++++++++++++++++
 website/src/docs/guide.md | 22 ++++++++++++++++++++++
 2 files changed, 38 insertions(+)

diff --git a/cmd/task/task.go b/cmd/task/task.go
index e169a954..4ec8e39a 100644
--- a/cmd/task/task.go
+++ b/cmd/task/task.go
@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strconv"
 
 	"github.com/spf13/pflag"
 
@@ -28,19 +29,34 @@ func main() {
 			Color:   flags.Color,
 		}
 		if err, ok := err.(*errors.TaskRunError); ok && flags.ExitCode {
+			emitCIErrorAnnotation(err)
 			l.Errf(logger.Red, "%v\n", err)
 			os.Exit(err.TaskExitCode())
 		}
 		if err, ok := err.(errors.TaskError); ok {
+			emitCIErrorAnnotation(err)
 			l.Errf(logger.Red, "%v\n", err)
 			os.Exit(err.Code())
 		}
+		emitCIErrorAnnotation(err)
 		l.Errf(logger.Red, "%v\n", err)
 		os.Exit(errors.CodeUnknown)
 	}
 	os.Exit(errors.CodeOk)
 }
 
+// emitCIErrorAnnotation emits an error annotation for supported CI providers.
+func emitCIErrorAnnotation(err error) {
+	if isGA, _ := strconv.ParseBool(os.Getenv("GITHUB_ACTIONS")); !isGA {
+		return
+	}
+	if e, ok := err.(*errors.TaskRunError); ok {
+		fmt.Fprintf(os.Stdout, "::error title=Task '%s' failed::%v\n", e.TaskName, e.Err)
+		return
+	}
+	fmt.Fprintf(os.Stdout, "::error title=Task failed::%v\n", err)
+}
+
 func run() error {
 	log := &logger.Logger{
 		Stdout:  os.Stdout,
diff --git a/website/src/docs/guide.md b/website/src/docs/guide.md
index 80ccf98d..ef59375c 100644
--- a/website/src/docs/guide.md
+++ b/website/src/docs/guide.md
@@ -2290,6 +2290,28 @@ The `output` option can also be specified by the `--output` or `-o` flags.
 
 :::
 
+## CI Integration
+
+### Colored output
+
+Task automatically enables colored output when running in CI environments
+(`CI=true`). Most CI providers set this variable automatically.
+
+You can also force colored output with `FORCE_COLOR=1` or disable it with
+`NO_COLOR=1`.
+
+### Error annotations
+
+When running in GitHub Actions (`GITHUB_ACTIONS=true`), Task automatically emits
+error annotations when a task fails. These annotations appear in the workflow
+summary, making it easier to spot failures without scrolling through logs.
+
+```shell
+::error title=Task 'build' failed::exit status 1
+```
+
+This feature requires no configuration and works automatically.
+
 ## Interactive CLI application
 
 When running interactive CLI applications inside Task they can sometimes behave