yo-jenkins

yo-jenkins is a cross-platform command line interface (CLI) tool to monitor, manage, and have fun with a Jenkins server. It makes it possible to interact with Jenkins server without using the browser based Jenkins UI.

This tool is able to be integrated into a script as middleware in order to automate Jenkins related tasks and enable Jenkins configuration as code.

yo-jenkins will liberate you and your browser from the Jenkins Web UI

With yo-jenkins you can manage:

• Authentication: Authentication structure similar to AWS CLI
• Server: Create, shutdown, view queue, and more
• User accounts: Create, delete, add/remove permission, and more
• Nodes/agents: Create, delete, shut down server, and more
• Credentials: Create, update, delete, list, and more
• Folders: Create items, delete items, disable, enable, and more
• Jobs: Create, delete, trigger, monitor, search, and more
• Builds: Monitor, abort, tail logs, follow logs, and more
• Stages: Get info, get logs, view steps, view status
• Steps: Get info
• Other tools and functions: Run groovy scripts remotely, run custom REST calls, setup a shared library, view command usage history, and more

NOTE: This project is in pre-alpha release phase. Please report any issues, odd behavior, or suggestions. Read more about the release cycle. See Bug Reports and Feature Requests

Overview

• Overview
• Quick Start
• Installation
• Usage
• Jenkins Plugin Requirements
• Local Jenkins Server Setup Using Docker
• Bug Reports
• Feature Requests
• Contributing
  • Contributors
• Licence

Quick Start

• (Optional) Start up a local Jenkins server using Docker

  • yo-jenkins server server-deploy

• Configure your first profile. Profiles are stored in the home directory in the .yo-jenkins directory

  • yo-jenkins auth configure

• Generate a Jenkins server API token and add it to your first profile

  • yo-jenkins auth token --profile <PROFILE NAME>

• Verify that you can access the Jenkins server

  • yo-jenkins auth verify

• Now start trying some things

  • Get sever info:       yo-jenkins server info
    Get your user info:   yo-jenkins auth user --pretty
    Search a job:         yo-jenkins job search some-job-name --fullname --yaml --list
    Monitor a build:      yo-jenkins build monitor some-job-name --latest --sound

Installation

1. Install system dependencies for simpleaudio sound Python package for job and build monitor

   • Platform	Command
     MacOS and Windows	Not needed
     Ubuntu	sudo apt update && apt-get install -y python3-dev python3-pip libasound2-dev
     CentOS	sudo yum update && yum install -y python3-devel gcc alsa-lib-devel

2. Install yo-jenkins

   • Option 1 (Recommended): Install from Python Package Index (PYPI) using pip

     • pip install yo-jenkins

   • Option 2: Download all files from this GitHub repository and install using the included setup.py

     •   python setup.py install

Usage

Each top level command has sub-commands. For example, yo-jenkins server has sub-commands server-deploy and server-start. To see the sub-commands of a command, or to see the options of a command, use the --help option.

                        YO-JENKINS (Version: 0.0.0) 

  yo-jenkins is a tool that is focused on interfacing with Jenkins server from
  the comfort of the beloved command line.  This tool can also be used as a
  middleware utility, generating and passing Jenkins information or automating
  tasks.

  QUICK START:

    1. Configure yo profile:  yo-jenkins auth configure
    2. Add yo API token:      yo-jenkins auth token --profile <PROFILE NAME>
    3. Verify yo creds:       yo-jenkins auth verify
    4. Explore yo-jenkins

Options:
  -v, --version  Show the version
  --help         Show this message and exit.

Commands:
  account     Manage user accounts
  auth        Manage authentication and profiles
  build       Manage builds
  credential  Manage credentials
  folder      Manage folders
  job         Manage jobs
  node        Manage nodes
  server      Manage server
  stage       Manage build stages
  step        Manage stage steps
  tools       Tools and more

Jenkins Plugin Requirements

If you are using yo-jenkins on a pre-existing Jenkins server, make sure that the following Jenkins plugin are installed for yo-jenkins to use all its functionalities. However, these plugins tend to be installed by default.

In order to check/install a plugin, go to Manage Jenkins > Manage Plugins > Installed OR Available

1. Folders (cloudbees-folder)
2. Next Build Number (next-build-number)
3. Promoted Builds (promoted-builds)
4. Role-based Authorization Strategy (role-strategy)
5. GitHub Branch Source Plugin (github-branch-source)

Local Jenkins Server Setup Using Docker

yo-jenkins offers an easy way to quickly set up a local Jenkins server within a Docker container. This server is setup and ready to go to tinker with yo-jenkins.

NOTE: You must have Docker installed and running. See Docker installation guide.

Run the following command to set up a local Jenkins server:

yo-jenkins server server-deploy

Use --help for available options, and use --debug to troubleshoot any issues.

Bug Reports

As with any other software, issues do come up during various usage scenarios that may not be accounted for during development and testing. Help from real users is enormously helpful.

Please report and bugs and odd behaviors with either of these:

• Online at GitHub Issues
• yo-jenkins tools bug-report

If possible, please include the command that caused the issue, running it with the --debug option. For example, yo-jenkins server server-deploy --debug

Note, that your issue may already be in queue, so please check the project FIXME.

Feature Requests

This is a very young project, and we are always looking for new features and improvements. Please feel free to open an issue and suggest a feature. Please be as specific as possible, and include as much information as possible.

• Online at GitHub Feature Request
• yo-jenkins tools feature-request

Note, your suggestion may be part of the Project plan, so be sure to check the TODO to see if it is already planned.

Contributing

This project is an on-going effort, slowly adding various features and improvements. If you would like to contribute, please fork the project, make your changes, and submit a pull request.

Any help, ideas, or user testing is much appreciated!

There is definitely work to be done. If you don't happen to have a great genius idea for the next big change, or if you spot an issue you are able to fix, please checkout the TODO and FIXME or add your own ideas. For guides and information on how to get started and help out, check out the dev_things directory.

Contributors

• Ismet Handžić: GitHub: @ismet55555

Licence

This project is licensed under the GNU General Public License Version 3 License. Please see the LICENSE file for details. Also a complete history of this licence.