ADR suggestion Using Composite Actions for Repeated GitHub Workflow Tasks

[rozyczko]

The EasyScience and EasyScience based projects currently uses GitHub Actions for continuous integration and deployment. Multiple workflows exist (python-ci.yml, python-package.yml, documentation-build.yml, nightly-check.yml, etc.) that perform common tasks such as:

• Checking out code (actions/checkout@v5)
• Setting up the Pixi environment (currently using a composite action [setup-pixi]
• Uploading artifacts (actions/upload-artifact@v4)
• Uploading coverage reports (codecov/[email protected])
• Pushing documentation changes (ad-m/github-push-action@master)

These tasks are repeated across multiple workflows, leading to code duplication and potential inconsistencies when updates are needed. While the project already uses a composite action for Pixi setup, other common tasks are implemented inline using marketplace actions or direct commands.

I would propose to create composite actions for the following repeated tasks to improve maintainability, consistency, and reusability across workflows:

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

These composite actions will be stored in .github\actions and follow the existing pattern established by setup-pixi in EasyScience.

Each composite action will:

• Have clear inputs for customization
• Include proper error handling and logging
• Use consistent naming conventions
• Be versioned appropriately

Consequences

Positive

• Maintainability: Changes to common tasks can be made in one place
• Consistency: Ensures uniform behavior across workflows
• Reusability: Actions can be easily reused in new workflows
• Readability: Workflows become more concise and focused on their specific logic

Negative

• Initial overhead: Time required to create and migrate to composite actions
• Maintenance burden: Additional files to maintain in the repository
• Complexity: Slight increase in complexity for workflow authors
• Versioning challenges: Need to manage versions of composite actions

[rozyczko]

Then I am converting this into an ADR

[rozyczko]

Additionally, we should create a project containing all the custom actions.
Having say, easyscience/github/.github/actions would allow other projects use these in their workflow files.

Here, it would be e.g.

uses: easyscience/github/.github/actions/setup-pixi@v1