This directory contains GitHub Actions workflows for Apache Cloudberry CI/CD.

• Available Workflows
• Manual Workflow Triggers
• Artifact Reuse for Faster Testing
• Running Workflows in Forked Repositories

Many workflows support manual triggering via workflow_dispatch, allowing developers to run CI jobs on-demand.

1. Navigate to the Actions tab in GitHub
2. Select the workflow from the left sidebar (e.g., "Build and Test Cloudberry")
3. Click Run workflow button (top right)
4. Select your branch
5. Configure input parameters (if available)
6. Click Run workflow

Available test selections:

• all - Run all test suites
• ic-good-opt-off - Installcheck with optimizer off
• ic-good-opt-on - Installcheck with optimizer on
• ic-contrib - Contrib extension tests
• ic-resgroup - Resource group tests
• ic-resgroup-v2 - Resource group v2 tests
• ic-resgroup-v2-memory-accounting - Resource group memory tests
• ic-singlenode - Single-node mode tests
• make-installcheck-world - Full test suite
• And more... (see workflow for complete list)

This manual workflow supports two manual modes:

• official_source_release: builds convenience DEB/RPM packages from an ASF-approved official source release
• git_ref_test: temporarily archives a specified tag or commit from the repository with git archive semantics and runs the same packaging flow for CI validation

Workflow behavior:

• In official_source_release mode, verifies the source tarball with the project KEYS, .asc, and .sha512 before any build starts.
• In git_ref_test mode, checks out the specified tag or commit and prepares a temporary source tarball using git archive semantics, including checked-out submodule contents, without Apache release verification.
• Derives the package build version automatically by stripping a trailing -incubating from the release version before invoking the DEB/RPM packaging scripts.
• Runs unittest-cloudberry.sh after building from source and before packaging.
• Installs each generated DEB/RPM, verifies its .sha512, and runs a gpdemo smoke test with basic SQL validation.
• Runs the full flow, from source release verification to package generation, inside Cloudberry Docker build images instead of installing dependencies on the GitHub runner.
• Generates .sha512 files for each produced DEB/RPM artifact.
• Preserves the default package filenames emitted by dpkg-buildpackage and rpmbuild.
• Does not generate detached .asc signatures for convenience binaries; that remains a release manager local signing step.

Input rules:

• official_source_release: fill source_url, source_asc_url, and source_sha512_url
• git_ref_test: fill git_ref; the Apache URL inputs may be left empty

Current target matrix:

• rocky8: x86_64, arm64
• rocky9: x86_64, arm64
• ubuntu22.04: x86_64, arm64
• ubuntu24.04: x86_64, arm64

When debugging test failures, rebuilding Cloudberry (~50-70 minutes) on every iteration is inefficient. The artifact reuse feature allows you to reuse build artifacts from a previous successful run.

1. Build artifacts (RPMs, source tarballs) from a previous workflow run are downloaded
2. Build job is skipped (saves ~45-60 minutes)
3. RPM installation test is skipped (saves ~5-10 minutes)
4. Test jobs run with the reused artifacts
5. You can iterate on test configurations without rebuilding

After a successful build (even if tests failed), get the run ID:

Option A: From GitHub Actions UI

• Go to Actions tab → Click on a completed workflow run
• The URL will be: https://github.com/apache/cloudberry/actions/runs/12345678901
• The run ID is 12345678901

Option B: From GitHub API

# List recent workflow runs
gh run list --workflow=build-cloudberry.yml --limit 5

# Get run ID from specific branch
gh run list --workflow=build-cloudberry.yml --branch=my-feature --limit 1

Via GitHub UI:

1. Go to Actions → Build and Test Cloudberry
2. Click Run workflow
3. Enter the run ID in "Reuse build artifacts from a previous run ID"
4. Optionally customize test_selection
5. Click Run workflow

Via GitHub CLI:

# Reuse artifacts from run 12345678901, run only specific tests
gh workflow run build-cloudberry.yml \
  --field reuse_artifacts_from_run_id=12345678901 \
  --field test_selection=ic-good-opt-off

