Improve 'Please run' messages in the CI (#48365)

* Improve 'Please run error'

* add missing file

* fix script

* Apply suggestions from code review

Co-authored-by: Alan Parra <alan.parra@goteleport.com>

* address alan's feedback

* Update Makefile

Co-authored-by: Alan Parra <alan.parra@goteleport.com>

* Update build.assets/please-run.sh

Co-authored-by: Alan Parra <alan.parra@goteleport.com>

---------

Co-authored-by: Alan Parra <alan.parra@goteleport.com>

Makefile

@@ -1458,7 +1458,7 @@ derive:
 .PHONY: derive-up-to-date
 derive-up-to-date: must-start-clean/host derive
 	@if ! git diff --quiet; then \
-		echo 'Please run make derive.'; \
+		./build.assets/please-run.sh "derived functions" "make derive"; \
 		exit 1; \
 	fi
 
@@ -1492,15 +1492,15 @@ endif
 # Unlike protos-up-to-date, this target runs locally.
 .PHONY: protos-up-to-date/host
 protos-up-to-date/host: must-start-clean/host grpc/host
-	@if ! git diff --quiet; then \
-		echo 'Please run make grpc.'; \
+		./build.assets/please-run.sh "protos gRPC" "make grpc"; \
 		exit 1; \
 	fi
 
 .PHONY: must-start-clean/host
 must-start-clean/host:
 	@if ! git diff --quiet; then \
-		echo 'This must be run from a repo with no unstaged commits.'; \
+		@echo 'This must be run from a repo with no unstaged commits.'; \
+		git diff; \
 		exit 1; \
 	fi
 
@@ -1509,7 +1509,12 @@ must-start-clean/host:
 crds-up-to-date: must-start-clean/host
 	$(MAKE) -C integrations/operator manifests
 	@if ! git diff --quiet; then \
-		echo 'Please run make -C integrations/operator manifests.'; \
+		./build.assets/please-run.sh "operator CRD manifests" "make -C integrations/operator crd"; \
+		exit 1; \
+	fi
+	$(MAKE) -C integrations/operator crd-docs
+	@if ! git diff --quiet; then \
+		./build.assets/please-run.sh "operator CRD docs" "make -C integrations/operator crd"; \
 		exit 1; \
 	fi
 
@@ -1518,8 +1523,7 @@ crds-up-to-date: must-start-clean/host
 terraform-resources-up-to-date: must-start-clean/host
 	$(MAKE) -C integrations/terraform docs
 	@if ! git diff --quiet; then \
-		echo 'Please run make -C integrations/terraform docs.'; \
-		git diff; \
+		./build.assets/please-run.sh "TF provider docs" "make -C integrations/terraform docs"; \
 		exit 1; \
 	fi
 

build.assets/please-run.sh

@@ -0,0 +1,40 @@
+#!/bin/sh
+
+# This script is a helper that tells developers what generated content is out of date
+# and which command to run.
+# When running on GitHub actions, the script will also create an error in the PR and
+# collapse the diff to improve readability.
+
+set -eu
+
+# only echoes the string if we are in GitHub Actions
+echo_gha() {
+  [ -n "${GITHUB_ACTIONS+x}" ] && echo "$@"
+}
+
+main() {
+  if [ $# -ne 2 ]; then
+    echo "Usage: $0 <kind> <generate command>" >&2
+    exit 1
+  fi
+
+  KIND="$1"
+  GENERATE_COMMAND="$2"
+
+  TITLE="$KIND are out-of-date"
+  MESSAGE="Please run the command \`$GENERATE_COMMAND\`"
+
+  # Create a GitHub error
+  echo_gha "::error file=Makefile,title=$TITLE::$MESSAGE"
+
+  echo "============="
+  echo "$TITLE"
+  echo "$MESSAGE"
+  echo "============="
+
+  echo_gha "::group::Diff output"
+  git diff || true
+  echo_gha "::endgroup::"
+}
+
+main "$@"

integrations/operator/Makefile

@@ -72,6 +72,9 @@ help: ## Display this help.
 
 ##@ Development
 
+.PHONY: crd ## Single command to generate anything CRD-related (manifests and docs)
+crd: crdgen crd-docs
+
 .PHONY: crdgen
 crdgen: ## Generate CRDs
 	make -C crdgen