gerrit API

• basic usage

  • regular options

  • sending data

  • verifying header content

• change

• who approval the CR+2

• get all vote CR-2

• who approval the V+1

• access list contains account

• all reviews at a certain time

• get review rate in certain time

• list all projects

• list gerrit projects with certain account

• list project configure

• comments

  • get inline comments

  • set review

• reference

reference:

• Gerrit Code Review - REST API Developers' Notes

• Gerrit Code Review - REST API

• go gerrit - index

• Class com.google.gerrit.extensions.api.access.ProjectAccessInfo

basic usage

regular options

                                  a might means [a]pi
                                    ⇡
$ curl -X PUT    http://domain.name/a/path/to/api/
$ curl -X POST   http://domain.name/a/path/to/api/
$ curl -X DELETE http://domain.name/a/path/to/api/

sending data

• json with file

  $ curl -X PUT \
         [e-mail] \
         --header "Content-Type: application/json" \
         http://domain.name/a/path/to/api/

• json with string

  $ curl -X POST \
         -H "Content-Type: application/json" https://domain.name/a/changes/<number>/move \
         -d '{ "destination_branch" : "target/branch/name" }'
  )]}'
  {
    "id": "marslo-project~target%2Fbranch%2Fname~Id90057ab632eb93be2fa9128a9d624664008cb4a",
    "project": "marslo-project",
    "branch": "target/branch/name",
    "hashtags": [],
    "change_id": "Id90057ab632eb93be2fa9128a9d624664008cb4a",
    "subject": "marslo: testing api move",
    "status": "NEW",
    "created": "2022-01-21 05:21:25.000000000",
    "updated": "2022-05-17 06:56:37.000000000",
    "submit_type": "FAST_FORWARD_ONLY",
    "mergeable": false,
    "insertions": 8,
    "deletions": 8,
    "unresolved_comment_count": 0,
    "has_review_started": true,
    "_number": 94490,
    "owner": {
      "_account_id": 790
    },
    "requirements": []
  }
  
  # or
  $ curl -X POST \
         -H "Content-Type: application/json" https://domain.name/a/changes/<number>/move \
         -d '{
              "destination_branch" : "target/branch/name"
             }' |
    tail -n +2 |
    jq -r .branch

• txt

  $ curl -X PUT \
         --data-binary @testdata.txt \
         --header "Content-Type: text/plain" \
         http://domain.name/a/path/to/api/

verifying header content

$ curl -v -n -X DELETE http://domain.name/a/path/to/api/

change

• get change via change-id

  $ curl -X GET 'https://domina.name/a/changes/<change-id>'

• get change via commit-id

  $ changeid=$(git show <commit-id> --no-patch --format="%s%n%n%b" | sed -nre 's!Change-Id: (.*$)!\1!p')
  $ curl -X GET "https://domina.name/a/changes/${changeid}"
  
  # or
  $ project=$(echo 'path/to/project' | sed 's:/:%2F:g')
  $ branch='dev'
  $ changeid=$(git show <commit-id> --no-patch --format="%s%n%n%b" | sed -nre 's!Change-Id: (.*$)!\1!p')
  $ curl -X GET "https://domina.name/a/changes/${project}~${branch}~${changeid}"

who approval the CR+2

$ curl -s -X GET https://domain.name/a/changes/${changeid}/detail |
       tail -n +2 |
       jq -r '.labels."Code-Review".approved.name'

get all vote CR-2

• example output for .labels.<tag>.all[]

  {
    "value": -2,
    "date": "2021-05-31 07:57:14.000000000",
    "permitted_voting_range": {
      "min": -2,
      "max": 2
    },
    "_account_id": 790,
    "name": "Marslo Jiao",
    "email": "[e-mail]",
    "username": "marslo"
  }
  {
    "value": 0,
    "permitted_voting_range": {
      "min": -2,
      "max": 2
    },
    "_account_id": 124,
    "name": "John Doe",
    "email": "[e-mail]",
    "username": "john"
  }

reference:

• Select objects based on value of variable in object using jq

• jq select or statement

• How to select items in JQ based on value in array

$ curl -s -X GET https://domain.name/a/changes/${changeid}/detail |
       tail -n +2 |
       jq -r '.labels."Code-Review".all[] | select ( .value == -2 ) | .username'
#                                         : |⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂| :
#                                         :           ⇣             :
#                                         :  select ".value"== -2   :
#                                         :                         :
#                                         ⇣                         ⇣
#                                        pipe                     pipe

# or
$ curl -s -X GET https://domain.name/a/changes/${changeid}/detail |
       tail -n +2 |
      jq -r '( .labels."Code-Review".all[] | select ( .value == -2 ) ).username'
#            :                                                       :
#            ⇣                                                       ⇣
#        expression                                              expression

# or
$ curl -s -X GET https://domain.name/a/changes/${changeid}/detail |
       tail -n +2 |
      jq -r '[ .labels."Code-Review".all[] | select ( .value == -2 ) ][].username'
#            :                                                       :
#            ⇣                                                       ⇣
#        expression                                              expression

# or
$ curl -s -X GET https://domain.name/a/changes/${changeid}/detail |
       tail -n +2 |
       jq -r '.labels."Code-Review".all[] | select ( .value == -2 )' |
       jq -r .username                                            #  :
                                                                  #  ⇣
                                                                  # pipe

who approval the V+1

$ curl -s -X GET https://domain.name/a/changes/${changeid}/detail |
       tail -n +2 |
       jq -r .labels.Verified.approved.username

access list contains account

[!NOTE]

• list projects

• List Access Rights for Project

