Synchronize Jenkins Teams with your GitHub Collaborators

The new user experience for CloudBees Jenkins Enterprise is focused on helping teams become productive so that they can ship faster. Many of you have asked for a way to quickly pull in members of your teams that already exist in GitHub. We’re excited to introduce our new Command Line Interface for that purpose (CLI).

These new CLI commands have been created to help you manage teams, team members and their corresponding roles and permissions. In this post we are going to show you how easy it is to sync teams from one GitHub repository with members of a CloudBees Jenkins Enterprise team using CLI commands.

We assume the CloudBees Jenkins Enterprise team has already been created directly from the UI as described in the documentation (it could be done using the CLI also, but that’s a matter for another blog post).

In this setup, a CloudBees Jenkins Enterprise team maps to a set of members that work on a subset of repositories under an SCM team or organization (a GitHub organization for the purpose of this post). Here, we are going to map collaborators from a single repository – for simplicity – and to focus on the new CLI command, rather than emphasize on more complex requests and parsing of GitHub API responses.

The example could be extended to use GitHub organization members and check the permissions they have on a pre-defined subset of repositories (for example, “If the GitHub 0rganization members has push permissions on A, B and C, then it is a team member”). All said, the following script maps collaborators from a GitHub repository to CloudBees Jenkins Enterprise team members.

Here is how we have mapped GitHub teams:

  • GitHub admin → CloudBees Jenkins Enterprise team admin
  • GitHub push → CloudBees Jenkins Enterprise team member
  • GitHub pull → CloudBees Jenkins Enterprise team guest

NOTE: the script uses jq, a JSON filter that takes an input and returns an output after applying some filters and transformations.

#!/bin/bash
# CJOC base URL
CJOC_URL=https://example.com/cjoc
# GitHub repository to map members from
GH_REPO=cloudbees/one-repo
# CJE Team to set members on
CJE_TEAM=a-team
# GitHub user
GH_USER=amuniz
# GitHub Personal Access Token to use for API requests
GH_PAT=xxxxx
# CJE user to be used in CLI calls
CJE_USER=simon
# CJE user access token
CJE_ACCESS_TOKEN=xxxxx
# re-download the CLI client due to possible version changes
if [ -f jenkins-cli.jar ]; then
  rm jenkins-cli.jar
fi
wget $CJOC_URL/jnlpJars/jenkins-cli.jar
# Get GH collaborators and map them to CJE Team members
curl -u "$GH_USER:$GH_PAT" https://api.github.com/repos/$GH_REPO/collaborators \
  | jq '[.[] | { id: .login, roles:[if .permissions.admin then "TEAM_ADMIN" elif .permissions.push then "TEAM_MEMBER" elif .permissions.pull then "TEAM_GUEST" else "ERROR" end]}]' | jq '{version: "1", data: .}' \
  | java -jar jenkins-cli.jar -noKeyAuth -auth $CJE_USER:$CJE_ACCESS_TOKEN -s $CJOC_URL/ team-members $CJE_TEAM --put

The script is transforming the incoming JSON from the GitHub response to a Team Members JSON, which will be like:

{
    "version": "1",
    "data": [{
        "id": "bob",
        "roles": ["TEAM_GUEST"]
    }, {
        "id": "john",
        "roles": ["TEAM_MEMBER"]
    }, {
        "id": "simon",
        "roles": ["TEAM_ADMIN"]
    }]
}

Some notes on the CLI Command used:

  • It is the team-members endpoint (there are others, like teams, team-roles or team-permissions).
  • It is using the —put option, which takes a full JSON file defining the whole set of team members.
  • It is using basic authentication, it could use SSH key based authentication as noted in the docs.

More will be coming about CloudBees Jenkins Enterprise teams CLI commands in this blog soon!