feat: add 'GetLatest' method to 'IPipelineClient' (#922)

msrouchou · web-flow · commit 17cdbd7c1638 · 2025-06-30T09:41:02.000-04:00
* feat: add 'GetLatest' method to 'IPipelineClient' - Resolves #920 * Add unit tests * Failing pipeline * fix: update GetLatestAsync method to use correct pipelines path * test: add unit test for handling forbidden response on non-existing pipeline ref * fix: update comment to clarify behavior for invalid refs in GetLatestAsync method
diff --git a/NGitLab.Mock/Clients/PipelineClient.cs b/NGitLab.Mock/Clients/PipelineClient.cs
@@ -51,6 +51,22 @@ public IEnumerable<PipelineBasic> All
 
     public IEnumerable<Models.Job> AllJobs => _jobClient.GetJobs(JobScopeMask.All);
 
+    public Task<Models.Pipeline> GetLatestAsync(string @ref, CancellationToken cancellationToken = default)
+    {
+        using (Context.BeginOperationScope())
+        {
+            var project = GetProject(_projectId, ProjectPermission.View);
+            var pipeline = project.Pipelines.GetLatest(@ref);
+            if (pipeline != null)
+            {
+                return Task.FromResult(pipeline.ToPipelineClient());
+            }
+
+            // GitLab returns 403 Forbidden if the ref is invalid, so we mimic that behavior here
+            throw GitLabException.Forbidden();
+        }
+    }
+
     public Models.Pipeline Create(string @ref)
     {
         using (Context.BeginOperationScope())
diff --git a/NGitLab.Mock/PipelineCollection.cs b/NGitLab.Mock/PipelineCollection.cs
@@ -19,6 +19,16 @@ public Pipeline GetById(long id)
         return this.FirstOrDefault(pipeline => pipeline.Id == id);
     }
 
+    public Pipeline GetLatest(string @ref)
+    {
+        var branchName = string.IsNullOrWhiteSpace(@ref) ? _project.DefaultBranch : @ref;
+
+        return this
+            .Where(pipeline => string.Equals(pipeline.Ref, branchName, StringComparison.OrdinalIgnoreCase))
+            .OrderByDescending(pipeline => pipeline.CreatedAt)
+            .FirstOrDefault();
+    }
+
     public override void Add(Pipeline pipeline)
     {
         if (pipeline is null)
diff --git a/NGitLab.Mock/PublicAPI.Unshipped.txt b/NGitLab.Mock/PublicAPI.Unshipped.txt
@@ -837,6 +837,7 @@ NGitLab.Mock.Pipeline.YamlError.set -> void
 NGitLab.Mock.PipelineCollection
 NGitLab.Mock.PipelineCollection.Add(string ref, NGitLab.JobStatus status, NGitLab.Mock.User user) -> NGitLab.Mock.Pipeline
 NGitLab.Mock.PipelineCollection.GetById(long id) -> NGitLab.Mock.Pipeline
+NGitLab.Mock.PipelineCollection.GetLatest(string ref) -> NGitLab.Mock.Pipeline
 NGitLab.Mock.PipelineCollection.PipelineCollection(NGitLab.Mock.GitLabObject parent) -> void
 NGitLab.Mock.PipelineSchedule
 NGitLab.Mock.PipelineSchedule.Active.get -> bool
diff --git a/NGitLab.Tests/Docker/GitLabTestContext.cs b/NGitLab.Tests/Docker/GitLabTestContext.cs
@@ -465,6 +465,24 @@ public static async Task<T> RetryUntilAsync<T>(Func<T> action, Func<T, bool> pre
         return await RetryUntilAsync(action, predicate, cts.Token).ConfigureAwait(false);
     }
 
+    public static async Task<T> RetryUntilAsync<T>(Func<Task<T>> action, Func<T, Task<bool>> predicate, TimeSpan timeSpan)
+    {
+        using var cts = new CancellationTokenSource(timeSpan);
+        return await RetryUntilAsync(action, predicate, cts.Token).ConfigureAwait(false);
+    }
+
+    public static async Task<T> RetryUntilAsync<T>(Func<Task<T>> action, Func<T, Task<bool>> predicate, CancellationToken cancellationToken)
+    {
+        while (true)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            var result = await action().ConfigureAwait(false);
+            if (await predicate(result).ConfigureAwait(false))
+                return result;
+            await Task.Delay(1000, cancellationToken).ConfigureAwait(false);
+        }
+    }
+
     public static async Task<T> RetryUntilAsync<T>(Func<T> action, Func<T, bool> predicate, CancellationToken cancellationToken)
     {
         var retryCount = 1;
diff --git a/NGitLab.Tests/PipelineTests.cs b/NGitLab.Tests/PipelineTests.cs
@@ -31,6 +31,52 @@ public async Task Test_can_list_the_pipelines()
         }
     }
 
