Programmatic Elimination of GitHub Actions Workflow Run History

The accumulation of workflow run data within GitHub repositories often leads to an oversized digital footprint, cluttered user interfaces, and an inefficiently managed history of Continuous Integration and Continuous Deployment (CI/CD) cycles. While GitHub provides a native web interface for managing actions, it lacks the granular, bulk-deletion capabilities required for enterprise-level maintenance or for developers who experiment heavily with trial-and-error workflow configurations. To solve this, the ecosystem relies on a combination of specialized GitHub Actions, the GitHub CLI (gh), and direct interactions with the REST API to purge unnecessary logs and run metadata.

Implementing a systematic deletion strategy is critical because the "cruft" generated by failed trial runs or repetitive daily builds can obscure important historical data and make it difficult for team members to navigate the Actions tab. The process involves identifying the specific workflow runs to be targeted, validating their retention age against a defined policy, and executing the deletion via authenticated API calls. By leveraging tools like the Mattraks/delete-workflow-runs action, developers can automate the lifecycle of their workflow data, ensuring that only the most relevant runs are preserved while orphan runs—those belonging to workflows that have since been deleted—are efficiently scrubbed from the system.

Architectural Mechanics of Workflow Deletion

The process of deleting workflow runs is fundamentally an exercise in API orchestration. Whether using a pre-built action or a custom bash script, the system interacts with the GitHub REST API to manage the lifecycle of run data.

The underlying mechanism utilizes three primary API operations:

• List repository workflows: This allows the system to identify all workflows currently defined in the repository, providing a map of what can be targeted.
• List workflow runs: This operation retrieves a detailed list of all runs associated with a specific workflow, including metadata such as the creation date, the conclusion of the run, and the run ID.
• Delete a workflow run: This is the destructive action that removes a specific run identified by its unique ID.

When these operations are wrapped into a JavaScript-based GitHub Action, the logic becomes more sophisticated. The action calculates the delta between the current date and the date the workflow run was created. This calculated value is then compared to a user-defined retain_days parameter. If the age of the run is equal to or greater than the specified threshold, the action triggers the deletion endpoint. This prevents the accidental loss of recent data while ensuring that ancient logs are systematically removed.

Detailed Analysis of the Mattraks Delete Workflow Runs Action

The Mattraks/delete-workflow-runs action is a specialized tool designed to automate the cleanup of GitHub Actions history. It is written in JavaScript and is optimized using @vercel/ncc to bundle code, which ensures that node_modules do not need to be uploaded during the action's execution, thereby increasing performance and reducing the action's startup time.

Configuration Parameters and Input Logic

The action provides a comprehensive set of inputs that allow users to fine-tune exactly which runs are deleted and which are preserved.

Advanced Filtering and Retention Strategies

The action supports complex matching patterns and state-based filtering to prevent the accidental deletion of critical runs.

• Workflow Pattern Matching: The delete_workflow_pattern input allows users to target specific workflows using a pipe-separated list. For example, using build|deploy will target any workflow that matches either "build" or "deploy". This is a logical OR operation that provides flexibility in multi-workflow environments.
• Daily Retention Logic: When use_daily_retention is set to true, the keep_minimum_runs parameter changes its behavior. Instead of keeping a global minimum per workflow, it ensures a specific number of runs are kept for each individual day. This is particularly useful for teams that need a daily audit trail of their builds.
• State and Conclusion Filtering: Users can target runs based on their current state or their final result.
• State Options: The delete_workflow_by_state_pattern allows filtering by active, deleted, disabled_fork, disabled_inactivity, or disabled_manually.
• Conclusion Options: The delete_run_by_conclusion_pattern allows targeting specific outcomes such as action_required, cancelled, failure, skipped, or success. It also provides a shorthand for "Unsuccessful" runs, which covers action_required, cancelled, failure, and skipped.
• Orphan Management: The action automatically identifies and deletes "orphan" workflow runs, which are runs associated with workflows that have already been deleted from the repository's codebase.

Authentication and Permission Requirements

Security is paramount when granting an action the ability to delete data. The authentication method depends on the scope of the operation.

