Skip to content

Test GitHub Actions Workflows

Test changes to erk's GitHub Actions workflows before merging.

Overview

When modifying workflow files like .github/workflows/plan-implement.yml, you need to test the actual workflow execution, not just the YAML syntax. This guide shows how to use erk admin test-erk-impl-gh-workflow to automate this process.

Prerequisites

  • Your workflow changes committed to a branch
  • GitHub CLI (gh) authenticated
  • Push access to the repository

Quick Start

# Test erk-impl workflow from your current branch
erk admin test-erk-impl-gh-workflow

# Use an existing issue (avoids creating a new one)
erk admin test-erk-impl-gh-workflow --issue 12345

# Watch the run in real-time
erk admin test-erk-impl-gh-workflow --watch

What the Command Does

  1. Pushes your branch - Ensures your workflow changes are on remote
  2. Creates a test issue - Or uses an existing one with --issue
  3. Creates a test branch - Pushes master to test-workflow-{timestamp}
  4. Creates a draft PR - Required by the workflow's pr_number input
  5. Triggers the workflow - Uses --ref to run YOUR version of the YAML
  6. Returns the run URL - So you can monitor the execution

Understanding --ref

The key insight is that gh workflow run --ref <branch> runs the workflow file from that branch, not just with different inputs. This means:

  • Changes to workflow steps, jobs, and scripts take effect
  • You're testing the actual modified workflow, not the one on master

Example Output

Ensuring branch 'my-workflow-fix' exists on remote...
✓ Branch 'my-workflow-fix' pushed to origin
✓ Created test issue #4358
Creating test branch 'test-workflow-abc123'...
✓ Test branch 'test-workflow-abc123' created
✓ Draft PR #4359 created
Triggering erk-impl workflow from 'my-workflow-fix'...

Workflow triggered successfully!

Run URL: https://github.com/dagster-io/erk/actions/runs/123456789
Test branch: test-workflow-abc123
Draft PR: https://github.com/dagster-io/erk/pull/4359

Cleanup After Testing

The command creates test artifacts that you should clean up:

# Delete the test branch
git push origin --delete test-workflow-abc123

# Close the draft PR (use the PR number from output)
gh pr close 4359

# Optionally close the test issue if you created one
gh issue close 4358

When to Use This

  • Modifying plan-implement.yml - Test before merging changes
  • Debugging workflow failures - Reproduce issues with your fixes
  • Testing new workflow inputs - Verify parameter handling
  • Developing new workflows - Iterate on workflow logic

Manual Alternative

For more control, you can trigger workflows manually:

# 1. Push your branch
git push origin HEAD

# 2. Create test infrastructure
git push origin master:test-branch
gh pr create --head test-branch --base master --draft --title "Test"

# 3. Trigger with --ref pointing to YOUR branch
gh workflow run plan-implement.yml \
  --ref your-branch-with-workflow-changes \
  -f issue_number=12345 \
  -f submitted_by=your-username \
  -f distinct_id=test123 \
  -f issue_title="Test" \
  -f branch_name=test-branch \
  -f pr_number=PR_NUMBER \
  -f base_branch=master

See Also