+    [Test]
+    [NGitLabRetry]
+    public async Task Test_can_get_latest_pipeline()
+    {
+        using var context = await GitLabTestContext.CreateAsync();
+        var project = context.CreateProject();
+        var pipelineClient = context.Client.GetPipelines(project.Id);
+        JobTests.AddGitLabCiFile(context.Client, project);
+        Pipeline latestPipeline;
+        using (await context.StartRunnerForOneJobAsync(project.Id))
+        {
+            latestPipeline = await GitLabTestContext.RetryUntilAsync(
+                () => pipelineClient.GetLatestAsync(project.DefaultBranch),
+                p => Task.FromResult(p != null),
+                TimeSpan.FromSeconds(120));
+        }
+
+        Assert.That(latestPipeline, Is.Not.Null);
+        Assert.That(latestPipeline.ProjectId, Is.EqualTo(project.Id));
+    }
+
+    [Test]
+    [NGitLabRetry]
+    public async Task Test_get_latest_pipeline_for_non_existing_ref_returns_forbidden()
+    {
+        using var context = await GitLabTestContext.CreateAsync();
+        var project = context.CreateProject();
+        var pipelineClient = context.Client.GetPipelines(project.Id);
+        JobTests.AddGitLabCiFile(context.Client, project);
+
+        const string nonExistingRef = "non-existing-branch";
+
+        GitLabException exception = null;
+        try
+        {
+            await pipelineClient.GetLatestAsync(nonExistingRef);
+        }
+        catch (GitLabException ex) when (ex.StatusCode == HttpStatusCode.Forbidden)
+        {
+            exception = ex;
+        }
+
+        Assert.That(exception, Is.Not.Null, "Expected a Forbidden exception when retrieving the latest pipeline for a non-existing ref.");
+        Assert.That(exception.StatusCode, Is.EqualTo(HttpStatusCode.Forbidden));
+    }
+
     [Test]
     [NGitLabRetry]
     public async Task Test_can_get_coverage()
diff --git a/NGitLab/IPipelineClient.cs b/NGitLab/IPipelineClient.cs
@@ -26,6 +26,16 @@ public interface IPipelineClient
     /// </summary>
     IEnumerable<Job> AllJobs { get; }
 
+    /// <summary>
+    /// Retrieves the latest pipeline associated with the specified reference.
+    /// </summary>
+    /// <remarks>Use this method to retrieve the most recent pipeline for a given branch or tag
+    /// tag.</remarks>
+    /// <param name="ref">Optional reference (e.g., branch name or tag) for which to retrieve the latest pipeline.
+    /// Defaults to the default branch when not specified.</param>
+    /// <returns>The task result contains the latest <see cref="Pipeline"/> associated with the specified reference.</returns>
+    Task<Pipeline> GetLatestAsync(string @ref, CancellationToken cancellationToken = default);
+
     GitLabCollectionResponse<Job> GetAllJobsAsync();
 
     /// <summary>
diff --git a/NGitLab/Impl/PipelineClient.cs b/NGitLab/Impl/PipelineClient.cs
@@ -26,6 +26,12 @@ public PipelineClient(API api, ProjectId projectId)
 
     public IEnumerable<Job> AllJobs => _api.Get().GetAll<Job>($"{_projectPath}/jobs");
 
