Skip to content

docs: Remove legacy files and enhance package cleanup action #261

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nookyo merged 3 commits into from
Jul 7, 2025
Merged

docs: Remove legacy files and enhance package cleanup action #261

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
80b9792
feat: Remove legacy loader, report, and wrapper files; introduce new …
nookyo Jul 4, 2025
fc4bae7
Merge branch '193-cleanup-action-create-workflow-for-cleaning-up-mave…
nookyo Jul 7, 2025
40e5d99
docs: Update README for Package Cleanup Action to support both Docker…
nookyo Jul 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
186 changes: 113 additions & 73 deletions actions/container-package-cleanup/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,39 +1,26 @@
# 🚀 Container Package Cleanup Action
# 🚀 Package Cleanup Action

This **Container Package Cleanup** GitHub Action automates the cleanup of old Docker images (or other container packages) in a GitHub repository or organization based on specified criteria.
This **Package Cleanup** GitHub Action automates the cleanup of old package versions in a GitHub repository or organization.
It supports both Docker/container images and Maven JAR files.

---

## Features

- Deletes old container package versions based on a threshold date.
- Supports filtering by included and excluded tags.
- Allows configuration through inputs or a configuration file.
- Provides debug mode for detailed logging.
- Supports dry-run mode to preview deletions without making changes.
- **Supports wildcard-based tag matching** for flexible filtering.

---

## 📌 Inputs
## Inputs

| Name | Description | Required | Default |
| ------------------ | --------------------------------------------------------------------------- | -------- | --------------------------- |
| `threshold-days` | The number of days to keep container package versions. Older versions will be deleted. | No | `7` |
| `included-tags` | A comma-separated list of tags to include for deletion. Wildcards (`*`) are supported. | No | `""` (all tags included) |
| `excluded-tags` | A comma-separated list of tags to exclude from deletion. Wildcards (`*`) are supported.| No | `""` (no tags excluded) |
| `threshold-days` | The number of days to keep package versions. Older versions will be deleted. | No | `7` |
| `included-tags` | A comma-separated list of tags/versions to include for deletion. Wildcards (`*`) are supported. | No | `""` (all tags included, or `*SNAPSHOT*` for Maven) |
| `excluded-tags` | A comma-separated list of tags/versions to exclude from deletion. Wildcards (`*`) are supported.| No | `""` (no tags excluded) |
| `included-patterns`| A comma-separated list of patterns to include for deletion. Wildcards (`*`) are supported. | No | `""` |
| `excluded-patterns`| A comma-separated list of patterns to exclude from deletion. Wildcards (`*`) are supported. | No | `""` |
| `package-type` | Type of package to clean up: `container` or `maven`. | No | `container` |
| `dry-run` | Enable dry-run mode to preview deletions without making changes. | No | `false` |
| `debug` | Enable debug mode for detailed logging. | No | `false` |

---

## 📌 Outputs

This action does not produce any outputs. It performs cleanup operations directly on the container packages.

---

## 📌 Environment Variables
## Environment Variables

| Name | Description | Required |
| --------------- | ------------------------------------------------ | -------- |
Expand All @@ -45,20 +32,20 @@ This action does not produce any outputs. It performs cleanup operations directl

---

## Usage Example
## How to Use

Below are examples of how to use this action in a GitHub Actions workflow for both Docker images and Maven JAR files:

Below is an example of how to use this action in a GitHub Actions workflow:
### Example for Docker Images

```yaml
name: Cleanup Old Docker Images

on:
schedule:
- cron: "0 0 * * 0" # Runs weekly on Sunday at midnight
workflow_dispatch:
inputs:
threshold-days:
description: "Number of days to keep container versions"
description: "Number of days to keep Docker image versions"
required: false
default: "7"
included-tags:
Expand All @@ -68,7 +55,11 @@ on:
excluded-tags:
description: "Tags to exclude from deletion"
required: false
default: "release*"
default: ""
debug:
description: "Enable debug mode"
required: false
default: "false"
dry-run:
description: "Enable dry-run mode"
required: false
Expand All @@ -82,84 +73,133 @@ jobs:
- name: Checkout repository
uses: actions/checkout@v4

- name: Run Container Package Cleanup Action
- name: Run Docker Cleanup Action
uses: netcracker/qubership-workflow-hub/actions/container-package-cleanup@main
with:
threshold-days: ${{ github.event.inputs.threshold-days }}
included-tags: ${{ github.event.inputs.included-tags }}
excluded-tags: ${{ github.event.inputs.excluded-tags }}
debug: ${{ github.event.inputs.debug }}
dry-run: ${{ github.event.inputs.dry-run }}
threshold-days: ${{ github.event.inputs.threshold-days || 7 }}
included-tags: ${{ github.event.inputs.included-tags || '' }}
excluded-tags: ${{ github.event.inputs.excluded-tags || '' }}
debug: ${{ github.event.inputs.debug || 'false' }}
dry-run: ${{ github.event.inputs.dry-run || 'false' }}
package-type: container
env:
PACKAGE_TOKEN: ${{ secrets.PACKAGE_TOKEN }}
```

---
### Example for Maven JAR Files

