Home

Awesome

Jenkins API Client for Go

GoDoc Go Report Cart Build Status

About

Jenkins is the most popular Open Source Continuous Integration system. This Library will help you interact with Jenkins in a more developer-friendly way.

These are some of the features that are currently implemented:

Installation

go get github.com/bndr/gojenkins

CLI

For users that would like CLI based on gojenkins, follow the steps below:

$ cd cli/jenkinsctl
$ make

Usage


import (
  "github.com/bndr/gojenkins"
  "context"
  "time"
  "fmt"
)

ctx := context.Background()
jenkins := gojenkins.CreateJenkins(nil, "http://localhost:8080/", "admin", "admin")
// Provide CA certificate if server is using self-signed certificate
// caCert, _ := ioutil.ReadFile("/tmp/ca.crt")
// jenkins.Requester.CACert = caCert
_, err := jenkins.Init(ctx)


if err != nil {
  panic("Something Went Wrong")
}

job, err := jenkins.GetJob(ctx, "#jobname")
if err != nil {
  panic(err)
}
queueid, err := job.InvokeSimple(ctx, params) // or  jenkins.BuildJob(ctx, "#jobname", params)
if err != nil {
  panic(err)
}
build, err := jenkins.GetBuildFromQueueID(ctx, job, queueid)
if err != nil {
  panic(err)
}

// Wait for build to finish
for build.IsRunning(ctx) {
  time.Sleep(5000 * time.Millisecond)
  build.Poll(ctx)
}

fmt.Printf("build number %d with result: %v\n", build.GetBuildNumber(), build.GetResult())

API Reference: https://godoc.org/github.com/bndr/gojenkins

Examples

For all of the examples below first create a jenkins object

import "github.com/bndr/gojenkins"

jenkins, _ := gojenkins.CreateJenkins(nil, "http://localhost:8080/", "admin", "admin").Init(ctx)

or if you don't need authentication:

jenkins, _ := gojenkins.CreateJenkins(nil, "http://localhost:8080/").Init(ctx)

you can also specify your own http.Client (for instance, providing your own SSL configurations):

client := &http.Client{ ... }
jenkins, := gojenkins.CreateJenkins(client, "http://localhost:8080/").Init(ctx)

By default, gojenkins will use the http.DefaultClient if none is passed into the CreateJenkins() function.

Check Status of all nodes

nodes := jenkins.GetAllNodes(ctx)

for _, node := range nodes {

  // Fetch Node Data
  node.Poll(ctx)
	if node.IsOnline(ctx) {
		fmt.Println("Node is Online")
	}
}

Get all Builds for specific Job, and check their status

jobName := "someJob"
builds, err := jenkins.GetAllBuildIds(ctx, jobName)

if err != nil {
  panic(err)
}

for _, build := range builds {
  buildId := build.Number
  data, err := jenkins.GetBuild(ctx, jobName, buildId)

  if err != nil {
    panic(err)
  }

	if "SUCCESS" == data.GetResult(ctx) {
		fmt.Println("This build succeeded")
	}
}

// Get Last Successful/Failed/Stable Build for a Job
job, err := jenkins.GetJob(ctx, "someJob")

if err != nil {
  panic(err)
}

job.GetLastSuccessfulBuild(ctx)
job.GetLastStableBuild(ctx)

Get Current Tasks in Queue, and the reason why they're in the queue


tasks := jenkins.GetQueue(ctx)

for _, task := range tasks {
	fmt.Println(task.GetWhy(ctx))
}

Create View and add Jobs to it


view, err := jenkins.CreateView(ctx, "test_view", gojenkins.LIST_VIEW)

if err != nil {
  panic(err)
}

status, err := view.AddJob(ctx, "jobName")

if status != nil {
  fmt.Println("Job has been added to view")
}

Create nested Folders and create Jobs in them


// Create parent folder
pFolder, err := jenkins.CreateFolder(ctx, "parentFolder")
if err != nil {
  panic(err)
}

// Create child folder in parent folder
cFolder, err := jenkins.CreateFolder(ctx, "childFolder", pFolder.GetName())
if err != nil {
  panic(err)
}

// Create job in child folder
configString := `<?xml version='1.0' encoding='UTF-8'?>
<project>
  <actions/>
  <description></description>
  <keepDependencies>false</keepDependencies>
  <properties/>
  <scm class="hudson.scm.NullSCM"/>
  <canRoam>true</canRoam>
  <disabled>false</disabled>
  <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>
  <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>
  <triggers class="vector"/>
  <concurrentBuild>false</concurrentBuild>
  <builders/>
  <publishers/>
  <buildWrappers/>
</project>`

job, err := jenkins.CreateJobInFolder(ctx, configString, "jobInFolder", pFolder.GetName(), cFolder.GetName())
if err != nil {
  panic(err)
}

if job != nil {
	fmt.Println("Job has been created in child folder")
}

Get All Artifacts for a Build and Save them to a folder


job, _ := jenkins.GetJob(ctx, "job")
build, _ := job.GetBuild(ctx, 1)
artifacts := build.GetArtifacts(ctx)

for _, a := range artifacts {
	a.SaveToDir("/tmp")
}

To always get fresh data use the .Poll() method


job, _ := jenkins.GetJob(ctx, "job")
job.Poll()

build, _ := job.getBuild(ctx, 1)
build.Poll()

Create and Delete Users

// Create user
user, err := jenkins.CreateUser(ctx, "username", "password", "fullname", "user@email.com")
if err != nil {
  log.Fatal(err)
}
// Delete User
err = user.Delete()
if err != nil {
  log.Fatal(err)
}
// Delete user not created by gojenkins
err = jenkins.DeleteUser("username")

Create and Revoke API Tokens

// Create a token for admin user
token, err := jenkins.GenerateAPIToken(ctx, "TestToken")
if err != nil {
  log.Fatal(err)
}

// Set Jenkins client to use new API token
jenkins.Requester.BasicAuth.Password = token.Value

// Revoke token that was just created
token.Revoke()

// Revoke all tokens for admin user
err = jenkins.RevokeAllAPITokens(ctx)
if err != nil {
  log.Fatal(err)
}

Testing

go test

Contribute

All Contributions are welcome. The todo list is on the bottom of this README. Feel free to send a pull request.

TODO

Although the basic features are implemented there are many optional features that are on the todo list.

LICENSE

Apache License 2.0