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

Note

This module is part of the community.general collection (version 11.2.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

• 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.
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:
    id: "test-token"
    jenkins_user: "admin"
    jenkins_password: "password"
    type: "token"
  register: token_result

- name: Add CUSTOM scope credential
  community.general.jenkins_credential:
    id: "CUSTOM"
    type: "scope"
    jenkins_user: "admin"
    token: "{{ 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 }}"
    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 }}"
    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 }}"
    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 }}"
    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 }}"
    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 }}"
    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 }}"
    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

• Issue Tracker
• Repository (Sources)
• Ask for help
• Submit a bug report
• Request a feature
• Communication