Finding jobs triggered by a specific user

Helpful Resources Support Solutions
1

Finding jobs triggered by a specific user

There might be situations where having a list of all jobs triggered by a specific user would be helpful.
Trying to scroll through the pipeline pages can be time consuming and not very effective.

We can use CircleCI’s API to help in automating this process.

Note: For jobs that were rerun, the name of the user who triggered the original job will be returned.

Requirements

We will be using V1 of the API. The documentation can be found on the following page:

CircleCI V1 API

Before using the API, you will need to follow these steps:

  1. Create an API token by visiting your user settings page.
  2. Store your API key as an environmental variable either at the project or context level, or in your local environment.
  3. Additionally, you will need the command-line JSON processor jq installed in your container or local environment.

Setup

I will be referring to the following variables in the steps below.

Variable Name Description
CIRCLE_TOKEN This will be a personal API token.
USER_NAME This will be the name of the user you are searching for
ORG_NAME This will be the name of the org you belong to
PROJECT_NAME This will be the name of the project you are searching for
VCS Github or Bitbucket

The following parameters can also be included in the API requests (filter is limited to solution #1)

Parameter Name Description
limit The number of builds to return. Maximum 100, defaults to 30.
offset The API returns builds starting from this offset, defaults to 0.
shallow An optional boolean parameter that may be sent to improve performance if set to ‘true’.
filter Restricts which builds are returned. Set to “completed”, “successful”, “failed”, “running”, or defaults to no filter.

Note 1: The API will return a maximum of 100 jobs, and the default is set to 30 if the limit parameter is not set.

Note 2: It may be necessary to set the following accept header to get the response in json format:

-H "Accept: application/json"

Solutions

Solution 1 - Find recent jobs triggered by a user for a project

Instead of having to scroll through pipelines to find builds that were triggered by a specific user, utilizing the API to automate this work would be much more efficient. Here I will give an example for finding recent jobs by a user for a specific project.

We will be using the Recent Builds For A Single Project endpoint from V1 of our API:

Calling the API

We can make a call to the endpoint in the following way:

curl https://circleci.com/api/v1.1/project/$VCS/$ORG_NAME/$PROJECT_NAME?limit=100 -H "Circle-Token: $CIRCLE_TOKEN"

This would give us list of the 100 most recent builds. To further restrict it to a specific user, we can use jq.

curl -s https://circleci.com/api/v1.1/project/$VCS/$ORG_NAME/$PROJECT_NAME?limit=100 -H "Circle-Token: $CIRCLE_TOKEN" | jq -r 'select(.[].user.login == "$USER_NAME")'

While this would give us all of the information regarding jobs triggered by the specified user, we may be only interested a couple of things from the response.
We can further filter the data we get to clean up the response.

For example, say I want to get only the following fields: subject, start_time, stop_time, status, build_url, and branch.
I could accomplish this with the following command:

curl -s https://circleci.com/api/v1.1/project/$VCS/$ORG_NAME/$PROJECT_NAME?limit=100 -H "Circle-Token: $CIRCLE_TOKEN" | jq -r 'select(.[].user.login == "$USER_NAME") | {subject,start_time,stop_time,status,build_url,branch}'

This would return JSON like the following:

{
  "subject": "Update config.yml",
  "start_time": "2021-04-21T07:43:52.138Z",
  "stop_time": "2021-04-21T07:44:18.033Z",
  "status": "success",
  "build_url": "https://circleci.com/gh/test/test-queue-job/13",
  "branch": "main"
}

Solution 2 - Find all recent jobs for a specific user

Instead of specifying a specific project, let’s say we want to get recent jobs for a specific user across all projects.

We will be using the Recent Builds Across All Projects endpoint from V1 of our API:

Calling the API

We can make a call to the endpoint in the following way:

curl -s https://circleci.com/api/v1.1/recent-builds?limit=100 -H "Circle-Token: $CIRCLE_TOKEN"

This request would return data for the last 100 jobs triggered. To further limit it to one user, we can make a request such as the following:

curl -s https://circleci.com/api/v1.1/recent-builds?limit=100 -H "Circle-Token: $CIRCLE_TOKEN" | jq -r 'select(.[].user.login == "$USER_NAME")'

Lastly, we could further filter the data to contain only the following information: reponame, subject, start_time, stop_time, status, build_url, and branch.

curl -s https://circleci.com/api/v1.1/recent-builds?limit=100 -H "Circle-Token: $CIRCLE_TOKEN" | jq '.[] | select(.user.login == "$USER_NAME") | {reponame,subject,start_time,stop_time,status,build_url,branch}'

This would return JSON like the following:

{
  "reponame": "test-orb-template",
  "subject": "Update config.yml",
  "start_time": "2021-02-16T01:53:52.228Z",
  "stop_time": "2021-02-16T02:03:57.246Z",
  "status": "failed",
  "build_url": "https://circleci.com/gh/test/test/137",
  "branch": "test1"
}

Resources

The preceeding solutions were created using V1 of our API for which the documentation can be found here:

https://circleci.com/docs/api/v1/#circleci-v1-api-overview

For more information about how to use jq, please take a look at the developer manual:

https://stedolan.github.io/jq/manual/

2 Likes