+    public Task<Pipeline> GetLatestAsync(string @ref, CancellationToken cancellationToken = default)
+    {
+        var urlParameter = string.IsNullOrWhiteSpace(@ref) ? string.Empty : $"?ref={Uri.EscapeDataString(@ref)}";
+        return _api.Get().ToAsync<Pipeline>($"{_pipelinesPath}/latest{urlParameter}", cancellationToken);
+    }
+
     public GitLabCollectionResponse<Job> GetAllJobsAsync()
     {
         return _api.Get().GetAllAsync<Job>($"{_projectPath}/jobs");
diff --git a/NGitLab/PublicAPI/net472/PublicAPI.Unshipped.txt b/NGitLab/PublicAPI/net472/PublicAPI.Unshipped.txt
@@ -816,6 +816,7 @@ NGitLab.Impl.PipelineClient.GetByIdAsync(long id, System.Threading.CancellationT
 NGitLab.Impl.PipelineClient.GetJobs(long pipelineId) -> NGitLab.Models.Job[]
 NGitLab.Impl.PipelineClient.GetJobs(NGitLab.Models.PipelineJobQuery query) -> System.Collections.Generic.IEnumerable<NGitLab.Models.Job>
 NGitLab.Impl.PipelineClient.GetJobsAsync(NGitLab.Models.PipelineJobQuery query) -> NGitLab.GitLabCollectionResponse<NGitLab.Models.Job>
+NGitLab.Impl.PipelineClient.GetLatestAsync(string ref, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<NGitLab.Models.Pipeline>
 NGitLab.Impl.PipelineClient.GetTestReports(long pipelineId) -> NGitLab.Models.TestReport
 NGitLab.Impl.PipelineClient.GetTestReportsSummary(long pipelineId) -> NGitLab.Models.TestReportSummary
 NGitLab.Impl.PipelineClient.GetVariables(long pipelineId) -> System.Collections.Generic.IEnumerable<NGitLab.Models.PipelineVariable>
@@ -1013,6 +1014,7 @@ NGitLab.IPipelineClient.GetByIdAsync(long id, System.Threading.CancellationToken
 NGitLab.IPipelineClient.GetJobs(long pipelineId) -> NGitLab.Models.Job[]
 NGitLab.IPipelineClient.GetJobs(NGitLab.Models.PipelineJobQuery query) -> System.Collections.Generic.IEnumerable<NGitLab.Models.Job>
 NGitLab.IPipelineClient.GetJobsAsync(NGitLab.Models.PipelineJobQuery query) -> NGitLab.GitLabCollectionResponse<NGitLab.Models.Job>
+NGitLab.IPipelineClient.GetLatestAsync(string ref, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<NGitLab.Models.Pipeline>
 NGitLab.IPipelineClient.GetTestReports(long pipelineId) -> NGitLab.Models.TestReport
 NGitLab.IPipelineClient.GetTestReportsSummary(long pipelineId) -> NGitLab.Models.TestReportSummary
 NGitLab.IPipelineClient.GetVariables(long pipelineId) -> System.Collections.Generic.IEnumerable<NGitLab.Models.PipelineVariable>
diff --git a/NGitLab/PublicAPI/net8.0/PublicAPI.Unshipped.txt b/NGitLab/PublicAPI/net8.0/PublicAPI.Unshipped.txt
@@ -815,6 +815,7 @@ NGitLab.Impl.PipelineClient.GetByIdAsync(long id, System.Threading.CancellationT
 NGitLab.Impl.PipelineClient.GetJobs(long pipelineId) -> NGitLab.Models.Job[]
 NGitLab.Impl.PipelineClient.GetJobs(NGitLab.Models.PipelineJobQuery query) -> System.Collections.Generic.IEnumerable<NGitLab.Models.Job>
 NGitLab.Impl.PipelineClient.GetJobsAsync(NGitLab.Models.PipelineJobQuery query) -> NGitLab.GitLabCollectionResponse<NGitLab.Models.Job>
+NGitLab.Impl.PipelineClient.GetLatestAsync(string ref, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<NGitLab.Models.Pipeline>
 NGitLab.Impl.PipelineClient.GetTestReports(long pipelineId) -> NGitLab.Models.TestReport
 NGitLab.Impl.PipelineClient.GetTestReportsSummary(long pipelineId) -> NGitLab.Models.TestReportSummary
 NGitLab.Impl.PipelineClient.GetVariables(long pipelineId) -> System.Collections.Generic.IEnumerable<NGitLab.Models.PipelineVariable>
@@ -1012,6 +1013,7 @@ NGitLab.IPipelineClient.GetByIdAsync(long id, System.Threading.CancellationToken
 NGitLab.IPipelineClient.GetJobs(long pipelineId) -> NGitLab.Models.Job[]
 NGitLab.IPipelineClient.GetJobs(NGitLab.Models.PipelineJobQuery query) -> System.Collections.Generic.IEnumerable<NGitLab.Models.Job>
 NGitLab.IPipelineClient.GetJobsAsync(NGitLab.Models.PipelineJobQuery query) -> NGitLab.GitLabCollectionResponse<NGitLab.Models.Job>
+NGitLab.IPipelineClient.GetLatestAsync(string ref, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<NGitLab.Models.Pipeline>
 NGitLab.IPipelineClient.GetTestReports(long pipelineId) -> NGitLab.Models.TestReport
 NGitLab.IPipelineClient.GetTestReportsSummary(long pipelineId) -> NGitLab.Models.TestReportSummary
 NGitLab.IPipelineClient.GetVariables(long pipelineId) -> System.Collections.Generic.IEnumerable<NGitLab.Models.PipelineVariable>
diff --git a/NGitLab/PublicAPI/netstandard2.0/PublicAPI.Unshipped.txt b/NGitLab/PublicAPI/netstandard2.0/PublicAPI.Unshipped.txt
@@ -816,6 +816,7 @@ NGitLab.Impl.PipelineClient.GetByIdAsync(long id, System.Threading.CancellationT
 NGitLab.Impl.PipelineClient.GetJobs(long pipelineId) -> NGitLab.Models.Job[]
 NGitLab.Impl.PipelineClient.GetJobs(NGitLab.Models.PipelineJobQuery query) -> System.Collections.Generic.IEnumerable<NGitLab.Models.Job>
 NGitLab.Impl.PipelineClient.GetJobsAsync(NGitLab.Models.PipelineJobQuery query) -> NGitLab.GitLabCollectionResponse<NGitLab.Models.Job>
+NGitLab.Impl.PipelineClient.GetLatestAsync(string ref, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<NGitLab.Models.Pipeline>
 NGitLab.Impl.PipelineClient.GetTestReports(long pipelineId) -> NGitLab.Models.TestReport
 NGitLab.Impl.PipelineClient.GetTestReportsSummary(long pipelineId) -> NGitLab.Models.TestReportSummary
 NGitLab.Impl.PipelineClient.GetVariables(long pipelineId) -> System.Collections.Generic.IEnumerable<NGitLab.Models.PipelineVariable>
@@ -1013,6 +1014,7 @@ NGitLab.IPipelineClient.GetByIdAsync(long id, System.Threading.CancellationToken
 NGitLab.IPipelineClient.GetJobs(long pipelineId) -> NGitLab.Models.Job[]
 NGitLab.IPipelineClient.GetJobs(NGitLab.Models.PipelineJobQuery query) -> System.Collections.Generic.IEnumerable<NGitLab.Models.Job>
 NGitLab.IPipelineClient.GetJobsAsync(NGitLab.Models.PipelineJobQuery query) -> NGitLab.GitLabCollectionResponse<NGitLab.Models.Job>
+NGitLab.IPipelineClient.GetLatestAsync(string ref, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<NGitLab.Models.Pipeline>
 NGitLab.IPipelineClient.GetTestReports(long pipelineId) -> NGitLab.Models.TestReport
 NGitLab.IPipelineClient.GetTestReportsSummary(long pipelineId) -> NGitLab.Models.TestReportSummary
 NGitLab.IPipelineClient.GetVariables(long pipelineId) -> System.Collections.Generic.IEnumerable<NGitLab.Models.PipelineVariable>
