Jenkins

1. Overview

Jenkins is a leading open-source automation server that helps automate the parts of software development related to building, testing, and deploying, facilitating continuous integration and continuous delivery (CI/CD). It provides a vast ecosystem of plugins to support building, deploying, and automating any project.

The GoInsight Jenkins node allows you to integrate your CI/CD pipelines directly into your automation workflows. You can manage the core components of your Jenkins instance, from jobs and builds to server-level operations. This includes:

• Job Lifecycle Management: Create, delete, copy, and trigger Jenkins jobs programmatically.
• Build Information Retrieval: Fetch detailed information about specific builds or a list of recent builds for any job.
• Instance Control: Perform administrative tasks such as restarting, shutting down, or managing the "quiet down" mode of your Jenkins server.

2. Prerequisites

Before using this node, you will need to have:

• A running Jenkins instance that is accessible from the GoInsight platform.
• A user account on the Jenkins instance with the necessary permissions to perform the desired actions (e.g., create/delete jobs, trigger builds).
• An API token generated for your Jenkins user account.

3. Credentials

For a detailed guide on how to obtain and configure your credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on resources such as Job, Build, and System.

Operation Details

Create a Job

Create a Jenkins job and return its configuration summary. Key points: JobName must be unique in the target Jenkins instance. AdditionalFields.parameters supports string, boolean, choice, text, and password types. On success, Job includes Name, Location, and the main flags written to the generated config XML.

Input Parameters:

• JobName: Name of the new Jenkins job. Format: Must be unique in the target Jenkins instance, case-sensitive, avoid leading or trailing spaces. Example: backend-api-build

Options:

• Description: Optional job description shown in the Jenkins UI. Example: Builds and deploys the backend API service.
• ScmClass: SCM implementation class used in the generated Jenkins job config. Common values: hudson.scm.NullSCM (default), hudson.plugins.git.GitSCM, hudson.scm.SubversionSCM.
• Disabled: Whether the new job is created in disabled mode. true: created disabled, false: available immediately.
• ConcurrentBuilds: Whether Jenkins allows multiple builds of this job to run at the same time.
• AdditionalFields: Optional advanced configuration as an object. Common fields include canRoam, keepDependencies, blockBuildWhenDownstreamBuilding, blockBuildWhenUpstreamBuilding, and parameters.

Output:

• Job (object): Business data object summarizing the created Jenkins job. Returns empty object {} if creation failed.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors, False for parameter/auth errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error details if any, empty string otherwise.

Delete a Job

Permanently delete a job and all its build history from Jenkins. Key points: Job name is case-sensitive and supports folder paths (e.g., 'folder/job-name'). Use Get Many Jobs to look up the exact job name before deleting. Requires admin or job-delete permissions on the Jenkins instance.

Input Parameters:

• JobName: Name of the job to delete. Job name is case-sensitive and supports folder paths. Example: 'production-deploy-job'

Output:

• DeletedJob (object): Business data object confirming the deletion. Structure: {"deleted": bool, "name": string}. Returns empty object {} if operation failed.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors, False for parameter/auth errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error details if any, empty string otherwise.

Get Many Jobs

Retrieve a paginated list of jobs from a Jenkins instance. Key points: Jenkins API does not support server-side pagination; all jobs are fetched then sliced locally by Limit/Offset. Jobs.jobs contains the paginated slice; Jobs.total is the full count across all jobs. Each job entry includes: name, url, color (build status), buildable, description.

Options:

• Limit: Maximum number of jobs to return. Minimum 1. Example: 50
• Offset: Number of jobs to skip for pagination. Minimum 0. Example: 0

Output:

• Jobs (object): Business data object containing the jobs list and metadata. Structure: {"jobs": [{"name": string, "url": string, "color": string, "buildable": bool}, ...], "total": number, "offset": number, "limit": number}. Returns empty object {} if operation failed.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors, False for parameter/auth errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error details if any, empty string otherwise.

Copy a Job

Create a new Jenkins job by copying an existing job's configuration. Key points: Inherits build steps, parameters, triggers, and permissions from the source job. Build history and workspace are NOT copied; new job is disabled by default. Job names are case-sensitive and support folder paths.

Input Parameters:

• SourceJobName: Name of the existing job to copy. Supports folder paths. Job name is case-sensitive. Example: 'production-deploy-job' or 'CI/backend-build'
• NewJobName: Name of the new job to create. Must not already exist in Jenkins. Supports folder paths. Example: 'staging-deploy-job' or 'CI/backend-build-staging'

Output:

