| name | github-actions-debugging |
| description | Guide for debugging and working with GitHub Actions CI/CD workflows in the ODA Canvas project. Covers Docker build workflows, chart release pipeline, PR test pipeline, linting, common debugging commands, and the auto-generated workflow system. Use this skill when troubleshooting CI failures, modifying workflows, or understanding the build pipeline. |
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
- Read image name/version from
charts/canvas-oda/values.yaml using yq
- Validate version format:
- Prerelease:
<n>.<n>.<n>-<suffix> (e.g., 1.2.5-LT5)
- Release:
<n>.<n>.<n> (e.g., 1.2.5)
- Check release image doesn't already exist (prevents overwriting)
- Build multi-arch:
linux/amd64,linux/arm64
- Inject build args:
SOURCE_DATE_EPOCH, GIT_COMMIT_SHA, CICD_BUILD_TIME
- 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)
- Kind cluster (Kubernetes v1.30.0) + cloud-provider-kind
- Istio install (pinned versions)
- Helm dependency update on all sub-charts
- Install Canvas from local source:
helm install canvas charts/canvas-oda
- Port-forward Keycloak (8083) and Resource Inventory (8639)
- Install test components in
components and odacompns-1 namespaces
- Run BDD tests:
cd feature-definition-and-test-kit && npm start
- Upload artifacts: operator logs, test results, cucumber.json
- 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
helm dependency update on all chartshelm/chart-releaser-action — package and publish to GitHub Pages- Verify charts available in Helm repo
- 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
- Trivy security scan on deployed images
- 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)
scripts/run-with-act.sh
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
