delete-workflow-runs v2

The GitHub action to delete workflow runs in a repository. This action (written in JavaScript) wraps two Workflow Runs API:

• List repository workflows -- Lists the workflows in a repository.

• List workflow runs -- List all workflow runs for a workflow.

• Delete a workflow run -- Delete a specific workflow run.

The action will calculate the number of days that each workflow run has been retained so far, then use this number to compare with the number you specify for the input parameter "retain_days". If the retention days of the workflow run has reached (equal to or greater than) the specified number, the workflow run will be deleted.

Features

Workflow runs to delete can be filtered in multiple ways.
Default: ALL workflow runs above a certain max age, except a certain minimum number, are removed. With no sorting or differentiation about what kind of workflow it is.
Various filters can be defined by configuration options to control this behaviour:

1. Restrict to specific branches in general and/or completely prevent deletion if the branch still exists.
2. Restrict to certain workflows only.
3. Filter out workflows by state, like active or disabled.
4. Restrict deletions based on outcome of the runs
5. Configure the minimum number to keep the be checked on branch and/or workflow level.

Inputs

1. token

Required: YES

Default: ${{ github.token }}

The token used to authenticate.

• If the workflow runs are in the current repository where the action is running, using github.token is OK, but you must specify additional permissions within your build job (or at a higher level) to allow the default token access to read the repository contents and to write (delete) action-related data, see the examples below. More details, see the GITHUB_TOKEN.
• If the workflow runs are in another repository, you need to use a personal access token (PAT) that must have the repo scope. More details, see "Creating a personal access token".

2. repository

Required: YES

Default: ${{ github.repository }}

Name of the repository where the workflow runs are located

3. retain_days

Required: YES

Default: 30

Amount of days used to compare with the retention days of each workflow

4. keep_minimum_runs

Required: YES

Default: 6

Minimum runs to keep for each workflow

5. minimum_ignore_deleted_branches

Required: NO

Default: false

Normally, the deletion filter keep_minimum_runs does not care if the branch associated with a run still exists. It will just try to maintain at least N entries for each workflow. This setting allows to only consider still existing branches for which to keep a minimum number of workflow runs. When this property is set to true, the minimum number of runs is not maintained for branches which were deleted. This can be used to keep a branch-specific amount of minimum runs for all existing branches while allowing to delete old runs of deleted branches.

6. branch_specific_minimum_runs

Required: NO

Default: false

When set, all workflows are grouped by branch and keep_mininum_runs will be applied to each group individually. Can be combined with workflow_specific_minimum_runs.

7. workflow_specific_minimum_runs

Required: NO

Default: false

When set, all workflows are grouped by workflow id and keep_mininum_runs will be applied to each group individually. Can be combined with branch_specific_minimum_runs.

8. delete_workflow_pattern

Required: NO

Name or filename of the workflow (if not set, all workflows are targeted).
Multiple values permitted as a comma-separated list, but names used should not contain comma

9. delete_workflow_by_state_pattern

Required: NO

Default: 'ALL'

Filter workflows by state: active, deleted, disabled_fork, disabled_inactivity, disabled_manually
Multiple state values permitted as a comma-separated list

10. delete_run_by_conclusion_pattern

Required: NO

Default: 'ALL'

Remove runs based on conclusion: action_required, cancelled, failure, skipped, success
Multiple conclusion values permitted as a comma-separated list

11. branch_filter

Required: NO

Default: '[".*"]'

This allows the action to only target workflow runs triggered by specific branches.

Expected value is a JSON array of regular expressions, e.g:
'["main", "release/.*", "test/.*"]' - only workflows whose branch names match main, release/... or test/... will be deleted (if no other filters prevent it).

12. dry_run

Required: NO

Logs simulated changes, no deletions are performed

13. check_branch_existence

Required: NO

If true, the removage of a workflow is skipped, when a run is attached to a existing branch. Set to true avoids that check runs are deleted and the checks are not more present. (excludes main)

14. check_branch_existence_exceptions

Required: NO

Default: main

Only applies when check_branch_existence=true.
The branch name(s) listed here will be exempt from the existence check. Workflows from matching branches will not be checked for existence. This is useful to keep the history of permanent branches tidy while still preventing temporary branches from losing all their checks.
Multiple names are permitted as a comma-separated list. Contrary to branch_filter, this does not use pattern matching.

15. check_pullrequest_exist

Required: NO

If true, the Runs will be checked for linkage to a PR.

Examples

In scheduled workflow, see schedule event.

Tip: Using scheduled workflow is the recommended way that can periodically, automatically delete old workflow runs.

name: Delete old workflow runs
on:
  schedule:
    - cron: '0 0 1 * *'
# Run monthly, at 00:00 on the 1st day of month.

jobs:
  del_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: 30
          keep_minimum_runs: 6

In manual triggered workflow, see workflow_dispatch event.

In this way, you can manually trigger the workflow at any time to delete old workflow runs.

name: Delete old workflow runs
on:
  workflow_dispatch:
    inputs:
      days:
        description: 'Days-worth of runs to keep for each workflow'
        required: true
        default: '30'
      minimum_runs:
        description: 'Minimum runs to keep for each workflow'
        required: true
        default: '6'
      delete_workflow_pattern:
        description: 'Name or filename of the workflow (if not set, all workflows are targeted)'
        required: false
      delete_workflow_by_state_pattern:
        description: 'Filter workflows by state: active, deleted, disabled_fork, disabled_inactivity, disabled_manually'
        required: true
        default: "ALL"
        type: choice
        options:
          - "ALL"
          - active
          - deleted
          - disabled_inactivity
          - disabled_manually
      delete_run_by_conclusion_pattern:
        description: 'Remove runs based on conclusion: action_required, cancelled, failure, skipped, success'
        required: true
        default: "ALL"
        type: choice
        options:
          - "ALL"
          - "Unsuccessful: action_required,cancelled,failure,skipped"
          - action_required
          - cancelled
          - failure
          - skipped
          - success
      dry_run:
        description: 'Logs simulated changes, no deletions are performed'
        required: false

jobs:
  del_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 }}
          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 }}

Using with self-hosted git hub enterprise

If you're using this action in a GHE environment, the value you provide for baseUrl needs to be the precise and full URL. Consult the documentation for your GHE instance to determine the correct URL to use.

For this example, let's say that you're running a modern version of GHE and it is accessible at https://github.mycompany.com. The API endpoint for your GHE instance will (probably) be https://github.mycompany.com/api/v3. So the resulting configuration would look like this:

jobs:
    clean_up:
        # <...>
        steps:
            - name: Delete workflow runs
              uses: Mattraks/delete-workflow-runs@v2
              with:
                  # <...>
                  baseUrl: https://github.mycompany.com/api/v3

License

The scripts and documentation in this project are released under the MIT License.