# i.e. : check all repos who contains account [e-mail]
$ while read -r _proj; do
    output=$( curl -fsSL https://gerrit.sample.com/a/projects/"${_proj}"/access |
              tail -n+2 |
              jq -r '.. | .rules? | select(. != null) | keys[] | ascii_downcase | select(contains("[e-mail]"))';
            )
    [[ -z "${output}" ]] || echo ">> https://gerrit.sample.com/admin/repos/$(sed 's:%2F:/:g' <<< "${_proj}")"
  done < <( curl -fsSL https://gerrit.sample.com/a/projects/?d |
                  tail -n+2 |
                  jq -r '.[].id' |
                  grep --color=never -E 'keyword-1|keyword-2'
          )

all reviews at a certain time

[!NOTE|label:references:]

• How to change the limit numbers of gerrit query

• Gerrit Code Review - Searching Changes

project='PROJECT'
branch='BRANCH'
start='2023-01-01'
end='2024-01-01'
curlOpt='--silent --insecure --globoff --netrc-file ~/.netrc'
query="project:${project}+branch:${branch}+after:${start}+before:${end}"
filter by status if necessary
query="${query}+is:closed+-is:abandoned"

echo ">> ${project} ~ ${branch}"
while IFS='|' read -r _change_id _id; do
  echo -e "\t- [${_id}] [_change_id]"
done < <( eval "curl ${curlOpt} 'https://gerrit.sample.com/a/changes/?q=${query}'" |
         tail -n +2 |
         jq -r '.[] | .change_id + "|" + .id'
 )

get review rate in certain time

gerritUrl='https://gerrit.sample.com'
sum=0
rnum=0
onum=0
echo ">> ${project} ~ ${branch}"
while IFS='|' read -r _change_id _id; do
  sum=$(( sum+1 ))
  output=$( eval "curl ${curlOpt} '${gerritUrl}/a/changes/${_id}/detail' | tail -n+2" )
  reviewed=$( jq -r '.labels."Code-Review".all[] | select(.value != null) | select( .value | contains(2) ) | .username' <<< "${output}" )
  owned=$( jq -r '.owner.username' <<< "${output}" )
  if grep 'marslo' <<< "${reviewed}" >/dev/null; then rnum=$(( rnum+1 )); fi
  if grep 'marslo' <<< "${owned}"    >/dev/null; then onum=$(( onum+1 )); fi
done < <( eval "curl ${curlOpt} '${gerritUrl}/a/changes/?q=${query}'" |
                tail -n +2 |
                jq -r '.[] | .change_id + "|" + .id'
        )
echo "${sum} ${rnum} ${onum} $(( sum-onum ))" |
      awk '{ sum=$1; reviewed=$2; owned=$3; rsum=$4; rate=$2*100/$4 } END { printf("\t- gerrit review: %s/(%s-%s) ( %s% )\n", reviewed, sum, owned, rate) }'

list all projects

$ curl -fsSL "${gerritUrl}"/a/projects/?d | tail -n+2 | jq -r '.[].id'

list gerrit projects with certain account

$ account='marslo'
$ id=1
$ gerritUrl='https://gerrit.sample.com'

$ while read -r _proj; do
    output=$( curl -fsSL "${gerritUrl}"/a/projects/"${_proj}"/access |
              tail -n+2 |
              jq -r --arg ACCOUNT "${account}" '.. | ."rules"? | select(. != null) | keys[] | ascii_downcase | select(contains($ACCOUNT))';
            )
    [[ -n "${output}" ]] && echo "[${id}] >> "${gerritUrl}"/admin/repos/$(sed 's:%2F:/:g' <<< "${_proj}")" && ((id++));
  done < <( curl -fsSL "${gerritUrl}"/a/projects/?d | tail -n+2 | jq -r '.[].id' )

list project configure

$ project='path/to/project'
$ curl -g -fsSL "https://${gerritUrl}/a/projects/$(printf %s "${project}" | jq -sRr @uri)/config" | tail -n+2 | jq -r

comments

get inline comments

[!NOTE|label:references:]

• get comment

APIs:

• 'GET /changes/{change-id}/comments'

• 'GET /changes/{change-id}/revisions/{revision-id}/comments'

• 'GET /changes/{change-id}/revisions/{revision-id}/comments/{comment-id}'

set review

[!NOTE|label:references:]

• set review

APIs:

• POST /changes/{change-id}/revisions/{revision-id}/review

{
  "tag": "jenkins",
  "message": "<OVERALL_MESSAGE>",
  "comments": {
    "<path/to/file>": [
      {
        "line": 7,
        "message": "<SINGLE_LINE_COMMENT>"
      },
      {
        "range": {
          "start_line": 9,
          "start_character": 0,
          "end_line": 11,
          "end_character": 20
        },
        "message": "<MULTI_LINE_COMMENT>"
      }
    ]
  }
}

$ CHAGE_ID=I82aca7c1979b930b5a2b902166ccd7d82442e2ef
$ REVISION_NUMBER=465dde65d2376f9f5f84a011473578b12d5a0350
$ curl -XPOST \
       -H "Content-Type: application/json" \
       --data-binary @gerrit-review.json \
       https://gerrit.domain.com/a/changes/${CHAGE_ID}/revisions/${REVISION_NUMBER}/review

reference

[!NOTE|lbael:references:]

• project owner guide

• Gerrit Code Review - Access Controls

• Gerrit Code Review - Uploading Changes

• The refs/for namespace

• gerrit/gerrit/refs/meta/config

• gerrit 权限控制

• its-jira plugin md

• Rule base configuration

• Gerrit push not working. Remote rejected, prohibited by gerrit

• Gerrit Code Review - Project Configuration File Format

• Review UI