## Additional Information
```yaml
name: Cleanup Old Maven JAR Files

### Debug Mode
on:
workflow_dispatch:
inputs:
threshold-days:
description: "Number of days to keep Maven JAR versions"
required: false
default: "14"
included-patterns:
description: "Patterns to include for deletion"
required: false
default: "*SNAPSHOT*"
excluded-patterns:
description: "Patterns to exclude from deletion"
required: false
default: "release*"
debug:
description: "Enable debug mode"
required: false
default: "false"
dry-run:
description: "Enable dry-run mode"
required: false
default: "false"

When `debug` is set to `true`, the action logs detailed information, including:
jobs:
cleanup:
runs-on: ubuntu-latest

- The calculated threshold date.
- The list of excluded and included tags.
- The list of packages and their versions retrieved from the repository or organization.
- The versions that are selected for deletion after applying the filtering criteria.
steps:
- name: Checkout repository
uses: actions/checkout@v4

This mode is useful for troubleshooting and understanding how the action processes packages and versions.
- name: Run Maven Cleanup Action
uses: netcracker/qubership-workflow-hub/actions/container-package-cleanup@main
with:
threshold-days: ${{ github.event.inputs.threshold-days || 14 }}
included-patterns: ${{ github.event.inputs.included-patterns || '*SNAPSHOT*' }}
excluded-patterns: ${{ github.event.inputs.excluded-patterns || 'release*' }}
debug: ${{ github.event.inputs.debug || 'false' }}
dry-run: ${{ github.event.inputs.dry-run || 'false' }}
package-type: maven
env:
PACKAGE_TOKEN: ${{ secrets.PACKAGE_TOKEN }}
```

---

### Dry-Run Mode
## Usage for Container Images

When `dry-run` is set to `true`, the action will simulate the cleanup process without actually deleting any package versions. It will log the versions that would be deleted if the action were run without `dry-run`.
- Set `package-type: container` (default).
- Filtering by `included-tags` and `excluded-tags` works on image tags.
- Wildcards (`*`) are supported for flexible tag matching.
- All container image versions older than `threshold-days` and matching the tag filters will be deleted (unless `dry-run` is enabled).

This mode is useful for previewing the cleanup results and ensuring the filtering criteria are correct before making changes.
---

## Usage for Maven Packages

- Set `package-type: maven`.
- Filtering by `included-patterns` and `excluded-patterns` works on Maven version names.
- **If you do not specify `included-patterns`, the action will automatically add `*SNAPSHOT*` to the list of included patterns for Maven packages.**
This means that by default, only SNAPSHOT versions will be deleted for Maven, unless you specify other include patterns.
- Wildcards (`*`) are supported for flexible version matching.
- All Maven versions older than `threshold-days` and matching the filters will be deleted (unless `dry-run` is enabled).

---

### Priority of Tag Filtering
## Tag/Version Filtering Logic

The action filters tags in the following order of priority:
The action filters tags/versions in the following order of priority:

1. **Excluded Tags**:
- Versions with tags matching `excluded-tags` are **always skipped**, even if they also match `included-tags`.
- This ensures that excluded tags take precedence over any other filtering criteria.
1. **Excluded Tags/Patterns**:
- Versions matching `excluded-tags` or `excluded-patterns` are **always skipped**, even if they also match `included-tags` or `included-patterns`.

2. **Included Tags**:
- If `included-tags` is specified, only versions with tags matching `included-tags` are considered for deletion.
- Tags that do not match `included-tags` are ignored, unless they are explicitly excluded.
2. **Included Tags/Patterns**:
- If `included-tags` or `included-patterns` is specified, only versions matching these are considered for deletion.

3. **Default Behavior**:
- If `included-tags` is empty, all versions are considered for deletion, except those explicitly excluded by `excluded-tags`.
- If neither `included-tags` nor `included-patterns` is specified, all versions are considered for deletion, except those explicitly excluded by `excluded-tags` or `excluded-patterns`.
- **For Maven:** If neither `included-tags` or `included-patterns` is specified, only `*SNAPSHOT*` versions are considered for deletion by default.

#### Filtering Process

The filtering process works as follows:
1. **Step 1**: Exclude versions with tags matching `excluded-tags`.
2. **Step 2**: From the remaining versions, include only those matching `included-tags` (if specified).
3. **Step 3**: If `included-tags` is not specified, all remaining versions are considered for deletion.
1. Exclude versions matching `excluded-tags` or `excluded-patterns`.
2. From the remaining versions, include only those matching `included-tags` or `included-patterns` (if specified).
3. If neither `included-tags` nor `included-patterns` is specified, all remaining versions are considered for deletion (for Maven, only `*SNAPSHOT*` by default).

---

### Tag Matching Behavior

The action supports flexible tag matching using exact matches and wildcard patterns. This allows you to define which tags should be included or excluded during the cleanup process.

#### Supported Patterns
## Wildcard Matching

1. **Exact Match**: Matches tags exactly as specified (e.g., `release` matches only `release`).
2. **Prefix Match**: Patterns ending with `*` match tags starting with the prefix (e.g., `release*` matches `release-v1`).
3. **Suffix Match**: Patterns starting with `*` match tags ending with the suffix (e.g., `*release` matches `v1-release`).
4. **Substring Match**: Patterns with `*` at both ends match tags containing the substring (e.g., `*release*` matches `v1-release-candidate`).
5. **Wildcard in the Middle**: Patterns with `*` in the middle match tags with any characters in place of `*` (e.g., `release*v1` matches `release-v1`).

#### Examples
Supported patterns for tags/versions:

| Pattern | Matches | Does Not Match |
|---------------|----------------------------------|----------------------|
| `release*` | `release`, `release-v1` | `v1-release` |
| `*release` | `v1-release`, `candidate-release`| `release-v1` |
| `*release*` | `v1-release-candidate`, `release-v1` | `v1-candidate` |
| `release*v1` | `release-v1`, `release-candidate-v1` | `release-v2` |

---

## Debug & Dry-Run Modes

- **Debug Mode:** Set `debug: true` to log detailed information about the filtering and deletion process.
- **Dry-Run Mode:** Set `dry-run: true` to simulate deletions without actually removing any versions.

---

## Feedback

If you have suggestions or find a bug, please create an issue or pull request in this repository.
Loading