GitHub Actions Debugging — Skill Instructions

Workflow Inventory

Workflow

Trigger

Purpose

dockerbuild-prerelease-*.yml (×15)

Push to feature/*, odaa-*

Build + push prerelease Docker images

dockerbuild-release-*.yml (×15)

Push to main (tags)

Build + push release Docker images

Chart-Releaser-ReleasedChartTester-TrivyScanner.yml

Push to main

Release Helm charts + integration test + security scan

trigger_tests.yml

PR to main + manual

Full BDD test suite on Kind cluster

local-test.yml

Manual

Local testing helper

lint-python-code.yml

PR to main

Python formatting with Black

check-no-prerelease-suffixes-in-PR.yml

PR to main

Ensure no prerelease suffixes in release

Auto-Generated Docker Workflows

CRITICAL: The 30 Docker build workflows are AUTO-GENERATED. Do not edit them directly.

  • Config: automation/generators/dockerbuild-workflow-generator/dockerbuild-config.yaml

  • Generator: automation/generators/dockerbuild-workflow-generator/dockerbuild_workflow_generator.py (uses Jinja2)

  • To modify: Edit the config YAML or Jinja2 templates, then regenerate

Docker Build Pipeline Steps

  1. Read image name/version from charts/canvas-oda/values.yaml using yq

  2. Validate version format:

    • Prerelease: <n>.<n>.<n>-<suffix> (e.g., 1.2.5-LT5)

    • Release: <n>.<n>.<n> (e.g., 1.2.5)

  3. Check release image doesn’t already exist (prevents overwriting)

  4. Build multi-arch: linux/amd64,linux/arm64

  5. Inject build args: SOURCE_DATE_EPOCH, GIT_COMMIT_SHA, CICD_BUILD_TIME

  6. Push to Docker Hub with latest and version tags

PR Test Pipeline (trigger_tests.yml)

Skip Mechanisms

  • [skip tests] in PR title or commit message

  • If only values.yaml changed with empty prereleaseSuffix removals

Pipeline Steps (334 lines)

  1. Kind cluster (Kubernetes v1.30.0) + cloud-provider-kind

  2. Istio install (pinned versions)

  3. Helm dependency update on all sub-charts

  4. Install Canvas from local source: helm install canvas charts/canvas-oda

  5. Port-forward Keycloak (8083) and Resource Inventory (8639)

  6. Install test components in components and odacompns-1 namespaces

  7. Run BDD tests: cd feature-definition-and-test-kit && npm start

  8. Upload artifacts: operator logs, test results, cucumber.json

  9. Generate badges: Parse cucumber JSON for pass/fail/skip counts

Common Failure Points

Symptom

Likely Cause

Debug Command

Pod not ready

Image pull failure

kubectl describe pod <name> -n canvas

CRD not found

Helm dependency not updated

helm dependency update charts/canvas-oda

Test timeout

Operator crash loop

kubectl -n canvas logs deployment/component-operator

Port-forward fail

Service not yet ready

kubectl get svc -n canvas

Istio errors

Version mismatch

Check Istio install step version pins

Chart Release Pipeline

Trigger: Push to main

  1. helm dependency update on all charts

  2. helm/chart-releaser-action — package and publish to GitHub Pages

  3. Verify charts available in Helm repo

  4. Integration test on Kind cluster:

    • Install from published charts: helm install canvas oda-canvas/canvas-oda --devel

    • Install test component

    • Verify component status reaches Complete

  5. Trivy security scan on deployed images

  6. Upload scan results as artifacts

Python Linting (lint-python-code.yml)

Uses psf/black formatter on:

  • automation/generators/dockerbuild-workflow-generator/

  • source/operators/component-management/

  • source/operators/api-management/istio/

  • source/operators/dependentApiSimpleOperator/

  • source/operators/secretsmanagementOperator-hc/

Debugging Commands

Cluster State

kubectl get all -n canvas
kubectl get all -n components
kubectl get components -n components
kubectl get exposedapis -n components
kubectl get dependentapis -n components

Operator Logs

kubectl -n canvas logs deployment/component-operator
kubectl -n canvas logs deployment/api-operator-istio
kubectl -n canvas logs deployment/identity-operator-keycloak

Helm State

helm list --all-namespaces
helm status canvas -n canvas
helm get values canvas -n canvas

Component Debugging

kubectl describe component <name> -n components
kubectl get events -n components --sort-by=.lastTimestamp
kubectl get component <name> -n components -o yaml

Local Testing

Using Act (GitHub Actions Locally)

# Run with act
scripts/run-with-act.sh

# Or directly
cd feature-definition-and-test-kit
npm install
npm start

Local Operator Development

kopf run --namespace=components --standalone source/operators/<path>/<operator>.py

Version Management in CI

File

Field

Prerelease

Release

charts/canvas-oda/values.yaml

compopVersion

1.2.5

1.2.5

charts/canvas-oda/values.yaml

compopPrereleaseSuffix

LT5

""

charts/<chart>/Chart.yaml

version

1.2.5-LT5

1.2.5

The prerelease check workflow (check-no-prerelease-suffixes-in-PR.yml) ensures no prerelease suffixes remain when merging to main.

Artifact Uploads

CI uploads these artifacts for post-mortem analysis:

  • Component operator logs: component-operator-logs

  • API operator logs: api-operator-istio-logs

  • Test results: test-results

  • Cucumber JSON: cucumber-report (machine-readable test results)

  • Trivy scan: trivy-results (security findings)

Do

  • Edit Docker workflow config YAML, not generated workflow files

  • Use [skip tests] in commit messages for documentation-only changes

  • Check operator logs first when BDD tests fail

  • Run helm dependency update after modifying sub-chart versions

  • Use Kind cluster for local integration testing

Don’t

  • Don’t edit dockerbuild-*.yml files directly — they’re auto-generated

  • Don’t push prerelease suffixes to main branch

  • Don’t skip the prerelease suffix check workflow

  • Don’t ignore Trivy security findings in release pipeline

  • Don’t hard-code Kubernetes or Istio versions — use the pinned versions from workflows