{"id":14008460,"url":"https://github.com/jenkinsci/ansible-plugin","last_synced_at":"2026-01-17T16:14:57.487Z","repository":{"id":31165773,"uuid":"34725942","full_name":"jenkinsci/ansible-plugin","owner":"jenkinsci","description":"Jenkins Ansible plugin","archived":false,"fork":false,"pushed_at":"2025-05-06T02:38:52.000Z","size":691,"stargazers_count":230,"open_issues_count":23,"forks_count":115,"subscribers_count":114,"default_branch":"main","last_synced_at":"2025-05-06T03:29:58.643Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"https://plugins.jenkins.io/ansible/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"jcsirot/ansible-plugin","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jenkinsci.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-04-28T11:12:10.000Z","updated_at":"2025-05-06T02:38:55.000Z","dependencies_parsed_at":"2023-09-25T05:58:18.940Z","dependency_job_id":"6d8ff914-16ab-4d04-8d83-7e3844fd50e7","html_url":"https://github.com/jenkinsci/ansible-plugin","commit_stats":{"total_commits":304,"total_committers":32,"mean_commits":9.5,"dds":0.575657894736842,"last_synced_commit":"a8dfc7bbc9ebcb6dffaaf47cad1281c8a97a91c0"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fansible-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fansible-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fansible-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fansible-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jenkinsci","download_url":"https://codeload.github.com/jenkinsci/ansible-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254464895,"owners_count":22075570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest"],"created_at":"2024-08-10T11:01:41.795Z","updated_at":"2026-01-17T16:14:57.476Z","avatar_url":"https://github.com/jenkinsci.png","language":"Java","funding_links":[],"categories":["Java"],"sub_categories":[],"readme":"# Ansible Plugin\n\n![Build](https://ci.jenkins.io/job/Plugins/job/ansible-plugin/job/main/badge/icon)\n[![Coverage](https://ci.jenkins.io/job/Plugins/job/ansible-plugin/job/main/badge/icon?status=${instructionCoverage}\u0026subject=coverage\u0026color=${colorInstructionCoverage})](https://ci.jenkins.io/job/Plugins/job/ansible-plugin/job/main)\n[![LOC](https://ci.jenkins.io/job/Plugins/job/ansible-plugin/job/main/badge/icon?job=test\u0026status=${lineOfCode}\u0026subject=line%20of%20code\u0026color=blue)](https://ci.jenkins.io/job/Plugins/job/ansible-plugin/job/main)\n![Contributors](https://img.shields.io/github/contributors/jenkinsci/ansible-plugin.svg?color=blue)\n[![GitHub release](https://img.shields.io/github/release/jenkinsci/ansible-plugin.svg?label=changelog)](https://github.com/jenkinsci/ansible-plugin/releases/latest)\n[![Jenkins Plugin Installs](https://img.shields.io/jenkins/plugin/i/ansible.svg?color=blue)](https://plugins.jenkins.io/ansible)\n[![GitHub license](https://img.shields.io/github/license/jenkinsci/ansible-plugin)](https://github.com/jenkinsci/ansible-plugin/blob/main/LICENSE.md)\n\nThis plugin allows to execute [Ansible](http://www.ansible.com/) tasks as a job build step.\n\n## Global Configuration\n\nAnsible needs to be on the PATH for the build job in order to be used.\nThis can be done through either Jenkins Global Tool Configuration or\nincluding Ansible on the OS User PATH variable.\n\n### Global Tool Configuration\n\nConfiguring Ansible through the Global Tool Configuration in Jenkins\n(Jenkins → Manage Jenkins → Global Tool Configuration) allows for\nmultiple Ansible installations to be present and used by different\nJenkins jobs.\n\n1.  Click \"Add Ansible\"\n2.  Configure the name and path\n\n    | Field name                            | Description                                                                                               |\n    | --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |\n    | Name                                  | Symbolic name used to identify a specific Ansible installation when multiple installations are configured |\n    | Path to ansible executables directory | Directory containing the *ansible,* *ansible-playbook*, and *ansible-vault* binaries                      |\n\n3.  Repeat for any additional desired installations\n\nThere is no automatic ansible installation possible using Global Tools.\n\n### OS User PATH\n\nAnsible can also be added to the PATH user used by the Jenkins executor\ninstead of configured through Global Tool Configuration. This is done\nthrough normal OS tools outside of Jenkins and is not covered by this\nguide.\n\n------------------------------------------------------------------------\n\n## Supported versions\n\nThe plugin is tested against supported ansible-core versions (https://endoflife.date/ansible-core). It might work with older versions, but this is not guaranteed.\n\nSee `PipelineTest.java`\n\n```java\nprivate static Stream\u003cString\u003e ansibleVersions() {\n    return Stream.of(\"2.18.12\", \"2.19.5\", \"2.20.1\");\n}\n```\n\n## Adhoc\n\n[Adhoc commands](http://docs.ansible.com/ansible/latest/intro_adhoc.html) allow\nfor simple operations to be done without writing a full playbook. This\nallows for a convenient way of doing quick tasks with Ansible.\n\n### Examples\n\n#### Scripted\n\n**Jenkinsfile**\n\n``` groovy\nansibleAdhoc credentialsId: 'private_key', inventory: 'inventories/a/hosts', hosts: 'hosts_pattern', moduleArguments: 'module_arguments'\n```\n\n#### Declarative\n\n**Jenkinsfile**\n\n``` groovy\nansibleAdhoc(credentialsId: 'private_key', inventory: 'inventories/a/hosts', hosts: 'hosts_pattern', moduleArguments: 'module_arguments')\n```\n\n### Arguments\n\nSee also [jenkins.io](https://jenkins.io/doc/pipeline/steps/ansible/) documentation.\n\n| Freestyle Name                         | Pipeline Name      |  Description                                                  |\n| -------------------------------------- | ------------------ | ------------------------------------------------------------- |\n| Ansible installation                   | installation       | Ansible installation to use for the playbook invocation       |\n| Host pattern                           | hosts              | The host pattern to manage. See Ansible Patterns for details. |\n| Module                                 | module             | CLI arg: `-m`                                                 |\n| Module arguments or command to execute | moduleArguments    | CLI arg: `-a`                                                 |\n| Inventory file or host list            | inventory          | CLI arg: `-i`: See the Inventory section for additional details. |\n| Inventory inline content               | inventoryContent   | CLI arg: `-i`: See the Inventory section for additional details. |\n| Credentials                            | credentialsId      | The Jenkins credential to use for the SSH connection. See the Authentication section for additional details. |\n| Vault Credentials                      | vaultCredentialsId | CLI arg: `--vault-password-file`: The Jenkins credential to use as the vault credential. See the Vault Credentials section for additional details. |\n| Vault temp path                        | vaultTmpPath       | Path where to store temporary vault secrets files, ssh key files, etc... Default is in workspace. |\n| sudo                                   | become             | CLI arg: `-s` |\n| sudo user                              | becomeUser         | CLI arg: `-U` |\n| Number of parallel processes           | forks              | CLI arg: `-f` |\n| Check host SSH key                     | hostKeyChecking    | Toggle checking of the host key. Sets the environment variable `ANSIBLE_HOST_KEY_CHECKING`, similar to the recommendations for running with Vagrant. |\n| Unbuffered stdout                      |                    | Toggle buffering of standard out. Sets the environment variable `PYTHONUNBUFFERED`, similar to the recommendations for running with Vagrant. |\n| Colorized stdout                       | colorized          | Toggle color codes in console text. See Colorized Output section for example usage. Sets the environment variable `ANSIBLE_FORCE_COLOR`, similar to the recommendations for running with Vagrant. |\n| Extra Variables                        | extraVars          | CLI arg: `-e` |\n| Additional parameters                  | extras             | String passed to the Ansible Command Line invocation as-is. |\n\n## Playbook\n\n[Ansible playbook](http://docs.ansible.com/ansible/latest/playbooks.html)\noperations can be run with the plugin. The plugin provides several\nconveniences such as easily using credentials from the Jenkins\ncredential store, unbuffered color output in the log, etc.\n\n### Examples\n\n#### Scripted\n\n**Jenkinsfile**\n\n``` groovy\nansiblePlaybook credentialsId: 'private_key', inventory: 'inventories/a/hosts', playbook: 'my_playbook.yml'\n```\n\n#### Declarative\n\n**Jenkinsfile**\n\n``` groovy\nansiblePlaybook(credentialsId: 'private_key', inventory: 'inventories/a/hosts', playbook: 'my_playbook.yml')\n```\n\nAdditional scripted and declarative pipeline examples can be found on\nthe plugin's [GitHub\nreadme](https://github.com/jenkinsci/ansible-plugin).\n\n### Arguments\n\nRefer to [jenkins.io](https://jenkins.io/doc/pipeline/steps/ansible/)\nfor documentation extracted from the online help of the plugin.\n\n| Freestyle Name                         | Pipeline Name       | Description                                                   |\n| -------------------------------------- | ------------------- | ------------------------------------------------------------- |\n| Ansible installation                   | installation        | Ansible installation to use for the playbook invocation       |\n| Playbook path                          | playbook            | Mandatory. The name of the playbook to run                    |\n| Inventory file or host list            | inventory           | CLI arg: `-i`: See the inventory section for details.         |\n| Inventory inline content               | inventoryContent    | CLI arg: `-i`: See the inventory section for details.         |\n| Credentials                            | credentialsId       | The Jenkins credential to use for the SSH connection. See the Authentication section for additional details |\n| Vault Credentials                      | vaultCredentialsId  | The Jenkins credential to use as the vault credential. See the Vault Credentials section for more details |\n| Vault temp path                        | vaultTmpPath        | Path where to store temporary vault secrets files, ssh key files, etc... rkspace. |\n| sudo                                   | sudo                | CLI arg: `-s`                                                 |\n| sudo user                              | sudoUser            | CLI arg: `-U`                                                 |\n| Host subset                            | limit               | CLI arg: `-l`                                                 |\n| Tags to run                            | tags                | CLI arg: `-t`                                                 |\n| Tags to skip                           | skippedTags         | CLI arg: `--skip-tags`                                        |\n| Task to start at                       | startAtTask         | CLI arg: `--start-at-task`                                    |\n| Number of parallel processes           | forks               | CLI arg: `-f`                                                 |\n| Check host SSH key                     | hostKeyChecking     | Toggle checking of the host key. Sets the environment variable ANSIBLE_HOST_KEY_CHECKING, similar to the recommendations for running with Vagrant. |\n| Colorized stdout                       | colorized           | Toggle color codes in console text. See Colorized Output section for example usage. Sets the environment variable ANSIBLE_FORCE_COLOR, similar to the recommendations for running with Vagrant.  |\n| Additional parameters                  | extras              | String passed to the Ansible Command Line invocation as-is    |\n| Extra Variables                        | extraVars           | CLI arg: `-e`                                                 |\n\nRefer to the ansible-playbook manual page for details on how each\ncommand line argument is interpreted.\n\n### Authentication\n\n#### SSH Keys\n\n[SSH keys](https://help.ubuntu.com/community/SSH/OpenSSH/Keys) are the\nrecommended authentication method for SSH connections. The plugin\nsupports the credential type \"SSH Username with private key\" configured\nin the Jenkins credential store through the [SSH crendentials\nplugin](https://plugins.jenkins.io/ssh-credentials).\n\n#### Password\n\nEven if using SSH keys is recommended authentication method, password\nauthentication may sometimes be required. The plugin has supported\npassword based authentication since 0.3.0. When using password based\nauthentication, the [sshpass](http://sourceforge.net/projects/sshpass/)\nbinary is expected to be on the PATH. The plugin supports the credential\ntype \"Username with password\" configured in the Jenkins credential store\nthrough the [SSH crendentials\nplugin](https://plugins.jenkins.io/ssh-credentials).\n\n### Vault Credentials\n\nVault credentials can be setup in the Jenkins credential store as either\na \"Secret text\" or a \"Secret file\".\n\n### Colorized Output\n\nThe [AnsiColor plugin](https://plugins.jenkins.io/ansicolor) is needed\nfor colorized console output. Once installed, colorized output can be\nenabled with the argument \"colorized: true\".\n\n**Jenkinsfile**\n\n``` groovy\nansiColor('xterm') {\n    ansiblePlaybook(\n        playbook: 'path/to/playbook.yml',\n        inventory: 'path/to/inventory.ini',\n        credentialsId: 'sample-ssh-key',\n        colorized: true)\n}\n```\n\n![](docs/images/jenkins-deploy-ansible-console.png)\n\n### Extra Parameters\n\nExtra parameters is a string passed to the Ansible Command Line\ninvocation as-is and can be useful for arguments occasionally added to\nan invocation at runtime, such as tags and host limits.\n\n### Inventory\n\n#### File\n\nA string path to the inventory file to use with the playbook invocation.\n\n#### Inline\n\nThe provided content is used as the content of the inventory file for\nthe playbook invocation.\n\n### Using Jenkins Environment Variables\n\nJenkins environment variables can be accessed from within an Ansible\nplaybook. The Jenkins variables are injected as environment variables\nmaking them available through the Ansible [lookup\nplugin](http://docs.ansible.com/ansible/latest/playbooks_lookups.html).\n\nThe following Ansible playbook accesses the Jenkins BUILD\\_TAG variable:\n\n**playbook.yml**\n\n``` groovy\n---\n- hosts: example\n  tasks:\n    - debug: msg=\"{{ lookup('env','BUILD_TAG') }}\"\n```\n\n------------------------------------------------------------------------\n\n## Vault\n\nMost [Ansible Vault](https://docs.ansible.com/ansible/latest/vault.html)\noperations can be performed with the plugin. Interactive operations such\nas create, edit, and view are not supported through the plugin. One use\ncase for this enabling developers to encrypt secret values while keeping\nthe vault password a secret.\n\n### Examples\n\n#### Scripted\n\n**Encrypts a File**\n\n``` groovy\nansibleVault action: 'encrypt', input: 'vars/secrets.yml', vaultCredentialsId: 'ansible_vault_credentials'\n```\n\n**Encrypts a String**\n\n``` groovy\nansibleVault action: 'encrypt_string', content: 'secret_content', vaultCredentialsId: 'ansible_vault_credentials'\n```\n\n#### Declarative\n\n**Jenkinsfile**\n\n``` groovy\nansibleVault(action: 'encrypt', input: 'vars/secrets.yml', vaultCredentialsId: 'ansible_vault_credentials')\n```\n\n**Jenkinsfile**\n\n``` groovy\nansibleVault(action: 'encrypt_string', content: 'secret_content', vaultCredentialsId: 'ansible_vault_password')\n```\n\n### Arguments\n\nSee also [jenkins.io Pipeline step](https://jenkins.io/doc/pipeline/steps/ansible/) documentation.\n\n| Freestyle Name                         | Pipeline Name         | Description                                                   |\n| -------------------------------------- | --------------------- | ------------------------------------------------------------- |\n| Ansible installation                   | installation          | Ansible installation to use for the playbook invocation       |\n| Action                                 | action                | Mandatory. The name of the action to use. Interactive operations such as create, edit, and view are not supported. |\n| Vault Credentials                      | vaultCredentialsId    | CLI arg: `--vault-password-file`. The Jenkins credential to use as the vault credential. See the Vault Credentials section for more details |\n| New Vault Credentials                  | newVaultCredentialsId | CLI arg: `--new-vault-password-file`. The Jenkins credential to use as the vault credential. See the Vault Credentials section for more details |\n| Vault temp path                        | vaultTmpPath          | Path where to store temporary vault secrets files, ssh key files, etc... Default is in workspace. |\n| Content                                | content               | The content to encrypt with the 'encrypt_string' action.      |\n| Input                                  | input                 | The file to encrypt with the encrypt actions.                 |\n| Output                                 | output                | CLI arg: `--output`                                           |\n\n### Vault Credentials\n\nVault credentials can be setup in the Jenkins credential store as either\na \"Secret text\" or a \"Secret file\".\n\n------------------------------------------------------------------------\n\n## Changelog\n\nChangelog is now published on GitHub release.\n\n## Using Jenkins Build and Environment Variables\n\nIt is possible to access build and environment variables in ansible playbooks. These variables are injected as environment variables within the ansible process. For example, use this code in an ansible playbook to access Jenkins ```BUILD_TAG``` variable.\n\n```yaml\n---\n- hosts: example\n  tasks:\n    - debug: msg=\"{{ lookup('env','BUILD_TAG') }}\"\n```\n\n## Job DSL support\n\n```groovy\nsteps {\n    ansiblePlaybook(String playbook) {\n        inventoryPath(String path)\n        inventoryContent(String content, boolean dynamic = false)\n        ansibleName(String name)\n        limit(String limit)\n        tags(String tags)\n        skippedTags(String tags)\n        startAtTask(String task)\n        credentialsId(String id)\n        checkMode(boolean checkMode = false)\n        become(boolean become = true)\n        becomeUser(String user = 'root')\n        sudo(boolean sudo = true)\n        sudoUser(String user = 'root')\n        forks(int forks = 5)\n        unbufferedOutput(boolean unbufferedOutput = true)\n        colorizedOutput(boolean colorizedOutput = false)\n        hostKeyChecking(boolean hostKeyChecking = false)\n        additionalParameters(String params)\n        extraVars {\n            extraVar(String key, String value, boolean hidden)\n        }\n    }\n\n    ansibleAdHoc(String module, String command) {\n        ansibleName(String name)\n        inventoryPath(String path)\n        inventoryContent(String content, boolean dynamic = false)\n        credentialsId(String id)\n        hostPattern(String pattern)\n        become(boolean become = true)\n        becomeUser(String user = 'root')\n        sudo(boolean sudo = true)\n        sudoUser(String user = 'root')\n        forks(int forks = 5)\n        unbufferedOutput(boolean unbufferedOutput = true)\n        colorizedOutput(boolean colorizedOutput = false)\n        hostKeyChecking(boolean hostKeyChecking = false)\n        additionalParameters(String params)\n        extraVars {\n            extraVar(String key, String value, boolean hidden)\n        }\n    }\n}\n```\n\n### Example\n\n```groovy\nsteps {\n    ansiblePlaybook('path/playbook.yml') {\n        inventoryPath('hosts.ini')\n        ansibleName('1.9.4')\n        tags('one,two')\n        credentialsId('credsid')\n        become(true)\n        becomeUser(\"user\")\n        checkMode(false)\n        extraVars {\n            extraVar(\"key1\", \"value1\", false)\n            extraVar(\"key2\", \"value2\", true)\n        }\n    }\n}\n```\n\n```groovy\nsteps {\n    ansiblePlaybookBuilder {\n        playbook('path/playbook.yml')\n        inventory {\n            inventoryDoNotSpecify()\n        }\n        unbufferedOutput(true)\n        extraVars {\n            extraVar {\n                key('key1')\n                secretValue(hudson.util.Secret.fromString('value1'))\n                hidden(false)\n            }\n            extraVar {\n                key('key2')\n                secretValue(hudson.util.Secret.fromString('value2'))\n                hidden(true)\n            }\n        }\n    }\n}\n```\n\n## Pipeline support\n\nAnsible playbooks can be executed from workflow scripts. Only the `playbook` parameter is mandatory.\n\n### Example\n\n```groovy\nnode {\n    ansiblePlaybook(\n        playbook: 'path/to/playbook.yml',\n        inventory: 'path/to/inventory.ini',\n        credentialsId: 'sample-ssh-key',\n        extras: '-e parameter=\"some value\"')\n}\n```\n\n### Extra Variables\n\nExtra variables can be passed to ansible by using a map in the pipeline script.\nSupported value types are: `String`, `Boolean`, `Number`.\nBy default the value will be considered potentially sensitive and masked in the logs.\nTo override this give a map with keys `value` and `hidden`.\n\n```groovy\nnode {\n    ansiblePlaybook(\n        inventory: 'local_inventory/hosts.cfg',\n        playbook: 'cloud_playbooks/create-aws.yml',\n        extraVars: [\n            login: 'mylogin',\n            toggle: true,\n            forks: 8,\n            not_secret: [value: 'I want to see this in the logs', hidden: false]\n        ])\n}\n```\n\n### Colorized Console Log\n\nYou need to install the [AnsiColor plugin](https://plugins.jenkins.io/ansicolor/) to output a\ncolorized Ansible log.\n\n```groovy\nnode {\n    wrap([$class: 'AnsiColorBuildWrapper', colorMapName: \"xterm\"]) {\n        ansiblePlaybook(\n            playbook: 'path/to/playbook.yml',\n            inventory: 'path/to/inventory.ini',\n            credentialsId: 'sample-ssh-key',\n            colorized: true)\n    }\n}\n```\n\n## Contributing\n\nRefer to our [contribution guidelines](https://github.com/jenkinsci/.github/blob/master/CONTRIBUTING.md)\n\n## LICENSE\n\nLicensed under MIT, see [LICENSE](LICENSE.md)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fansible-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjenkinsci%2Fansible-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fansible-plugin/lists"}