Skip to main content

Jenkins

Jenkins is an open-source automation server that enables developers to build, test, and deploy software through continuous integration and continuous delivery (CI/CD) pipelines.

Authentication Types​

Jenkins supports 1 authentication method:

  • API Token - Use a personal API token for authentication. Each user connects with their own Jenkins account credentials.
    • Pros: Secure, works with all authentication realms (LDAP, SSO, etc.), no CSRF token needed, per-user tracking
    • Cons: Requires Jenkins 2.96+ for optimal experience, requires manual token generation per user

General Settings​

Before using the connector, you need to configure:

  • Jenkins Instance URL - Your Jenkins server URL (e.g., https://jenkins.company.com or https://ci.mycompany.io)
tip

Make sure to include the protocol (https:// or http://) in your instance URL. Do not include a trailing slash.

Setting up API Token​

1. Generate an API Token in Jenkins​

  1. Log in to your Jenkins instance with your credentials

  2. Click on your username in the top right corner

  3. Click Configure in the left sidebar (or navigate to https://your-jenkins-instance/me/configure)

  4. Scroll down to the API Token section

  5. Click Add new Token

  6. Enter a descriptive name for the token (e.g., "Webrix Integration" or "AI Assistant Access")

  7. Click Generate

  8. Copy the token immediately - it will only be shown once

warning

The API token is only displayed once. If you lose it, you'll need to revoke it and generate a new one.

2. Prepare Your Credentials​

Jenkins API authentication requires HTTP Basic Auth with your username and API token. You need to format your credentials as:

username:apiToken

For example, if your username is john.doe and your API token is abc123def456, your credential string should be:

john.doe:abc123def456

3. Configure in Webrix​

  1. In Webrix, navigate to Integrations → New → Built-in

  2. Select Jenkins

  3. In General Settings, enter your Jenkins Instance URL

  4. In Authentication, paste your credentials in the format username:apiToken

  5. Click Save Changes

  6. Click Connect to verify the connection

tip

Your username is your Jenkins login username, not your display name or email address. You can find it in your Jenkins profile.

Troubleshooting​

403 Forbidden Error​

Cause: Invalid credentials, incorrect username, or expired/revoked API token.

Solution:

  1. Verify that you're using your Jenkins username (not email or display name)
  2. Ensure the API token is correct and hasn't been revoked
  3. Generate a new API token and try again
  4. Check that your Jenkins account has appropriate permissions

Invalid Instance URL​

Cause: The Jenkins instance URL is malformed or unreachable.

Solution:

  1. Ensure the URL includes the protocol (https:// or http://)
  2. Remove any trailing slashes from the URL
  3. Verify you can access the Jenkins web interface at that URL
  4. Check that the Jenkins server is accessible from Webrix (not blocked by firewall)

Job Not Found Error​

Cause: The job name is incorrect, especially for nested jobs in folders.

Solution:

For jobs nested in folders, use forward slashes to separate folder names:

folder-name/subfolder-name/job-name

For example:

  • Correct: production/backend/deploy-api
  • Incorrect: production-backend-deploy-api

You can verify the correct path by checking the job's URL in Jenkins - the path segments after /job/ are what you need.

Permission Denied Error​

Cause: Your Jenkins user account lacks necessary permissions for the requested operation.

Solution:

Ensure your Jenkins user has the appropriate permissions:

  • Read - View jobs, builds, and configuration
  • Build - Trigger builds
  • Configure - Modify job configuration
  • Delete - Delete jobs
  • Cancel - Stop running builds

Contact your Jenkins administrator to grant the necessary permissions. Jenkins uses role-based access control (RBAC) which can be configured through matrix-based security or role plugins.

Pipeline API Tools Not Working​

Cause: The Pipeline REST API plugin is not installed.

Solution:

The pipeline-specific tools (Get Pipeline Runs, Get Pipeline Run Details, etc.) require the Pipeline: REST API plugin. Ask your Jenkins administrator to install it from:

Manage Jenkins → Manage Plugins → Available Plugins → Search for "Pipeline REST API"

Alternatively, you can use the standard build tools which work for all job types including pipelines.

Security Considerations​

caution

API tokens have the same permissions as your user account. Store tokens securely and rotate them periodically.

Best Practices:

  1. Generate separate tokens for different integrations or applications
  2. Use descriptive names when generating tokens to track their usage
  3. Revoke unused tokens regularly through your Jenkins profile
  4. Never share tokens - each user should generate their own
  5. Use minimal permissions - request your Jenkins admin to grant only necessary permissions to your account
  6. Rotate tokens periodically as part of your security policy

Common Use Cases​

Monitoring Build Status​

Use "Get Build Status" to check if a build succeeded or failed, and "Get Console Output" to view logs when debugging failures.

Triggering Deployments​

Use "Trigger Parameterized Build" to start deployment jobs with specific parameters like environment, version, or branch.

Managing Build Queue​

Use "Get Build Queue" to see what's waiting to build, and "Cancel Queued Item" to remove builds that are no longer needed.

Debugging Pipelines​

For pipeline jobs, use "Get Pipeline Run Details" to see the status of each stage, and "Get Pipeline Node Log" to view stage-specific logs.

Checking Build Capacity​

Use "List Nodes" to see all available build agents and their executor counts, helping identify capacity issues.

Additional Resources​