• Internal Repository Access: When the action runs within the same repository it is cleaning, the default ${{ github.token }} is sufficient.
• Cross-Repository Access: If the action is designed to clean a different repository, a Personal Access Token (PAT) is required. This PAT must be granted the repo scope to access private repositories and perform destructive actions across the organization.
• Required Permissions: For the action to function, the workflow must explicitly grant the following permissions in the YAML configuration:
• actions: write (Required to delete the runs)
• contents: read (Required to list the workflows and repository state)

Implementation via GitHub CLI and Custom Scripting

For those who prefer not to use a third-party action, the GitHub CLI (gh) provides a powerful interface for mass deletion. This approach is often used by developers who need a one-time cleanup or who want to integrate deletion into a local maintenance script.

The process involves using the gh api command to interact with the Workflow Runs API. A typical implementation follows this logical flow:

1. API Request: The script sends a GET request to /repos/{owner}/{repo}/actions/workflows/{workflow_name}/runs.
2. Header Configuration: It specifies the API version and the accepted media type (e.g., Accept: application/vnd.github+json and X-GitHub-Api-Version: 2022-11-28).
3. Data Parsing: Using jq, the script filters the JSON response to extract only the IDs of runs that have a non-empty conclusion (meaning they have completed).
4. Execution Loop: The script iterates through the list of IDs and executes the command gh run delete --repo $REPOSITORY $RUN.
5. Rate Limiting: A small sleep interval (e.g., 0.1 seconds) is often added between deletions to avoid triggering GitHub's secondary rate limits.

This method is highly effective for removing a workflow's entire history, which subsequently removes the workflow from the Actions UI once all associated runs are gone.

Technical Configuration Example

The following YAML fragment demonstrates a production-ready implementation of the Mattraks action within a GitHub workflow.

yaml jobs: delete-runs: runs-on: ubuntu-latest permissions: actions: write contents: read steps: - name: Delete workflow runs uses: Mattraks/delete-workflow-runs@v2 with: token: ${{ github.token }} repository: ${{ github.repository }} retain_days: ${{ github.event.inputs.days }} keep_minimum_runs: ${{ github.event.inputs.minimum_runs }} use_daily_retention: ${{ github.event.inputs.use_daily_retention }} delete_workflow_pattern: ${{ github.event.inputs.delete_workflow_pattern }} delete_workflow_by_state_pattern: ${{ github.event.inputs.delete_workflow_by_state_pattern }} delete_run_by_conclusion_pattern: >- ${{ startsWith(github.event.inputs.delete_run_by_conclusion_pattern, 'Unsuccessful:') && 'action_required,cancelled,failure,skipped' || github.event.inputs.delete_run_by_conclusion_pattern }} dry_run: ${{ github.event.inputs.dry_run }}

Strategic Operational Considerations

When deploying workflow deletion policies, several critical safeguards should be observed to prevent catastrophic data loss.

• Simulation via Dry-Run: Always execute the action with dry_run: true first. This allows the operator to preview exactly which runs would be deleted without actually modifying the repository data.
• Pull Request Protection: If the check_pullrequest_exist parameter is set to true, the action will skip any runs linked to open pull requests. This ensures that active code reviews are not interrupted by the loss of their associated CI logs.
• Token Scope Validation: Ensure that if a PAT is used, it is stored as a GitHub Secret and not hardcoded in the YAML file.
• Pattern Testing: Before applying a delete_workflow_pattern across an entire organization, test the pattern on a small, non-critical repository to verify that the regular expression or pipe-separated list is matching the intended targets.

Conclusion

The management of GitHub Actions workflow runs is a critical component of repository hygiene. Whether through the use of the Mattraks/delete-workflow-runs action—which offers a high-level, parameterized approach to retention—or through the low-level precision of the GitHub CLI and REST API, the goal is to maintain a lean and meaningful history of automation. By implementing strategies such as daily retention, conclusion-based filtering, and orphan run scrubbing, organizations can ensure that their CI/CD pipelines remain performant and their audit trails remain clear. The transition from manual, sporadic deletion to an automated, policy-driven cleanup ensures that the focus remains on the code and the delivery pipeline rather than the management of historical log data.

Sources

1. GitHub Marketplace - Delete GitHub Actions Workflow Runs
2. GitHub Marketplace - Delete Workflow Runs
3. qmacro Blog - Mass deletion of GitHub Actions workflow runs
4. GitHub Community Discussions - Deleting Workflow Runs