ci-cd-quirks

name	ci-cd-quirks
description	Use when confused by CI behavior, investigating why a workflow failed, or troubleshooting environment variable issues in qe-tools

CI/CD Quirks and Non-Obvious Behaviors

Overview

The qe-tools CI has several non-obvious behaviors around Go versions, pre-commit hooks, workflow triggers, and environment variables that can cause confusing failures.

Quirk 1: Go Version Mismatch

Three different Go versions are in play:

Location	Go Version	Source
go.mod	1.21	Module minimum compatibility
CI (test.yml, lint.yml)	1.22	actions/setup-go in workflows
Dockerfile	Varies	UBI9 go-toolset (version depends on tag)

Consequence: Code may compile locally with Go 1.22 features but fail in the container if the UBI9 image ships an older Go. Stick to Go 1.21 language features unless go.mod is bumped.

Quirk 2: Pre-commit Runs Full Test Suite

.pre-commit-config.yaml includes go-test-mod which runs go test ./... on every commit. This means:

• Every git commit triggers the full test suite
• Slow tests block the commit
• Failing tests prevent committing

Workaround: git commit --no-verify to skip hooks (not recommended for final commits).

Quirk 3: Lint Config Uses Non-Standard Name

The golangci-lint config is .golang-ci.yml (with hyphen), not the standard .golangci.yml. This means:

• golangci-lint run without -c flag won't find the config
• Always use: golangci-lint run -c .golang-ci.yml ./...
• The Makefile already handles this via make lint

Quirk 4: estimate-review Workflow Runs on Its Own PR

.github/workflows/estimate-review.yml triggers on pull_request: [opened, synchronize] and runs the estimate-review command against the PR itself. This is self-referential -- the tool estimates its own review time and labels the PR.

Quirk 5: AGENTS.md Line Limit is CI-Enforced

validate-agents-md.yaml fails the PR if AGENTS.md has 60 or more lines. Uses grep -c '' for accurate counting (not wc -l which can undercount without trailing newline).

Environment Variables

Variable	Required By	Default	Notes
SLACK_TOKEN	coffee-break, send-slack-message	none	Slack Bot OAuth token
CHANNEL_ID	send-slack-message	none	Slack channel ID
HACBS_CHANNEL_ID	coffee-break	none	Different from CHANNEL_ID
GITHUB_TOKEN	health-check, estimate-review	none	Needs PR read + label write scopes
PROW_URL	periodic-report	none	GCS base URL for Prow job artifacts
JOB_SPEC	webhook report-portal	none	OpenShift CI job spec JSON
ARTIFACT_DIR	create-report, health-check	none	Local directory for output files
OCI_REF	analyze-test-results	none	Quay artifact reference

Viper convention: Flag names are lowercase (slack_token), env vars are UPPERCASE (SLACK_TOKEN). Viper handles the translation when bound with viper.BindEnv().

Workflow Summary

Workflow	Trigger	Blocks Merge
test.yml	PR + push to main (*.go)	Yes
lint.yml	PR + push to main (*.go)	Yes
pre-commit.yml	PR	Yes
commitlint.yml	PR	Yes
estimate-review.yml	PR (opened, synchronize)	No (informational)
validate-agents-md.yaml	PR (AGENTS.md changes)	Yes
release.yml	tag push	N/A
coffee.yml	cron (monthly)	N/A
slack-message.yml	cron	N/A