• Job (object): Business data object containing the copied job details. Structure: {"name": string, "url": string, "copied": bool}. Returns empty object {} if operation failed.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors, False for parameter/auth errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error details if any, empty string otherwise.

Trigger a Job

Trigger a Jenkins job and return details when Jenkins accepts the request. Key points: JobName is case-sensitive and supports folder paths like folder/subfolder/job-name. Trigger.queueUrl may be empty if Jenkins omits the Location header. Use Trigger a Job with Parameters when the job requires build parameters.

Input Parameters:

• JobName: Name of the Jenkins job to trigger. Format: Root folder job (use name directly), Nested job (use folder/subfolder/job-name). Job names are case-sensitive. Example: production/deploy-service

Output:

• Trigger (object): Business data object for the accepted Jenkins trigger request. Structure: {"accepted": bool, "jobName": string, "queueUrl": string, "endpoint": string}. Returns empty object {} if operation failed.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors, False for parameter/auth errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error details if any, empty string otherwise.

Trigger a Job with Parameters

Trigger a parameterized Jenkins job and return queue details. Key points: JobName is case-sensitive and supports folder paths like folder/subfolder/job-name. Parameters must be a non-empty object whose keys match Jenkins job parameter names. Use Trigger a Job instead when the target job does not need parameters.

Input Parameters:

• JobName: Name of the Jenkins job to trigger. Format: Root folder job (use name directly), Nested job (use folder/subfolder/job-name). Job names are case-sensitive. Example: production/deploy-service
• Parameters: Non-empty object of Jenkins build parameters. Each key must exactly match a parameter name configured in the target Jenkins job. Example: {"environment": "production", "deploy": true, "version": "1.2.3"}

Output:

• Trigger (object): Business data object for the accepted Jenkins trigger request. Structure: {"accepted": bool, "jobName": string, "queueUrl": string, "endpoint": string, "submittedParameters": object}. Returns empty object {} if operation failed.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors, False for parameter/auth errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error details if any, empty string otherwise.

Get Many Builds

Fetches Jenkins build history for one job or all jobs (Limit is per job). Key points: JobName empty: each job contributes up to Limit builds; Builds.total is how many this call returned, not global. See Builds.pagination for limits; has_more is always false.

Options:

• JobName: Job name to fetch builds for. Leave empty to scan all jobs (up to Limit builds per job). Example: CI/backend-api
• Limit: Max builds per job (integer >= 1). Behavior: JobName set: at most Limit builds for that job. JobName empty: lists jobs then takes up to Limit builds from each job.

Output:

• Builds (object): Wrapper: builds (array) of records; total (int) = len(builds) for this response only; pagination (object) with limit_per_job, jobs_scanned, has_more, note.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors, False for parameter/auth errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error details if any, empty string otherwise.

Enable Quiet Down

Put Jenkins into quiet down mode to stop accepting new builds. Key points: Existing builds continue; only new builds are blocked. No business inputs; credentials are injected from the selected credential. The action handles the Jenkins CSRF token and sets QuietDown.quietingDown=true on success.

Output:

• QuietDown (object): Business data object confirming the quiet down operation. Structure: {"quietingDown": boolean}. When quietingDown=true, Jenkins is now blocking new builds. Returns empty object {} if operation failed.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors, False for parameter/auth errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error details if any, empty string otherwise.

Cancel Quiet Down

Cancel Jenkins quiet down mode so Jenkins accepts new builds again. Key points: No business inputs; credentials are injected from the selected credential. The action handles the Jenkins CSRF token and calls /cancelQuietDown. JenkinsState.status_code is 200 or 302 on success.

Output:

• JenkinsState (object): Business data object containing cancel quiet down operation details. Returns stable confirmation fields when successful, empty object {} otherwise.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors, False for parameter/auth errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error details if any, empty string otherwise.

Restart

Restart the Jenkins controller in safe or immediate mode, with optional completion verification. Key points: SafeRestart=true uses /safeRestart and waits for running builds to finish. SafeRestart=false uses /restart and may interrupt running builds. VerifyCompletion=false returns after Jenkins accepts the request. VerifyCompletion=true waits for Jenkins to enter a restart/unavailable state and recover to healthy.

Options:

• SafeRestart: Restart mode. true (default, recommended): POST /safeRestart; Jenkins finishes running builds first. false: POST /restart; immediate restart and running builds are aborted. Use false only in emergencies.
• VerifyCompletion: Whether to wait and verify that Jenkins actually restarts. false (default): return after the restart request is accepted. true: wait for Jenkins to enter a restart/unavailable state and then recover to healthy state.
• WaitTimeoutSeconds: Maximum seconds to wait for restart verification when VerifyCompletion is true. Default 180.
• PollIntervalSeconds: Polling interval in seconds for restart verification when VerifyCompletion is true. Default 5.

