---
name: ci-cd-workflows
description: Guide for GitHub Actions workflows, test orchestration, parallel testing,
  adapter builds, releases, and CI/CD configuration. Use when working with .github/workflows/,
  versions.json, or troubleshooting CI issues.
version: 1.0.0
tags:
  - ci-cd
  - github-actions
  - workflows
  - testing
  - deployment
  - release
  - orchestration
---

# CI/CD Workflows

**Purpose:** Guide development, modification, and troubleshooting of AIDB's GitHub Actions CI/CD infrastructure

This skill provides practical guidance for working with workflows and configuration. Complete documentation lives in `docs/developer-guide/ci-cd.md`.

## Related Skills

- **testing-strategy** - Test architecture and patterns
- **dev-cli-development** - Local testing with dev-cli
- **adapter-development** - Adapter build processes

## System Overview

**For complete architecture**, see `docs/developer-guide/ci-cd.md` and [architecture.md](resources/architecture.md).

### Workflow Organization

**Note:** All workflow files are now in `.github/workflows/` root directory (GitHub Actions requirement). Workflows use category prefixes for organization:

**Release Workflows** (`release-*.yaml`)

- `release-pr.yaml` - PR-based release orchestration (validate, test, build, matrix, adapters, upload)
- `release-publish.yaml` - Publish draft release on PR merge

**Testing Workflows** (`test-*.yaml`)

- `test-parallel.yaml` - Main test orchestrator (10-15 min, runs everything including frameworks). Called by `release-pr.yaml` or via manual dispatch. Builds adapters and Docker images as part of its flow.

**Adapter Workflows** (`adapter-*.yaml`)

- `adapter-build.yaml` - Build debug adapters for multiple platforms
- `adapter-build-act.yaml` - ACT local testing workflow (for local development with act)

**Maintenance Workflows** (`maintenance-*.yaml`)

- *(Currently none - Dependabot PRs are merged manually)*

**Reusable Workflows** (`*.yaml`)

- `load-versions.yaml` - Dynamic version loading
- `test-suite.yaml` - Generic test runner
- `test-frameworks.yaml` - Framework testing
- `build-adapters.yaml` - Adapter build orchestration
- `build-docker.yaml` - Docker image builds

### Single Source of Truth

**versions.json** (repo root):

- Infrastructure versions (Python, Node, Java) with docker_tag fields
- Adapter versions and repositories (debugpy, vscode-js-debug, java-debug)
- Global packages (build tools: pip, setuptools, wheel, typescript, ts-node)
- Platform/architecture matrix
- GitHub Actions configuration

All workflows dynamically load versions via `load-versions.yaml` - zero hardcoded versions.

See `docs/developer-guide/ci-cd.md` for configuration overview.

### Version Management Strategy

- **versions.json** - Infrastructure versions (Python, Node, Java) and adapter versions updated manually
- **pyproject.toml** - Application dependencies managed by Dependabot (creates PRs automatically)

### Dependabot Integration

Dependabot creates PRs directly against `main`, but **no workflows run** on these PRs:

1. **Target Branch**: All Dependabot PRs target `main`
1. **No CI Triggers**: `release-pr.yaml` skips Dependabot PRs (`github.actor != 'dependabot[bot]'`)
1. **Manual Management**: PRs are reviewed, typically retargeted to release branches, and merged manually
1. **Ecosystems**: pip (daily), github-actions (weekly), npm (weekly)

**Configuration**: `.github/dependabot.yaml`

## Common Tasks

### Running Tests

**On GitHub:**

- Release PRs to `main` → triggers `release-pr.yaml` which calls `test-parallel.yaml`
- Manual dispatch via Actions UI (workflow_dispatch) with options:
  - suite: all, cli, shared, common, logging, mcp, core, frameworks, launch, ci_cd
  - `skip_coverage`: Skip coverage reporting for faster execution
  - `debug_logging`: Enable TRACE-level logging (equivalent to `dev-cli -vvv`)

**Debug logging:** Enable trace-level debugging via `debug_logging` input (mirrors `dev-cli -vvv`):

- `gh workflow run test-parallel.yaml -f debug_logging=true`
- Sets: `AIDB_LOG_LEVEL=TRACE`, `AIDB_ADAPTER_TRACE=1`, `AIDB_CONSOLE_LOGGING=1`

**Test artifacts:** All jobs upload logs to `test-logs-{suite}` artifacts (7-day retention):

