Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bndr/gojenkins
Jenkins API Client in Go. Looking for maintainers to move this project forward.
https://github.com/bndr/gojenkins
api continuous-integration go godoc jenkins
Last synced: 3 days ago
JSON representation
Jenkins API Client in Go. Looking for maintainers to move this project forward.
- Host: GitHub
- URL: https://github.com/bndr/gojenkins
- Owner: bndr
- License: apache-2.0
- Created: 2014-09-27T18:03:32.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2024-07-26T09:10:49.000Z (5 months ago)
- Last Synced: 2024-12-03T15:08:32.830Z (10 days ago)
- Topics: api, continuous-integration, go, godoc, jenkins
- Language: Go
- Homepage:
- Size: 363 KB
- Stars: 874
- Watchers: 19
- Forks: 447
- Open Issues: 145
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-golang-repositories - gojenkins
README
# Jenkins API Client for Go
[](https://godoc.org/github.com/bndr/gojenkins)
[](https://goreportcard.com/report/github.com/bndr/gojenkins)
[](https://travis-ci.org/bndr/gojenkins)
## 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:
* Get information on test-results of completed/failed build
* Ability to query Nodes, and manipulate them. Start, Stop, set Offline.
* Ability to query Jobs, and manipulate them.
* Get Plugins, Builds, Artifacts, Fingerprints
* Validate Fingerprints of Artifacts
* Create and Delete Users
* Get Current Queue, Cancel Tasks
* Create and Revoke API Tokens
* etc. For all methods go to GoDoc Reference.
## 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
```go
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
```go
import "github.com/bndr/gojenkins"
jenkins, _ := gojenkins.CreateJenkins(nil, "http://localhost:8080/", "admin", "admin").Init(ctx)
```
or if you don't need authentication:
```go
jenkins, _ := gojenkins.CreateJenkins(nil, "http://localhost:8080/").Init(ctx)
```
you can also specify your own `http.Client` (for instance, providing your own SSL configurations):
```go
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
```go
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
```go
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
```go
tasks := jenkins.GetQueue(ctx)
for _, task := range tasks {
fmt.Println(task.GetWhy(ctx))
}
```
### Create View and add Jobs to it
```go
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
```go
// 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 := `
false
true
false
false
false
false
`
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
```go
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
```go
job, _ := jenkins.GetJob(ctx, "job")
job.Poll()
build, _ := job.getBuild(ctx, 1)
build.Poll()
```
### Create and Delete Users
```go
// Create user
user, err := jenkins.CreateUser(ctx, "username", "password", "fullname", "[email protected]")
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
```go
// 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.
* Kerberos Authentication
* Rewrite some (all?) iterators with channels
## LICENSE
Apache License 2.0