Skip to content

ADR-006: Two-Workflow Initialization Pattern

Status

Accepted - 2025-10-01

Context

The original initialization system used a single, complex workflow (init.yml) that handled everything from issue creation to repository setup, branch creation, security scanning, and cleanup in one 492-line file. This approach led to several challenges:

Problems with Single Workflow Approach: - Complexity: One workflow trying to handle multiple concerns (UI, validation, setup, cleanup) - Maintainability: Large, complex workflow difficult to debug and modify - User Experience: Technical error messages and status updates not user-friendly - Error Handling: Complex nested conditions with multiple failure points - State Management: Overlapping initialization checks and complex cleanup process

Need for Better Architecture: The initialization process naturally divides into two distinct phases: 1. User Interaction: Issue creation, validation, and communication 2. Repository Setup: Branch creation, configuration, and finalization

Decision

Split the initialization process into two focused workflows:

  1. init.yml - User interface and issue management (~40 lines, streamlined)
  2. Triggered on push to main branch (template creation)
  3. Creates initialization issue with user-friendly instructions
  4. Handles template vs. instance detection

  5. Removed: README status updates (unnecessary noise)

  6. init-complete.yml - Repository setup and configuration (~300 lines, comprehensive)

  7. Triggered on issue comments (user providing upstream repo)
  8. Validates user input with clear error messages
  9. Performs repository setup and configuration
  10. Enhanced: Repository variable state management
  11. Enhanced: Automatic validation workflow triggering
  12. Streamlined: Minimal issue comments, consolidated commits
  13. Added: Self-cleanup of initialization workflows

Rationale

Separation of Concerns Benefits

  1. Single Responsibility: Each workflow has one clear purpose
  2. Maintainability: Smaller, focused files easier to understand and modify
  3. Debugging: Issues can be isolated to specific workflow phase
  4. Testing: Each workflow can be tested independently
  5. User Experience: Clear separation between user interaction and system setup

User Experience Improvements

  1. Friendly Communication: Welcome messages with emoji and clear instructions
  2. Progress Updates: Real-time status updates during setup process
  3. Clear Error Messages: User-friendly validation feedback
  4. Completion Celebration: Comprehensive summary of what was configured

Technical Architecture Benefits

  1. State Management: .github/workflow.env as primary initialization indicator
  2. Concurrency Control: Proper job isolation with issue-based locking
  3. Error Recovery: Better error handling with user feedback
  4. Simplified Logic: No complex cleanup process required

Alternatives Considered

1. Maintain Single Workflow with Refactoring

  • Pros: Fewer files to manage, all logic in one place
  • Cons: Would still be complex, difficult to separate concerns properly
  • Decision: Rejected due to fundamental complexity issues

2. Three-Workflow Pattern (Init + Validate + Setup)

  • Pros: Even more granular separation
  • Cons: Over-engineering for current needs, too many moving parts
  • Decision: Rejected as unnecessary complexity

3. Composite Actions for Reusable Components

  • Pros: Code reuse, modular components
  • Cons: Doesn't address fundamental architecture issues
  • Decision: Considered for future enhancement but not core solution

Consequences

Positive

  • Dramatically Improved UX: Users get friendly guidance throughout process
  • Easier Maintenance: Developers can quickly understand and modify workflows
  • Better Error Handling: Clear validation with actionable feedback
  • Simplified State Management: Single source of truth for initialization status
  • Reduced Complexity: Each workflow handles 50% fewer concerns
  • Enhanced Reliability: Fewer complex operations reduce failure points

Negative

  • More Files: Two workflows instead of one (mitigated by much simpler content)
  • Cross-Workflow Dependencies: init-complete.yml depends on issue created by init.yml
  • Learning Curve: Team needs to understand two-workflow pattern

Implementation Details

Workflow Triggers

# init.yml - Template creation detection
on:
  push:
    branches: [main]

# init-complete.yml - User response handling
on:
  issue_comment:
    types: [created]

State Management

# Primary initialization indicator
echo "INITIALIZATION_COMPLETE=true" > .github/workflow.env
echo "UPSTREAM_REPO_URL=$UPSTREAM_URL" >> .github/workflow.env

User Communication Pattern

# Progress updates during setup
echo "🔧 **Setting up upstream connection...**" | 
  gh issue comment "${{ github.event.issue.number }}" --body-file -

echo "🌿 **Creating branch structure...**" | 
  gh issue comment "${{ github.event.issue.number }}" --body-file -

Concurrency Control

concurrency:
  group: ${{ github.workflow }}-${{ github.event.issue.number }}
  cancel-in-progress: false

Success Criteria

  • ✅ Initialization workflows are maintainable by team members without GitHub Actions expertise
  • ✅ Users receive clear, friendly guidance throughout the initialization process
  • ✅ Error messages provide actionable feedback for common mistakes
  • ✅ Workflow execution is more reliable with fewer failure points
  • ✅ State management is clear and consistent across deployments
  • ✅ README automatically reflects initialization status for user guidance

Migration Impact

From Previous Single Workflow

  • Reduced Complexity: 492 lines → 222 + 180 lines (better organized)
  • Eliminated Complex Security Filtering: Relies on GitHub's native security features
  • Removed Cleanup PR Requirement: Self-contained initialization process
  • Improved Error Recovery: Better handling of edge cases and user errors

Backward Compatibility

  • Existing Repositories: Continue to work with previous initialization
  • Template Updates: New pattern applies to newly created repositories
  • Migration Path: Optional migration guide for existing repositories

Future Evolution

Potential Enhancements

  1. Template Customization: Support for different initialization templates
  2. Advanced Validation: More sophisticated upstream repository checks
  3. Integration Testing: Automated validation of repository setup
  4. Analytics: Tracking initialization success rates and common issues

Extensibility Design

  • Modular Structure: Additional validation or setup steps can be added easily
  • Configuration Options: Environment variables for customizing behavior
  • Error Handling Framework: Consistent patterns for handling and reporting errors

← ADR-005 | Catalog | ADR-007 →