community.general.jenkins_credential module – Manage Jenkins credentials and domains through API

Note

This module is part of the community.general collection (version 12.6.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.general.jenkins_credential.

New in community.general 11.1.0

Synopsis
Requirements
Parameters
Attributes
Examples
Return Values

Synopsis

This module allows managing Jenkins credentials and domain scopes through the Jenkins HTTP API.
Create, update, and delete different credential types such as username/password, secret text, SSH key, certificates, GitHub App, and domains.
For scoped domains (type=scope), it supports restrictions based on hostname, hostname:port, path, and scheme.

Requirements

The below requirements are needed on the host that executes this module.

urllib3 >= 1.26.0

Parameters

Parameter	Comments
api_uri string	Link to Github API. Default: `"https://api.github.com"`
appID string	GitHub App ID.
description string	Description of the credential or domain. Default: `""`
exc_hostname list / elements=string	List of hostnames to exclude from scope. If a hostname appears in both this list and `inc_hostname`, the hostname is excluded.
exc_hostname_port list / elements=string	List of host:port to exclude from scope. If a hostname and port appears in both this list and `inc_hostname_port`, it is excluded.
exc_path list / elements=string	List of URL paths to exclude. If a path is also matched by `exc_path`, it is excluded. If you exclude a subpath of a path previously included, that subpath alone is excluded.
file_path path	File path to secret file (for example `type=file` or `type=certificate`). For `type=certificate`, this can be a `.p12` or `.pem` file.
force boolean	Force update if the credential already exists, used with `state=present`. If set to `true`, it deletes the existing credential before creating a new one. Always returns `changed=true`. Choices: `false` ← (default) `true`
id string	The ID of the Jenkins credential or domain. When generating a new token, do not pass `id`. It is generated automatically.
inc_hostname list / elements=string	List of hostnames to include in scope.
inc_hostname_port list / elements=string	List of `host:port` to include in scope.
inc_path list / elements=string	List of URL paths to include when matching credentials to domains. Matching is hierarchical: subpaths of excluded paths are also excluded, even if explicitly included.
jenkins_password string	Jenkins password for token creation. Required if `type=token`.
jenkins_user string / required	Jenkins user for authentication.
location string	Location of the credential. Either `system` or `folder`. If `location=folder` then `url` must be set to `<jenkins-server>/job/<folder_name>`. Choices: `"system"` ← (default) `"folder"`
name string	Name of the token to generate. Required if `type=token`. When generating a new token, do not pass `id`. It is generated automatically. Creating two tokens with the same name generates two distinct tokens with different `token_uuid` values. Replacing a token with another one of the same name requires deleting the original first using `force=True`.
owner string	GitHub App owner.
passphrase string	SSH passphrase if needed.
password string	Password for credentials types that require it (for example `type=user_and_passs` or `type=certificate`).
private_key_path path	Path to private key file for PEM certificates or GitHub Apps.
schemes list / elements=string	List of schemes (for example `http` or `https`) to match.
scope string	Jenkins credential domain scope. Deleting a domain scope deletes all credentials within it. Default: `"_"`
secret string	Secret text (used when `type=text`).
state string	The state of the credential. Choices: `"present"` ← (default) `"absent"`
token string	Jenkins API token. Required unless `type=token`.
type string	Type of the credential or action. Choices: `"user_and_pass"` `"file"` `"text"` `"github_app"` `"ssh_key"` `"certificate"` `"scope"` `"token"`
url string	Jenkins server URL. Default: `"http://localhost:8080"`
username string	Username for credentials types that require it (for example `type=ssh_key` or `type=user_and_pass`).

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in `check_mode` and return changed status prediction without modifying target.
diff_mode	Support: none	Returns details on what has changed (or possibly needs changing in `check_mode`), when in diff mode.

Examples

- name: Generate token
  community.general.jenkins_credential:
    name: "test-token"
    jenkins_user: "admin"
    jenkins_password: "password"
    type: "token"
  register: token_result

- name: Save Jenkins token to INI file (you must secure/encrypt separately)
  vars:
    jenkins_token_ini: # Defining dict for to_ini filter
      api_token:
        uuid: "{{ token_result.token_uuid }}"
        token: "{{ token_result.token }}"
  ansible.builtin.copy:
    dest: "/secure/path/jenkins_token.ini"
    mode: '0600'
    content: "{{ jenkins_token_ini | community.general.to_ini }}"

# Note:
# (1) Jenkins token is intended to be securely stored in encrypted storage
#     or secrets vault outside the playbook, retrieved when needed.
# (2) Examples below showcasing token retrieval from
#     variable "token_result" are NOT how it should be used to add credentials.
# (3) Data in "token_result" is inconsistent and unavailable
#     across different playbooks and multiple executions.

- name: Add CUSTOM scope credential
  community.general.jenkins_credential:
    id: "CUSTOM"
    type: "scope"
    jenkins_user: "admin"
    token: "{{ token_result.token }}"
    description: "Custom scope credential"
    inc_path:
      - "include/path"
      - "include/path2"
    exc_path:
      - "exclude/path"
      - "exclude/path2"
    inc_hostname:
      - "included-hostname"
      - "included-hostname2"
    exc_hostname:
      - "excluded-hostname"
      - "excluded-hostname2"
    schemes:
      - "http"
      - "https"
    inc_hostname_port:
      - "included-hostname:7000"
      - "included-hostname2:7000"
    exc_hostname_port:
      - "excluded-hostname:7000"
      - "excluded-hostname2:7000"

- name: Add user_and_pass credential
  community.general.jenkins_credential:
    id: "userpass-id"
    type: "user_and_pass"
    jenkins_user: "admin"
    token: "{{ token_result.token }}"
    description: "User and password credential"
    username: "user1"
    password: "pass1"

- name: Add file credential to custom scope
  community.general.jenkins_credential:
    id: "file-id"
    type: "file"
    jenkins_user: "admin"
    token: "{{ token_result.token }}"
    scope: "CUSTOM"
    description: "File credential"
    file_path: "../vars/my-secret.pem"

- name: Add text credential to folder
  community.general.jenkins_credential:
    id: "text-id"
    type: "text"
    jenkins_user: "admin"
    token: "{{ token_result.token }}"
    description: "Text credential"
    secret: "mysecrettext"
    location: "folder"
    url: "http://localhost:8080/job/test"

- name: Add githubApp credential
  community.general.jenkins_credential:
    id: "githubapp-id"
    type: "github_app"
    jenkins_user: "admin"
    token: "{{ token_result.token }}"
    description: "GitHub app credential"
    appID: "12345"
    file_path: "../vars/github.pem"
    owner: "github_owner"

- name: Add sshKey credential
  community.general.jenkins_credential:
    id: "sshkey-id"
    type: "ssh_key"
    jenkins_user: "admin"
    token: "{{ token_result.token }}"
    description: "SSH key credential"
    username: "sshuser"
    file_path: "../vars/ssh_key"
    passphrase: 1234

- name: Add certificate credential (p12)
  community.general.jenkins_credential:
    id: "certificate-id"
    type: "certificate"
    jenkins_user: "admin"
    token: "{{ token_result.token }}"
    description: "Certificate credential"
    password: "12345678901234"
    file_path: "../vars/certificate.p12"

- name: Add certificate credential (pem)
  community.general.jenkins_credential:
    id: "certificate-id-pem"
    type: "certificate"
    jenkins_user: "admin"
    token: "{{ token_result.token }}"
    description: "Certificate credential (pem)"
    file_path: "../vars/cert.pem"
    private_key_path: "../vars/private.key"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
details string	Return more details in case of errors. Returned: failed
token string	The generated API token if `type=token`. This is needed to authenticate API calls later. This should be stored securely, as it is the only time it is returned. Returned: success
token_uuid string	The generated ID of the token. You pass this value back to the module as `id` to edit or revoke the token later. This should be stored securely, as it is the only time it is returned. Returned: success

Authors

Youssef Ali (@YoussefKhalidAli)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/general/jenkins_credential_module.html