• Build job will be skipped (shows as "Skipped" in Actions UI)
• RPM Install Test will be skipped
• Test jobs will run with artifacts from the specified run ID
• Total time: ~15-30 minutes (vs ~65-100 minutes for full build+test)

Debugging a specific test failure:

# Run 1: Full build + all tests (finds test failure in ic-good-opt-off)
gh workflow run build-cloudberry.yml

# Get the run ID from output
RUN_ID=$(gh run list --workflow=build-cloudberry.yml --limit 1 --json databaseId --jq '.[0].databaseId')

# Run 2: Reuse artifacts, run only failing test
gh workflow run build-cloudberry.yml \
  --field reuse_artifacts_from_run_id=$RUN_ID \
  --field test_selection=ic-good-opt-off

Testing different configurations:

# Test with optimizer off, then on, using same build
gh workflow run build-cloudberry.yml \
  --field reuse_artifacts_from_run_id=$RUN_ID \
  --field test_selection=ic-good-opt-off

gh workflow run build-cloudberry.yml \
  --field reuse_artifacts_from_run_id=$RUN_ID \
  --field test_selection=ic-good-opt-on

• Artifacts expire after 90 days (GitHub default retention)
• Run ID must be from the same repository (or accessible fork)
• Artifacts must include both RPM and source build artifacts
• Cannot reuse artifacts across different OS/architecture combinations
• Changes to source code require a fresh build

GitHub Actions workflows are enabled in forks, allowing you to validate changes before submitting a Pull Request.

1. Fork the repository to your GitHub account

2. Enable GitHub Actions in your fork:

   • Go to your fork's Actions tab
   • Click "I understand my workflows, go ahead and enable them"

Secrets Configuration:

No manual secret configuration is required for the main build and test workflows.

• GITHUB_TOKEN is automatically provided by GitHub and used when downloading artifacts from previous runs (artifact reuse feature)
• DockerHub secrets (DOCKERHUB_USER, DOCKERHUB_TOKEN) are only required for building custom container images (advanced/maintainer use case, not needed for typical development)

• ✅ Automated triggers work: Push and PR events trigger workflows
• ✅ Manual triggers work: workflow_dispatch is fully functional
• ✅ Artifact reuse works: Can reuse artifacts from previous runs in your fork
• ⚠️ Cross-fork artifact reuse: Not supported (security restriction)
• ⚠️ Some features may be limited: Certain features requiring organization-level secrets may not work

1. Test locally first when possible (faster iteration)
2. Use manual triggers to avoid burning GitHub Actions minutes unnecessarily
3. Use artifact reuse to iterate on test failures efficiently
4. Push to feature branches to trigger automated CI
5. Review Actions tab to ensure workflows completed successfully before opening PR

# 1. Create feature branch in fork
git checkout -b fix-test-failure

# 2. Make changes and push to fork
git commit -am "Fix test failure"
git push origin fix-test-failure

# 3. CI runs automatically on push

# 4. If tests fail, iterate using artifact reuse
# Get run ID from your fork's Actions tab
gh workflow run build-cloudberry.yml \
  --field reuse_artifacts_from_run_id=12345678901 \
  --field test_selection=ic-good-opt-off

# 5. Once tests pass, open PR to upstream
gh pr create --web

Cause: Artifacts from specified run ID not found or expired

Solution:

• Verify the run ID is correct
• Check that run completed successfully (built artifacts)
• Run a fresh build if artifacts expired (>90 days)

Cause: GitHub Actions not enabled in fork

Solution:

• Go to fork's Actions tab
• Click to enable workflows

Cause: Workflow trying to access artifacts from different repository

Solution:

• Can only reuse artifacts from same repository
• Run a fresh build in your fork first, then reuse those artifacts

• GitHub Actions Documentation
• Cloudberry Contributing Guide
• Cloudberry Build Guide
• DevOps Scripts