Programmatically query the number of commits in a single project during a specified time period
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
Release notes
Programmatically query the number of commits in a single project during a specified time period.
Problem to solve
As a developer or manager of developers, I want to be able to programmatically* query the number of commits made to a certain project within a specified time interval so that I can understand where developers are spending their time and identify trends in these results over time.
(* - The goal is to be able to use the API to retrieve this information.)
Intended users
- Delaney (Development Team Lead)
- Devon (DevOps Engineer)
- Sidney (Systems Administrator)
- Sam (Security Analyst)
- Rachel (Release Manager)
- Alex (Security Operations Engineer)
- Simone (Software Engineer in Test)
- Priyanka (Platform Engineer)
- Dana (Data Analyst)
User experience goal
The user should be able to use the API to get information about the number of commits that were made to a specific project during a specified time interval:
- User makes authenticated call to API with these parameters: project ID, start date and time, end date and time
- Successful response from the API includes the total number of commits made to the specified project between the specified start date and time and the specified end date and time
- The user can implement custom code that consumes the API response, extract the number of commits and use that value for further processing.
Proposal
Update the commits API or the projects API to permit the user to make a request like the one described above.
Further details
It was previously possible to use the X-Total HTTP response header returned in a call like the following to solve the problem described above:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits?since=2020-11-09T11:40:24.000-04:00&until=2020-11-10-T11:40:24.000-04"This header was excluded from the commits API as part of an effort to improve Gitaly performance.
I am filing this feature proposal on behalf of a customer who used to rely on X-Total for this functionality, noticed that it was missing after upgrading and would like some method of getting this functionality back. GitLab team members with access to ZenDesk can learn more by viewing the ticket that led to this feature proposal.
NOTE: The X-Total approach worked with some limitations. Prior to the MR that removed the X-Total header altogether, the X-Total header was omitted when a project went beyond 10,000 commits.
Alternative Approaches
statistics.commit_count
The value in statistics.commit_count response from the projects API is not a viable solution because it is a sum over the lifetime of a project and does not allow for collecting a commit count during a specific date range.
Count commits
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits?since=2020-11-09T11:40:24.000-04:00&until=2020-11-10-T11:40:24.000-04"Looping through the results of an API call like the one shown above would solve the problem but it has downsides, specifically:
- This approach requires making multiple GET requests per repo in order to count commits where the previous solution only required one GET request per repository
- As a result of the additional requests, the counting process is more inefficient.
Repository analytics
Being able to query the data in the "Commits per day of month" chart in Repository Analytics via the API would be a potentially useful approach. While this approach would not permit the user to specify a time alongside the date, it does get much closer to the desired functionality without requiring the user to resort to counting individual commits.
Permissions and Security
I suspect that the permissions required to perform the described actions should match who is permitted to make the list repository commits API call.
Documentation
The documentation requirements will depend on how this is implemented. If this is implemented by adding to the response to the list repository commits request, that page will need to be updated.
Availability & Testing
What does success look like, and how can we measure that?
What is the type of buyer?
Is this a cross-stage feature?
Links / references
Here are a few issues where we can see folks are relying on the presence of the X-Total header: