@@ -10,9 +10,18 @@ sources:
         kind: semver
         pattern: "~0"
 
+  latest:
+    kind: gitlab/release
+    spec:
+      owner: "olblak"
+      repository: "updatecli"
+      age:
+        minimum: 4y
+
 conditions:
   default:
     kind: gitlab/release
+    disablesourceinput: true
     spec:
       owner: "olblak"
       repository: "updatecli"
@@ -24,4 +33,3 @@ conditions:
       url: "gitlab.com"
       owner: "olblak"
       repository: "updatecli"
-
 
@@ -0,0 +1,155 @@
+package release
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/updatecli/updatecli/pkg/plugins/utils/age"
+	gitlab "gitlab.com/gitlab-org/api/client-go"
+)
+
+// daysAgo formats a date n days in the past the way the GitLab API reports one.
+func daysAgo(n int) string {
+	return time.Now().Add(-time.Duration(n) * 24 * time.Hour).Format(time.RFC3339)
+}
+
+// newReleaseServer serves a single page of releases, so that the age filtering is
+// exercised without reaching the real GitLab API.
+func newReleaseServer(t *testing.T, releases ...string) *httptest.Server {
+	t.Helper()
+	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		fmt.Fprintf(w, "[%s]", strings.Join(releases, ","))
+	}))
+}
+
+func releaseJSON(tag, released string, upcoming bool) string {
+	return fmt.Sprintf(`{"tag_name":%q,"released_at":%q,"created_at":%q,"upcoming_release":%t}`,
+		tag, released, released, upcoming)
+}
+
+func newReleaseResource(t *testing.T, url string, releaseAge age.Spec) *Gitlab {
+	t.Helper()
+	resource, err := New(map[string]interface{}{
+		"url":        url,
+		"owner":      "updatecli",
+		"repository": "updatecli",
+		"age":        map[string]interface{}{"minimum": releaseAge.Minimum, "maximum": releaseAge.Maximum},
+	})
+	require.NoError(t, err)
+	return resource
+}
+
+func TestSearchReleasesAge(t *testing.T) {
+	// GitLab returns the most recent release first and SearchReleases reverses that,
+	// so the expected values below read oldest first.
+	releases := []string{
+		releaseJSON("v3.0.0", daysAgo(1), false),
+		releaseJSON("v2.0.0", daysAgo(10), false),
+		releaseJSON("v1.0.0", daysAgo(30), false),
+	}
+
+	tests := []struct {
+		name       string
+		releaseAge age.Spec
+		releases   []string
+		want       []string
+		wantSkip   bool
+	}{
+		{
+			name:     "no age filter keeps every release",
+			releases: releases,
+			want:     []string{"v1.0.0", "v2.0.0", "v3.0.0"},
+		},
+		{
+			name:       "the most recent release is still in cooldown",
+			releaseAge: age.Spec{Minimum: "7d"},
+			releases:   releases,
+			want:       []string{"v1.0.0", "v2.0.0"},
+		},
+		{
+			name:       "releases published too long ago are discarded",
+			releaseAge: age.Spec{Maximum: "20d"},
+			releases:   releases,
+			want:       []string{"v2.0.0", "v3.0.0"},
+		},
+		{
+			name:       "every release still in cooldown reports a running cooldown",
+			releaseAge: age.Spec{Minimum: "60d"},
+			releases:   releases,
+			wantSkip:   true,
+		},
+		{
+			name:       "an upcoming release is not mistaken for a cooling down one",
+			releaseAge: age.Spec{Minimum: "7d"},
+			releases: []string{
+				releaseJSON("v4.0.0", daysAgo(-1), true),
+				releaseJSON("v1.0.0", daysAgo(30), false),
+			},
+			want: []string{"v1.0.0"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			server := newReleaseServer(t, tt.releases...)
+			defer server.Close()
+
+			got, err := newReleaseResource(t, server.URL, tt.releaseAge).SearchReleases(tt.releaseAge)
+
+			if tt.wantSkip {
+				require.Error(t, err)
+				assert.ErrorIs(t, err, age.ErrNoVersionMatchingAge)
+				return
+			}
+
+			require.NoError(t, err)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestReleaseDate(t *testing.T) {
+	released := time.Now().Add(-24 * time.Hour)
+	created := time.Now().Add(-48 * time.Hour)
+
+	tests := []struct {
+		name    string
+		release gitlab.Release
+		want    time.Time
+		wantOk  bool
+	}{
+		{
+			name:    "the release date wins",
+			release: gitlab.Release{ReleasedAt: &released, CreatedAt: &created},
+			want:    released,
+			wantOk:  true,
+		},
+		{
+			name:    "the creation date is the fallback",
+			release: gitlab.Release{CreatedAt: &created},
+			want:    created,
+			wantOk:  true,
+		},
+		{
+			name:    "a release without any date reports none",
+			release: gitlab.Release{},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, ok := releaseDate(&tt.release)
+			assert.Equal(t, tt.wantOk, ok)
+			if tt.wantOk {
+				assert.Equal(t, tt.want, got)
+			}
+		})
+	}
+}
@@ -6,14 +6,17 @@ import (
 
 	"github.com/sirupsen/logrus"
 	"github.com/updatecli/updatecli/pkg/core/pipeline/scm"
+	"github.com/updatecli/updatecli/pkg/plugins/utils/age"
 )
 
 func (g *Gitlab) Condition(_ context.Context, source string, scm scm.ScmHandler) (pass bool, message string, err error) {
 	if scm != nil {
 		logrus.Warningf("Condition not supported for the plugin GitLab release")
 	}
 
-	releases, err := g.SearchReleases()
+	// A condition checks whether a specific release exists, so the age filter, which
+	// only narrows down which release to pick, doesn't apply here.
+	releases, err := g.SearchReleases(age.Spec{})
 	if err != nil {
 		return false, "", fmt.Errorf("looking for GitLab release: %w", err)
 	}
 
@@ -3,12 +3,14 @@ package release
 import (
 	"context"
 	"fmt"
+	"slices"
 	"strings"
 	"time"
 
 	"github.com/go-viper/mapstructure/v2"
 	"github.com/sirupsen/logrus"
 	"github.com/updatecli/updatecli/pkg/plugins/resources/gitlab/client"
+	"github.com/updatecli/updatecli/pkg/plugins/utils/age"
 	"github.com/updatecli/updatecli/pkg/plugins/utils/redact"
 	"github.com/updatecli/updatecli/pkg/plugins/utils/version"
 	gitlab "gitlab.com/gitlab-org/api/client-go"
@@ -23,6 +25,11 @@ type Spec struct {
 	Repository string `yaml:",omitempty" jsonschema:"required"`
 	// [S] VersionFilter provides parameters to specify version pattern and its type like regex, semver, or just latest.
 	VersionFilter version.Filter `yaml:",omitempty"`
+	// [S] Age defines the minimum or maximum age of a release to be considered valid.
+	// It accepts a duration string (e.g., "24h", "7d", "3w", "1y").
+	// The age of a release is the date at which it was released, or the date at which
+	// it was created for a release published without one.
+	Age age.Spec `yaml:",omitempty"`
 	// [T] Title defines the GitLab release title.
 	Title string `yaml:",omitempty"`
 	// [C][T] Tag defines the GitLab release tag.
@@ -100,18 +107,24 @@ func New(spec interface{}) (*Gitlab, error) {
 	return &g, nil
 }
 
-// Retrieve git tags from a remote GitLab repository
-func (g *Gitlab) SearchReleases() ([]string, error) {
+// SearchReleases retrieves the release tags from a remote GitLab repository, keeping
+// only the ones released inside the provided age window. The returned tags are ordered
+// from the oldest to the most recent one, as expected by the version filters.
+func (g *Gitlab) SearchReleases(releaseAge age.Spec) ([]string, error) {
 
 	ctx := context.Background()
 	// Timeout api query after 30sec
 	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
 	defer cancel()
 
 	results := []string{}
-	page := 0
+	// Tracks whether the repository publishes releases at all, so that a running
+	// cooldown isn't reported as a repository without any release.
+	foundRelease := false
+	// GitLab paginates from page 1, so starting anywhere else fetches the first page twice.
+	page := int64(1)
 	for {
-		opt := &gitlab.ListReleasesOptions{ListOptions: gitlab.ListOptions{Page: int64(page), PerPage: 30}}
+		opt := &gitlab.ListReleasesOptions{ListOptions: gitlab.ListOptions{Page: page, PerPage: 30}}
 
 		releases, resp, err := g.client.Releases.ListReleases(
 			g.getPID(),
@@ -127,22 +140,66 @@ func (g *Gitlab) SearchReleases() ([]string, error) {
 			logrus.Debugf("GitLab Api Response:\n%+v", resp)
 		}
 
-		for i := len(releases) - 1; i >= 0; i-- {
-			if !releases[i].UpcomingRelease {
-				results = append(results, releases[i].TagName)
+		for _, release := range releases {
+			if release.UpcomingRelease {
+				continue
 			}
+			foundRelease = true
+
+			if !releaseAge.IsZero() {
+				date, ok := releaseDate(release)
+				if !ok {
+					logrus.Debugf("ignoring release %q, which carries no date, as the age filter cannot be applied to it", release.TagName)
+					continue
+				}
+				if !releaseAge.Matches(date) {
+					logrus.Debugf("ignoring release %q, dated %s, as outside of the age window", release.TagName, date)
+					continue
+				}
+			}
+
+			results = append(results, release.TagName)
 		}
 
-		// Means that we parsed all pages
-		if int64(page) >= resp.NextPage {
+		// GitLab reports no next page once the last one has been visited.
+		if resp.NextPage == 0 {
 			break
 		}
-		page++
+		page = resp.NextPage
+	}
+
+	/*
+		The repository does publish releases but the age filter discarded every one of
+		them, which means the release we would have returned is still cooling down.
+		That's not a lookup failure, so the sentinel lets the caller skip rather than
+		fail.
+	*/
+	if !releaseAge.IsZero() && foundRelease && len(results) == 0 {
+		return nil, fmt.Errorf("%w for the GitLab releases of %s", age.ErrNoVersionMatchingAge, g.getPID())
 	}
 
+	// GitLab returns the most recent release first, while the version filters expect
+	// the oldest one first, such as when they pick the last element for the "latest"
+	// kind. Reversing the whole list, rather than each page, keeps the releases ordered
+	// across page boundaries too.
+	slices.Reverse(results)
+
 	return results, nil
 }
 
+// releaseDate returns the date at which a release became public, and whether GitLab
+// reported one. The release date is left empty for a release created without one, so
+// the creation date is used as a fallback.
+func releaseDate(r *gitlab.Release) (time.Time, bool) {
+	if r.ReleasedAt != nil && !r.ReleasedAt.IsZero() {
+		return *r.ReleasedAt, true
+	}
+	if r.CreatedAt != nil && !r.CreatedAt.IsZero() {
+		return *r.CreatedAt, true
+	}
+	return time.Time{}, false
+}
+
 func (s Spec) Validate() error {
 	gotError := false
 	missingParameters := []string{}
@@ -157,6 +214,11 @@ func (s Spec) Validate() error {
 		missingParameters = append(missingParameters, "repository")
 	}
 
+	if err := s.Age.Validate(); err != nil {
+		gotError = true
+		logrus.Errorln(err)
+	}
+
 	if len(missingParameters) > 0 {
 		logrus.Errorf("missing parameter(s) [%s]", strings.Join(missingParameters, ","))
 	}
@@ -179,6 +241,7 @@ func (g *Gitlab) ReportConfig() interface{} {
 		},
 		Repository:    g.spec.Repository,
 		VersionFilter: g.spec.VersionFilter,
+		Age:           g.spec.Age,
 		Tag:           g.spec.Tag,
 	}
 }
Original file line number	Diff line number	Diff line change
`@@ -6,14 +6,17 @@ import (`
`6`	`6`
`7`	`7`	`"github.com/sirupsen/logrus"`
`8`	`8`	`"github.com/updatecli/updatecli/pkg/core/pipeline/scm"`
	`9`	`+ "github.com/updatecli/updatecli/pkg/plugins/utils/age"`
`9`	`10`	`)`
`10`	`11`
`11`	`12`	`func (g *Gitlab) Condition(_ context.Context, source string, scm scm.ScmHandler) (pass bool, message string, err error) {`
`12`	`13`	`if scm != nil {`
`13`	`14`	`logrus.Warningf("Condition not supported for the plugin GitLab release")`
`14`	`15`	`}`
`15`	`16`
`16`		`- releases, err := g.SearchReleases()`
	`17`	`+ // A condition checks whether a specific release exists, so the age filter, which`
	`18`	`+ // only narrows down which release to pick, doesn't apply here.`
	`19`	`+ releases, err := g.SearchReleases(age.Spec{})`
`17`	`20`	`if err != nil {`
`18`	`21`	`return false, "", fmt.Errorf("looking for GitLab release: %w", err)`
`19`	`22`	`}`