Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 80 additions & 0 deletions .github/workflows/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# GitHub Actions Workflows

This directory contains CI/CD workflows for the DeepWork project. We use GitHub's merge queue for efficient testing.

## Workflow Overview

| Workflow | File | Purpose |
|----------|------|---------|
| **Validate** | `validate.yml` | Linting (ruff) and unit tests |
| **Integration Tests** | `claude-code-test.yml` | Command generation and e2e tests |
| **CLA Assistant** | `cla.yml` | Contributor License Agreement verification |
| **Release** | `release.yml` | PyPI publishing on tags |

## Merge Queue Strategy

We use a skip pattern so the same required checks pass in both PR and merge queue contexts:

| Workflow | On PRs | In Merge Queue |
|----------|--------|----------------|
| **Validate** | Runs | Runs |
| **Integration Tests** | Skipped (passes) | Runs |
| **E2E Tests** | Skipped (passes) | Runs |
| **CLA Check** | Runs | Skipped (passes) |

### How It Works

Jobs/steps use `if: github.event_name == 'merge_group'` conditions to control execution:

```yaml
# Job that only runs in merge queue (skipped on PRs)
jobs:
expensive-tests:
if: github.event_name == 'merge_group' || github.event_name == 'workflow_dispatch'
...

# Step that skips in merge queue (runs on PRs only)
steps:
- name: CLA Check
if: github.event_name != 'merge_group'
...
```

When a job/step is skipped due to an `if` condition, GitHub treats it as a successful check. This allows:

- **Fast PR feedback**: Only lint + unit tests run on every push
- **Thorough merge validation**: Expensive integration/e2e tests run in merge queue before merging
- **No duplicate CLA checks**: CLA is verified on PRs; no need to re-check in merge queue

### Required Checks Configuration

In GitHub branch protection rules, require these checks:
- `Validate / tests`
- `Claude Code Integration Test / validate-generation`
- `Claude Code Integration Test / claude-code-e2e`
- `CLA Assistant / cla-check`

All checks will pass in both PR and merge queue contexts (either by running or by being skipped).

## Workflow Details

### validate.yml
- **Triggers**: `pull_request`, `merge_group`
- **Jobs**: `tests` - runs ruff format/lint checks and pytest unit tests
- Runs on every PR and in merge queue

### claude-code-test.yml
- **Triggers**: `pull_request`, `merge_group`, `workflow_dispatch`
- **Jobs**:
- `validate-generation`: Tests command generation from fixtures (no API key needed)
- `claude-code-e2e`: Full end-to-end test with Claude Code CLI (requires `ANTHROPIC_API_KEY`)
- Both jobs skip on PRs, run in merge queue and manual dispatch

### cla.yml
- **Triggers**: `pull_request_target`, `issue_comment`, `merge_group`
- **Jobs**: `cla-check` - verifies contributors have signed the CLA
- Runs on PRs, skips in merge queue (CLA already verified)

### release.yml
- **Triggers**: Tags matching `v*`
- **Jobs**: Builds and publishes to PyPI
4 changes: 3 additions & 1 deletion .github/workflows/cla.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ on:
types: [created]
pull_request_target:
types: [opened, synchronize]
# Run in merge queue but skip the step (shows as passing check)
merge_group:

# Explicitly set permissions for the workflow
permissions:
Expand All @@ -18,7 +20,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: "CLA Assistant"
if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
if: github.event_name != 'merge_group' && ((github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target')
uses: contributor-assistant/github-action@v2.6.1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Expand Down
9 changes: 7 additions & 2 deletions .github/workflows/claude-code-test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ on:
required: false
default: 'false'
type: boolean
# Run on all PRs (shows as check, but steps skip unless in merge queue)
pull_request:
# Run in the merge queue to validate before merging
merge_group:

Expand All @@ -18,9 +20,11 @@ concurrency:
cancel-in-progress: true

jobs:
# Job 1: Validate command generation from fixtures (always runs, no API key needed)
# Job 1: Validate command generation from fixtures (no API key needed)
# Runs on merge_group and workflow_dispatch, skipped on PRs (shows as passing check)
validate-generation:
runs-on: ubuntu-latest
if: github.event_name == 'merge_group' || github.event_name == 'workflow_dispatch'
steps:
- uses: actions/checkout@v4

Expand Down Expand Up @@ -80,10 +84,11 @@ jobs:

# Job 2: Full end-to-end test with Claude Code
# Tests the COMPLETE workflow: define job -> implement -> execute
# Runs on merge_group and workflow_dispatch, skipped on PRs (shows as passing check)
claude-code-e2e:
runs-on: ubuntu-latest
needs: validate-generation
if: github.event_name == 'workflow_dispatch' || github.event_name == 'merge_group'
if: github.event_name == 'merge_group' || github.event_name == 'workflow_dispatch'
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
steps:
Expand Down