Using Composite Actions for Repeated GitHub Workflow Tasks

[rozyczko]

ADR: Using Composite Actions for Repeated GitHub Workflow Tasks

We will create composite actions for the following repeated tasks to improve maintainability, consistency, and reusability across workflows:

1. checkout - Standardized checkout with common options
2. build-package - Package building with Pixi
3. run-tests - Test execution with configurable options
4. upload-artifacts - Artifact upload with standardized naming
5. upload-coverage - Coverage report upload to Codecov
6. push-docs - Documentation deployment to gh-pages

Implementation Details

• Composite actions will be stored in https://github.com/easyscience/github/.github/actions.
• Actions should be centralized in a dedicated repository (easyscience/github) to enable reuse across all EasyScience projects
• Actions will be referenced using the format: uses: easyscience/github/.github/actions/<action-name>@v*

Design Principles

Each composite action will:

• Have clear inputs for customization
• Include proper error handling and logging
• Use consistent naming conventions
• Be versioned appropriately (following semantic versioning)
• Include comprehensive documentation

Consequences

Positive

• Maintainability: Changes to common tasks can be made in one place and propagate to all workflows
• Consistency: Ensures uniform behavior across all workflows and projects
• Reusability: Actions can be easily reused in new workflows and across different repositories
• Readability: Workflows become more concise and focused on their specific business logic
• Cross-project sharing: Centralizing in easyscience/github enables all EasyScience projects to benefit

Negative

• Initial overhead: Time and effort required to create composite actions and migrate existing workflows
• Maintenance burden: Additional files and versioning to maintain in the repository
• Learning curve: Team members need to understand the composite action abstraction layer
• Versioning challenges: Need to carefully manage versions to avoid breaking changes
• Complexity: Slight increase in indirection when troubleshooting workflow issues
• Dependency management: Workflows depend on external composite actions, requiring coordination

Alternatives Considered

1. Status quo: Continue with inline actions in each workflow

   • Rejected due to maintenance overhead and inconsistencies

2. Reusable workflows: Use GitHub's reusable workflows feature

   • Not chosen as composite actions provide better granularity for individual tasks

3. Workflow templates: Use workflow templates only

   • Insufficient for ensuring consistency in already-existing workflows

References

• GitHub Composite Actions Documentation
• Original discussion: https://github.com/orgs/easyscience/discussions/38
• Existing setup-pixi composite action implementation

Notes

Date: 2025-12-04
Authors: @rozyczko
Related discussions: Discussion #38