Output:

• Restart (object): Outcome object. Keys: requestAccepted (bool), safe_restart (bool), endpoint (string), verificationRequested (bool), verificationStatus (string: not_requested/passed/failed), observedTransition (bool), finalState (string), probeStatusCode (number), stateDetail (string).
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors, False for parameter/auth errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error details if any, empty string otherwise.

Shutdown

Shut down the Jenkins controller in safe or immediate mode, with optional completion verification. Key points: SafeShutdown=true uses /safeExit and blocks new builds while waiting for running builds to finish. SafeShutdown=false uses /exit and may terminate running builds. VerifyCompletion=false returns after Jenkins accepts the request. VerifyCompletion=true waits until Jenkins becomes unavailable.

Options:

• SafeShutdown: Shutdown mode: True (Recommended): Jenkins will wait for all running builds to finish before shutting down. False (Immediate): Jenkins will shut down immediately, terminating all running builds.
• VerifyCompletion: Whether to wait and verify that Jenkins becomes unavailable. false (default): return after the shutdown request is accepted. true: wait until Jenkins becomes unavailable.
• WaitTimeoutSeconds: Maximum seconds to wait for shutdown verification when VerifyCompletion is true. Default 60.
• PollIntervalSeconds: Polling interval in seconds for shutdown verification when VerifyCompletion is true. Default 5.

Output:

• Shutdown (object): Outcome object. Keys: requestAccepted (bool), shutdownRequested (bool), mode (string), endpoint (string), verificationRequested (bool), verificationStatus (string: not_requested/passed/failed), finalState (string), probeStatusCode (number), stateDetail (string).
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors, False for parameter/auth errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error details if any, empty string otherwise.

5. Example Usage

This section walks through a simple workflow that creates a new Jenkins job using the Create a Job operation.

The workflow consists of three nodes: Start -> Jenkins: Create a Job -> Answer.

1. Add the Jenkins Node

• In the workflow canvas, click the + icon to add a new node.
• In the panel that appears, select the Tools tab.
• Find and select Jenkins from the list of tools.
• In the list of supported operations, click Create a Job to add the node to your canvas.

2. Configure the Node

• Click the Create a Job node to open its configuration panel.
• Credentials: Select the Jenkins credential you have already configured.
• Input Parameters:
  • JobName: Enter a unique job name, for example my-automated-test-job.
• Options (optional):
  • Description: A short label shown in the Jenkins UI, for example Automated test job created from GoInsight.
  • ScmClass: Leave the default hudson.scm.NullSCM unless you need Git or Subversion integration.
  • Disabled: Set to false if the job should be triggerable immediately after creation.
  • AdditionalFields: Use this object for advanced settings such as build parameters. Example: {"parameters": [{"name": "environment", "type": "string", "default": "test", "description": "Deployment environment"}]}.

3. Run and Validate

• After required fields are filled, error indicators on the canvas should clear.
• Click Run in the top-right corner to execute the workflow.
• Open the execution logs to inspect the node output. On success, the Job object includes fields such as Name, Created, and Location.
• Confirm the new job appears in your Jenkins UI.

When the workflow completes successfully, Jenkins creates a job using the generated configuration XML based on your inputs.

6. FAQs

Q: How do I add build parameters when creating a job?

A: Use the AdditionalFields option on Create a Job. Pass a JSON object with a parameters array. Each item needs at least name and type (string, boolean, choice, text, or password). For choice parameters, include a choices array. Example: {"parameters": [{"name": "BRANCH", "type": "string", "default": "main", "description": "Git branch to build"}]}.

Q: I'm receiving a 401 Unauthorized or 403 Forbidden error. What should I do?

A: These errors typically indicate an issue with authentication or permissions. Please check the following:

• API Token: Ensure the API token used in your GoInsight credential is correct and has not expired or been revoked.
• User Permissions: Verify that the Jenkins user associated with the API token has the necessary permissions to perform the action (e.g., Job > Create, Job > Delete).
• Credential Configuration: Double-check that you have selected the correct Jenkins credential in the node's configuration panel.

Q: How can I trigger a parameterized job?

A: Use the Trigger a Job with Parameters action. The Parameters input must be a non-empty JSON object whose keys match the parameter names configured on the target Jenkins job. Example: {"BRANCH": "develop", "RUN_TESTS": true}.

7. Official Documentation

For more in-depth information about the Jenkins API and its capabilities, please refer to the Jenkins Official API Documentation.