- Includes: pytest logs, container logs, CLI logs, full test output
- Retrieval: `gh run download {run-id} -n test-logs-{suite}`
- Job summaries show pytest summary (capped at 100 lines) with link to full artifact

**Locally:**

```bash
./dev-cli test run --suite shared
./dev-cli test run -t "path/to/test.py"
./dev-cli test run --suite shared --language python

# CI/CD workflow tests (includes act-based validation)
./dev-cli test run -s ci_cd              # All tests (unit + integration)
./dev-cli test run -s ci_cd -m "not slow"  # Skip slow act tests
./dev-cli test run -s ci_cd -m integration  # Only integration tests
```

**With act (local CI):**
See [quick-reference.md](resources/quick-reference.md) and [CI/CD Integration Tests](#cicd-integration-tests) below.

### Troubleshooting CI Failures with GitHub CLI

**GitHub CLI is the primary tool for CI observability and debugging.** When tests fail in CI, use GH CLI to inspect jobs, download artifacts, and analyze logs locally.

**Prerequisites:**

```bash
# Verify GH CLI is installed and authenticated
gh auth status
```

**Common workflows:**

```bash
# List recent workflow runs
gh run list --status=failure --limit 10

# View run details and job summary
gh run view <run-id>

# Watch running job in real-time
gh run watch <run-id>

# Download test artifacts (from job summary)
gh run download <run-id> -n test-logs-{suite}
```

**Job summaries include:**

- Status (pass/fail)
- Artifact download command (copy-paste ready)
- Pytest summary (capped at 100 lines)
- FAILED/SKIPPED/ERROR test listings with file paths

**Artifact contents:**

- `pytest-logs/` - Full pytest output, stack traces, captured stdout/stderr
- `.cache/container-data/` - Docker/adapter logs, DAP traces
- `aidb-logs/` - AIDB core library logs (from ~/.aidb/log/)

**For complete guide** including artifact structure, log locations, and troubleshooting workflows, see [troubleshooting.md](resources/troubleshooting.md).

### Building Adapters

**PR-based workflow:**

```bash
# Create release branch
git checkout -b release/0.1.0
# Add release notes
# Push and open PR to main
git push origin release/0.1.0
```

**Manual dispatch:** Actions UI → Build Debug Adapters

See [Adapter Builds](resources/adapter-builds.md) for architecture.

### Cutting Releases

**PR-based release workflow:**

1. Create release branch: `release/X.Y.Z`
1. Create release notes: `docs/release-notes/X.Y.Z.md`
1. Open PR to `main` → triggers comprehensive release pipeline:
   - Validation, tests, builds (VSIX, wheel)
   - TestPyPI/ProdPyPI uploads
   - Adapter builds (Python/JS/Java × platforms)
   - Draft release creation
1. Merge PR → publishes release

**Testing mode:** Set `CD_SKIP_PYPI=true` to run full workflow without PyPI uploads.

For complete pipeline breakdown, CD_SKIP_PYPI details, and examples, see [Release Workflows](resources/release-workflows.md) or `docs/developer-guide/ci-cd.md` for detailed job list.

### Adding Frameworks

1. Create app in `src/tests/_assets/framework_apps/{lang}/{framework}/`
1. Add deps to `src/tests/_docker/scripts/install-framework-deps.sh`
1. Create test file in `src/tests/frameworks/{lang}/{framework}/e2e/`

Framework dependencies auto-managed via checksum services.

### Modifying Configuration

**Update infrastructure version:**

```json
// versions.json
{
  "infrastructure": {
    "python": {
      "version": "3.12"  // All workflows pick up automatically
    }
  }
}
```

**Add platform:**

```json
{
  "platforms": [
    {
      "os": "linux",
      "arch": "arm64"
    }
  ]
}
```

## Test Orchestration

**For detailed architecture**, see [Test Orchestration](resources/test-orchestration.md) and `docs/developer-guide/ci-cd.md`.

### Parallel Execution

**Main orchestrator:** `test-parallel.yaml`

**Flow:**

1. Load versions from `versions.json`
1. Build adapters and Docker in parallel
1. Run test suites in parallel: cli, shared, mcp, core, frameworks, launch, common/logging, ci_cd

**Performance:**

- 10-15 min wall-clock
- 50% faster than sequential
- Up to 10 parallel runners

### Dynamic Matrix

Frameworks use dynamic matrix from `versions.json`:

- Single source of truth
- Easy enable/disable
- Auto version expansion
- No workflow changes needed

## Troubleshooting

**For comprehensive guide**, see [Troubleshooting](resources/troubleshooting.md).

**For CI test failures and artifact analysis**, see [troubleshooting.md](resources/troubleshooting.md).

### Quick Diagnostics

**Workflow not triggering:**

- Check trigger conditions and branch names
- Review path filters
- Verify workflow enabled

**Test failures:**

- Download artifacts: `gh run download <run-id> -n test-logs-{suite}`
- Check job logs in Actions UI
- Look for adapter build failures
- Review Docker build logs
- Check version conflicts

**Adapter builds:**

- Verify platform compatibility
- Check upstream availability
- Review versions.json adapter configuration

**Version loading:**

- Validate versions.json syntax
- Check Python version consistency

### Investigation Workflow

1. Identify failing job → Download artifacts (`gh run download`)
1. Check logs for errors
1. Review recent changes
1. Reproduce locally with dev-cli or act

**Note:** `actionlint` runs automatically via pre-commit hooks when committing workflow changes.

## Workflow Patterns

See [architecture.md](resources/architecture.md) for job dependencies, conditionals, matrices, and reusable workflows.

## Configuration Files

- **versions.json** - Infrastructure, adapters, platforms (see `docs/developer-guide/ci-cd.md`)

**Secrets:** See `docs/developer-guide/ci-cd.md` for complete list.

## Local CI Testing

Use `act` to run workflows locally. See [quick-reference.md](resources/quick-reference.md) for commands.

## CI/CD Integration Tests

Act-based tests in `src/tests/ci_cd/integration/` validate workflow syntax and matrices.

**Quick commands:**

```bash
./dev-cli test run -s ci_cd              # All tests (unit + integration)
./dev-cli test run -s ci_cd -m "not slow"  # Skip slow tests
```

## Composite Actions

Available in `.github/actions/`: `setup-aidb-env`, `setup-multi-lang`, `download-test-artifacts`, `run-aidb-tests`. See [architecture.md](resources/architecture.md).

## Best Practices

For comprehensive guidelines on workflow development, configuration management, testing strategy, and validation checklists, see [architecture.md](resources/architecture.md).

## Cross-Workflow Dependencies

Workflows run independently by default. See [architecture.md](resources/architecture.md) for cross-workflow coordination patterns.

## Resources

| Resource                                                 | Content                                                                       |
| -------------------------------------------------------- | ----------------------------------------------------------------------------- |
| [architecture.md](resources/architecture.md)             | Workflow patterns, reusable workflows, composite actions, cross-workflow deps |
| [test-orchestration.md](resources/test-orchestration.md) | Parallel execution, test suites, matrix strategy                              |
| [adapter-builds.md](resources/adapter-builds.md)         | Build process, artifacts, platforms, local builds                             |
| [release-workflows.md](resources/release-workflows.md)   | Release process, versioning, CD_SKIP_PYPI                                     |
| [troubleshooting.md](resources/troubleshooting.md)       | Investigation workflow, common issues, debugging                              |
| [quick-reference.md](resources/quick-reference.md)       | Commands, file locations, triggers                                            |

### Internal Documentation

Complete guides: `docs/developer-guide/ci-cd.md`

### Code References

- `.github/workflows/` - Workflow definitions
- `.github/actions/` - Composite actions
- `.github/scripts/` - CI/CD scripts
- `versions.json` - Infrastructure & adapter versions

## Quick Reference

### Workflow Triggers

**Run Tests:** Via `release-pr.yaml` (PR to `main`) or manual dispatch
**Release (draft):** PR to `main` from `release/**` branch
**Release (publish):** PR merge to `main` from `release/**` branch
**Build Adapters:** Part of release workflow (release-pr.yaml)

### Common Commands

```bash
# Local testing
./dev-cli test run --suite {shared|cli|mcp}
./dev-cli test run -t "path/to/test.py"

# Validation
actionlint .github/workflows/**/*.yaml

# Local CI
act -l                    # List
act -j test-shared        # Run job
act push -j build         # With event
```

### Key Files

- `versions.json` - Single source of truth
- `.github/workflows/test-parallel.yaml` - Main orchestrator
- `.github/workflows/load-versions.yaml` - Version loading
- `.actrc` - Local CI config

______________________________________________________________________

**Remember:**

- versions.json is single source of truth
- Use reusable workflows for DRY
- Test locally before pushing
- Validate configuration changes
- Monitor performance metrics