README.rst - salt-formulas/jenkins - Gitiles

 =====
 Usage
 =====

 Jenkins CI is an open source automation server written in Java. Jenkins
 helps to automate the non-human part of software development process,
 with continuous integration and facilitating technical aspects of
 continuous delivery.

 More information can be found at `<https://jenkins.io/>`_

 Setup jenkins client, works with Salt 2016.3+, supports pipeline
 workflow projects only for now.

 Dependencies
 ============

 To install on Ubuntu, you will need to add the jenkins debian repository
 to the target server. You can do this with the
 `salt-formula-linux formula <https://github.com/salt-formulas/salt-formula-linux>`_ ,
 with the following pillar data:

 .. code-block:: yaml

   linux:
     system:
       enabled: true
         repo:
         jenkins:
           enabled: true
           source: "deb http://pkg.jenkins.io/debian-stable binary/"
           key_url: "https://pkg.jenkins.io/debian/jenkins-ci.org.key"

 This state will need to be applied *before* the jenkins state.

 Using this formula
 ==================

 To use this formula, you must install the formula to your Salt
 Master as documented in
 `saltstack formula docs <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#installation>`_

 This formula is driven by pillar data, and can be used to
 install either a Jenkins Master or Client. See pillar data
 below for examples.

 Sample pillars
 ==============

 Master role
 -----------

 Simple master with reverse proxy:

 .. code-block:: yaml

     nginx:
       server:
         site:
           jenkins:
             enabled: true
             type: nginx_proxy
             name: jenkins
             proxy:
               host: 127.0.0.1
               port: 8080
               protocol: http
             host:
               name: jenkins.example.com
               port: 80
     jenkins:
       master:
         mode: EXCLUSIVE
         java_args: -Xms256m -Xmx1g
         # Do not manage any xml config files via Salt, use UI instead
         # Including config.xml and any plugin xml's.
         no_config: true
         slaves:
           - name: slave01
              label: pbuilder
              executors: 2
           - name: slave02
              label: image_builder
              mode: EXCLUSIVE
              executors: 2
         views:
           - name: "Package builds"
             regex: "debian-build-.*"
           - name: "Contrail builds"
             regex: "contrail-build-.*"
           - name: "Aptly"
             regex: "aptly-.*"
         plugins:
         - name: slack
         - name: extended-choice-parameter
         - name: rebuild
         - name: test-stability

 Jenkins master with experimental plugin source support:

 .. code-block:: yaml

     jenkins:
       master:
         enabled: true
         update_site_url: 'http://updates.jenkins-ci.org/experimental/update-center.json'

 SMTP server settings:

 .. code-block:: yaml

     jenkins:
       master:
         email:
           engine: "smtp"
           host: "smtp.domain.com"
           user: "user@domain.cz"
           password: "smtp-password"
           port: 25

 Script approvals from client:

 .. code-block:: yaml

     jenkins:
       client:
         approved_scripts:
           - method groovy.json.JsonSlurperClassic parseText java.lang.String

 Script approvals:

 .. code-block:: yaml

     jenkins:
       master:
         approved_scripts:
         - method groovy.json.JsonSlurperClassic parseText java.lang.String

 User enforcement:

 .. code-block:: yaml

     jenkins:
       master:
         user:
           admin:
             api_token: xxxxxxxxxx
             password: admin_password
             email: admin@domain.com
           user01:
             api_token: xxxxxxxxxx
             password: user_password
             email: user01@domain.com

 Agent (slave) role
 ------------------

 .. code-block:: yaml

     jenkins:
       slave:
         master:
           host: jenkins.example.com
           port: 80
           protocol: http
         user:
           name: jenkins_slave
           password: dexiech6AepohthaiHook2iesh7ol5ook4Ov3leid3yek6daid2ooNg3Ee2oKeYo
         gpg:
           keypair_id: A76882D3
           public_key: |
             -----BEGIN PGP PUBLIC KEY BLOCK-----
             ...
           private_key: |
             -----BEGIN PGP PRIVATE KEY BLOCK-----
             ...

 Client role
 -----------

 Simple client with workflow job definition:

 .. code-block:: yaml

     jenkins:
       client:
         master:
           host: jenkins.example.com
           port: 80
           protocol: http
         job:
           jobname:
             type: workflow
             param:
               bool_param:
                 type: boolean
                 description: true/false
                 default: true
               string_param:
                 type: string
                 description: 1 liner
                 default: default_string
               text_param:
                 type: text
                 description: multi-liner
                 default: default_text
           jobname_scm:
             type: workflow-scm
             concurrent: false
             scm:
               type: git
               url: https://github.com/jenkinsci/docker.git
               branch: master
               script: Jenkinsfile
               github:
                 url: https://github.com/jenkinsci/docker
                 name: "Jenkins Docker Image"
             trigger:
               timer:
                 spec: "H H * * *"
               github:
               pollscm:
                 spec: "H/15 * * * *"
               reverse:
                 projects:
                  - test1
                  - test2
                 state: SUCCESS
             param:
               bool_param:
                 type: boolean
                 description: true/false
                 default: true
               string_param:
                 type: string
                 description: 1 liner
                 default: default_string
               text_param:
                 type: text
                 description: multi-liner
                 default: default_text

 Inline Groovy scripts:

 .. code-block:: yaml

     jenkins:
       client:
         job:
           test_workflow_jenkins_simple:
             type: workflow
             display_name: Test jenkins simple workflow
             script:
               content: |
                 node {
                    stage 'Stage 1'
                    echo 'Hello World 1'
                    stage 'Stage 2'
                    echo 'Hello World 2'
                 }
           test_workflow_jenkins_input:
             type: workflow
             display_name: Test jenkins workflow inputs
             script:
               content: |
                 node {
                    stage 'Enter string'
                    input message: 'Enter job parameters', ok: 'OK', parameters: [
                      string(defaultValue: 'default', description: 'Enter a string.', name: 'string'),
                    ]
                    stage 'Enter boolean'
                    input message: 'Enter job parameters', ok: 'OK', parameters: [
                      booleanParam(defaultValue: false, description: 'Select boolean.', name: 'Bool'),
                    ]
                    stage 'Enter text'
                    input message: 'Enter job parameters', ok: 'OK', parameters: [
                      text(defaultValue: '', description: 'Enter multiline', name: 'Multiline')
                    ]
                 }

 GIT controlled groovy scripts:

 .. code-block:: yaml

     jenkins:
       client:
         source:
           base:
            engine: git
             address: repo_url
             branch: branch
           domain:
            engine: git
             address: domain_url
             branch: branch
         job:
           test_workflow_jenkins_simple:
             type: workflow
             display_name: Test jenkins simple workflow
             param:
               bool_param:
                 type: boolean
                 description: true/false
                 default: true
             script:
               repository: base
               file: workflows/test_workflow_jenkins_simple.groovy
           test_workflow_jenkins_input:
             type: workflow
             display_name: Test jenkins workflow inputs
             script:
               repository: domain
               file: workflows/test_workflow_jenkins_input.groovy
           test_workflow_jenkins_input_jenkinsfile:
             type: workflow
             display_name: Test jenkins workflow inputs (jenknisfile)
             script:
               repository: domain
               file: workflows/test_workflow_jenkins_input/Jenkinsfile

 GIT controlled groovy script with shared libraries:

 .. code-block:: yaml

     jenkins:
       client:
         source:
           base:
            engine: git
             address: repo_url
             branch: branch
           domain:
            engine: git
             address: domain_url
             branch: branch
         job:
           test_workflow_jenkins_simple:
             type: workflow
             display_name: Test jenkins simple workflow
             param:
               bool_param:
                 type: boolean
                 description: true/false
                 default: true
             script:
               repository: base
               file: workflows/test_workflow_jenkins_simple.groovy
             libs:
             - repository: base
               file: macros/cookiecutter.groovy
             - repository: base
               file: macros/git.groovy

 Setting job max builds to keep (amount of last builds stored on Jenkins master)

 .. code-block:: yaml

     jenkins:
       client:
         job:
           my-amazing-job:
             type: workflow
             discard:
               build:
                 keep_num: 5
                 keep_days: 5
               artifact:
                 keep_num: 6
                 keep_days: 6

 Using job templates in similar way as in jjb. For now just
 1 defined param is supported:

 .. code-block:: yaml

     jenkins:
       client:
         job_template:
           test_workflow_template:
             name: test-{{formula}}-workflow
             template:
               type: workflow
               display_name: Test jenkins {{name}} workflow
               param:
                 repo_param:
                   type: string
                   default: repo/{{formula}}
               script:
                 repository: base
                 file: workflows/test_formula_workflow.groovy
             param:
               formula:
               - aodh
               - linux
               - openssh

 Interpolating parameters for job templates:

 .. code-block:: yaml

     _param:
       salt_formulas:
       - aodh
       - git
       - nova
       - xorg
     jenkins:
       client:
         job_template:
           test_workflow_template:
             name: test-{{formula}}-workflow
             template:
               ...
             param:
               formula: ${_param:salt_formulas}

 Or simply define multiple jobs and it's parameters to
 replace from template:

 .. code-block:: yaml

    jenkins:
      client:
        job_template:
          test_workflow_template:
            name: test-{{name}}-{{myparam}}
            template:
              ...
            jobs:
              - name: firstjob
                myparam: dummy
              - name: secondjob
                myparam: dummyaswell

 Purging undefined jobs from Jenkins:

 .. code-block:: yaml

     jenkins:
       client:
         purge_jobs: true
         job:
           my-amazing-job:
             type: workflow

 Plugins management from client:

 .. code-block:: yaml

     jenkins:
       client:
         plugin_remove_unwanted: false
         plugin_force_remove: false
         plugin:
           plugin1: 1.2.3
           plugin2:
           plugin3: {}
           plugin4:
             version: 3.2.1
             enabled: false
           plugin5: absent

 Adding plugin params to job:

 .. code-block:: yaml

     jenkins:
       client:
         job:
           my_plugin_parametrized_job:
             plugin_properties:
               throttleconcurrents:
                 enabled: True
                 max_concurrent_per_node: 3
                 max_concurrent_total: 1
                 throttle_option: category #one of project (default or category)
                 categories:
                   - my_throuttle_category
         plugin:
           throttle-concurrents:

 LDAP configuration (depends on LDAP plugin):

 .. code-block:: yaml

     jenkins:
       client:
         security:
           ldap:
             server: 1.2.3.4
             root_dn: dc=foo,dc=com
             user_search_base: cn=users,cn=accounts
             manager_dn: ""
             manager_password: password
             user_search: ""
             group_search_base: ""
             inhibit_infer_root_dn: false

 Matrix configuration (depends on auth-matrix plugin):

 .. code-block:: yaml

     jenkins:
       client:
         security:
           matrix:
             # set true for use ProjectMatrixAuthStrategy instead of GlobalMatrixAuthStrategy
             project_based: false
             permissions:
               Jenkins:
                 # administrator access
                 ADMINISTER:
                   - admin
                 # read access (anonymous too)
                 READ:
                   - anonymous
                   - user1
                   - user2
                 # agents permissions
                 MasterComputer:
                   BUILD:
                     - user3
               # jobs permissions
               hudson:
                 model:
                   Item:
                     BUILD:
                       - user4

 `Common matrix strategies <https://github.com/arbabnazar/configuration/blob/c08a5eaf4e04a68d2481375502a926517097b253/playbooks/roles/tools_jenkins/templates/projectBasedMatrixSecurity.groovy.j2>`_

 Views enforcing from client:

 .. code-block:: yaml

     jenkins:
       client:
         view:
          my-list-view:
            enabled: true
            type: ListView
            include_regex: ".*"
          my-view:
            # set false to disable
            enabled: true
            type: MyView

 View specific params:

 - ``include_regex`` for ``ListView`` and ``CategorizedJobsView``
 - categories for ``CategorizedJobsView``

 Categorized views:

 .. code-block:: yaml

     jenkins:
       client:
         view:
           my-categorized-view:
             enabled: true
             type: CategorizedJobsView
             include_regex: ".*"
             categories:
               - group_regex: "aptly-.*-nightly-testing"
                 naming_rule: "Nightly -> Testing"
               - group_regex: "aptly-.*-nightly-production"
                 naming_rule: "Nightly -> Production"

 Credentials enforcing from client:

 .. code-block:: yaml

     jenkins:
       client:
         credential:
           cred_first:
             username: admin
             password: password
           cred_second:
             username: salt
             password: password
           cred_with_key:
             username: admin
             key: SOMESSHKEY
           cred_with_text_secret:
             secret: SOMETEXTSECRET
           cred_with_secret_file:
             filename: somefile.json
             content: |
               { "Hello": "world!" }

 Users enforcing from client:

 .. code-block:: yaml

     jenkins:
       client:
         user:
           admin:
             password: admin_password
             admin: true
           user01:
             password: user_password

 Node enforcing from client using JNLP launcher:

 .. code-block:: yaml

     jenkins:
       client:
         node:
           node01:
             remote_home: /remote/home/path
             desc: node-description
             num_executors: 1
             node_mode: Normal
             ret_strategy: Always
             labels:
               - example
               - label
             launcher:
                type: jnlp

 Node enforcing from client using SSH launcher:

 .. code-block:: yaml

     jenkins:
       client:
         node:
           node01:
             remote_home: /remote/home/path
             desc: node-description
             num_executors: 1
             node_mode: Normal
             ret_strategy: Always
             labels:
               - example
               - label
             launcher:
                type: ssh
                host: test-launcher
                port: 22
                username: launcher-user
                password: launcher-pass

 Configure Jenkins master:

 .. code-block:: yaml

     jenkins:
       client:
         node:
           master:
             num_executors: 1
             node_mode: Normal # or Exclusive
             labels:
               - example
               - label

 Setting node labels:

 .. code-block:: yaml

     jenkins:
       client:
         label:
           node-name:
             lbl_text: label-offline
             append: false # set true for label append instead of replace

 SMTP server settings from client:

 .. code-block:: yaml

     jenkins:
       client:
         smtp:
           host: "smtp.domain.com"
           username: "user@domain.cz"
           password: "smtp-password"
           port: 25
           ssl: false
           reply_to: reply_to@address.com

 Jenkins admin user email enforcement from client:

 .. code-block:: yaml

     jenkins:
       client:
         smtp:
           admin_email: "My Jenkins <jenkins@myserver.com>"

 Slack plugin configuration:

 .. code-block:: yaml

     jenkins:
       client:
         slack:
           team_domain: example.com
           token: slack-token
           room: slack-room
           token_credential_id: cred_id
           send_as: Some slack user

 Pipeline global libraries setup:

 .. code-block:: yaml

     jenkins:
       client:
         lib:
           my-pipeline-library:
             enabled: true
             url: https://path-to-my-library
             credential_id: github
             branch: master # optional, default master
             implicit: true # optional default true

 Artifactory server enforcing:

 .. code-block:: yaml

     jenkins:
       client:
         artifactory:
           my-artifactory-server:
             enabled: true
             url: https://path-to-my-library
             credential_id: github

 Jenkins Global env properties enforcing:

 .. code-block:: yaml

     jenkins:
       client:
         globalenvprop:
           OFFLINE_DEPLOYMENT:
             enabled: true
             name: "OFFLINE_DEPLOYMENT" # optional, default using dict key
             value: "true"

 Throttle categories management from client (requires
 `Throttle Concurrent Builds <https://plugins.jenkins.io/throttle-concurrents>`_
 plugin):

 .. code-block:: yaml

     jenkins:
       client:
         throttle_category:
           'My First Category':
             max_total: 2
             max_per_node: 1
           'My Second Category':
             max_total: 5
             max_per_node: 2
             max_per_label:
               'node_label_1': 1
               'node_label_2': 2
           'My Category To Remove:
             enabled: false

 Jira sites management from client (requires
 `JIRA <https://plugins.jenkins.io/jira>`_ plugin):

 .. code-block:: yaml

     # Remove all sites
     jenkins:
       client:
         jira:
           enabled: False

 .. code-block:: yaml

     jenkins:
       client:
         jira:
           sites:
             'http://my.jira.site/':
               link_url: 'http://alternative.link/'
               http_auth: false
               use_wiki_notation: false
               record_scm: false
               disable_changelog: false
               issue_pattern: ''
               any_build_result: false
               user: 'username'
               password: 'passwd'
               conn_timeout: 10
               visible_for_group: ''
               visible_for_project: ''
               timestamps: false
               timestamp_format: ''

 Gerrit trigger plugin configuration:

 .. code-block:: yaml

     jenkins:
       client:
         gerrit:
           server1:
             host: "gerrit.domain.local"
             port: 29418
             username: "jenkins"
             email: "jenkins@domain.local"
             auth_key_file: "/var/jenkins_home/.ssh/id_rsa"
             frontendURL: "https://gerrit.domain.local"
             build_current_patches_only: true
             abort_new_patchsets: false
             abort_manual_patchsets: false
             abort_same_topic: false
             authkey: |
               SOMESSHKEY
           server2:
             host: "gerrit2.domain.local"
             port: 29418
             username: "jenkins"
             email: "jenkins@domain.local"
             auth_key_file: "/var/jenkins_home/.ssh/id_rsa"
             frontendURL: "https://gerrit2.domain.local"
             build_current_patches_only: true
             abort_new_patchsets: false
             abort_manual_patchsets: false
             abort_same_topic: false
             authkey: |
               SOMESSHKEY

 CSRF Protection configuration:

 .. code-block:: yaml

     jenkins:
       client:
         security:
           csrf:
             enabled: true
             proxy_compat: false

 Agent to Master Access Control:

 .. code-block:: yaml

     jenkins:
       client:
         security:
           agent2master:
             enabled: true
             whitelisted: ''
             file_path_rules: ''

 Content Security Policy configuration:

 .. code-block:: yaml

     jenkins:
       client:
         security:
           csp: "sandbox; default-src 'none'; img-src 'self'; style-src 'self';"

 Usage
 =====

 #. Generate password hash:

    .. code-block:: bash

     echo -n "salt{plainpassword}" | openssl dgst -sha256

 #. Place in the configuration ``salt:hashpassword``.


 Read more
 =========

 * https://wiki.jenkins-ci.org/display/JENKINS/Use+Jenkins

 Documentation and Bugs
 ======================

 * http://salt-formulas.readthedocs.io/
    Learn how to install and update salt-formulas

 * https://github.com/salt-formulas/salt-formula-jenkins/issues
    In the unfortunate event that bugs are discovered, report the issue to the
    appropriate issue tracker. Use the Github issue tracker for a specific salt
    formula

 * https://launchpad.net/salt-formulas
    For feature requests, bug reports, or blueprints affecting the entire
    ecosystem, use the Launchpad salt-formulas project

 * https://launchpad.net/~salt-formulas-users
    Join the salt-formulas-users team and subscribe to mailing list if required

 * https://github.com/salt-formulas/salt-formula-jenkins
    Develop the salt-formulas projects in the master branch and then submit pull
    requests against a specific formula

 * #salt-formulas @ irc.freenode.net
    Use this IRC channel in case of any questions or feedback which is always
    welcome
	=====
	Usage
	=====

	Jenkins CI is an open source automation server written in Java. Jenkins
	helps to automate the non-human part of software development process,
	with continuous integration and facilitating technical aspects of
	continuous delivery.

	More information can be found at `<https://jenkins.io/>`_

	Setup jenkins client, works with Salt 2016.3+, supports pipeline
	workflow projects only for now.

	Dependencies
	============

	To install on Ubuntu, you will need to add the jenkins debian repository
	to the target server. You can do this with the
	`salt-formula-linux formula <https://github.com/salt-formulas/salt-formula-linux>`_ ,
	with the following pillar data:

	.. code-block:: yaml

	linux:
	system:
	enabled: true
	repo:
	jenkins:
	enabled: true
	source: "deb http://pkg.jenkins.io/debian-stable binary/"
	key_url: "https://pkg.jenkins.io/debian/jenkins-ci.org.key"

	This state will need to be applied before the jenkins state.

	Using this formula
	==================

	To use this formula, you must install the formula to your Salt
	Master as documented in
	`saltstack formula docs <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#installation>`_

	This formula is driven by pillar data, and can be used to
	install either a Jenkins Master or Client. See pillar data
	below for examples.

	Sample pillars
	==============

	Master role
	-----------

	Simple master with reverse proxy:

	.. code-block:: yaml

	nginx:
	server:
	site:
	jenkins:
	enabled: true
	type: nginx_proxy
	name: jenkins
	proxy:
	host: 127.0.0.1
	port: 8080
	protocol: http
	host:
	name: jenkins.example.com
	port: 80
	jenkins:
	master:
	mode: EXCLUSIVE
	java_args: -Xms256m -Xmx1g
	# Do not manage any xml config files via Salt, use UI instead
	# Including config.xml and any plugin xml's.
	no_config: true
	slaves:
	- name: slave01
	label: pbuilder
	executors: 2
	- name: slave02
	label: image_builder
	mode: EXCLUSIVE
	executors: 2
	views:
	- name: "Package builds"
	regex: "debian-build-.*"
	- name: "Contrail builds"
	regex: "contrail-build-.*"
	- name: "Aptly"
	regex: "aptly-.*"
	plugins:
	- name: slack
	- name: extended-choice-parameter
	- name: rebuild
	- name: test-stability

	Jenkins master with experimental plugin source support:

	.. code-block:: yaml

	jenkins:
	master:
	enabled: true
	update_site_url: 'http://updates.jenkins-ci.org/experimental/update-center.json'

	SMTP server settings:

	.. code-block:: yaml

	jenkins:
	master:
	email:
	engine: "smtp"
	host: "smtp.domain.com"
	user: "user@domain.cz"
	password: "smtp-password"
	port: 25

	Script approvals from client:

	.. code-block:: yaml

	jenkins:
	client:
	approved_scripts:
	- method groovy.json.JsonSlurperClassic parseText java.lang.String

	Script approvals:

	.. code-block:: yaml

	jenkins:
	master:
	approved_scripts:
	- method groovy.json.JsonSlurperClassic parseText java.lang.String

	User enforcement:

	.. code-block:: yaml

	jenkins:
	master:
	user:
	admin:
	api_token: xxxxxxxxxx
	password: admin_password
	email: admin@domain.com
	user01:
	api_token: xxxxxxxxxx
	password: user_password
	email: user01@domain.com

	Agent (slave) role
	------------------

	.. code-block:: yaml

	jenkins:
	slave:
	master:
	host: jenkins.example.com
	port: 80
	protocol: http
	user:
	name: jenkins_slave
	password: dexiech6AepohthaiHook2iesh7ol5ook4Ov3leid3yek6daid2ooNg3Ee2oKeYo
	gpg:
	keypair_id: A76882D3
	public_key: \|
	-----BEGIN PGP PUBLIC KEY BLOCK-----
	...
	private_key: \|
	-----BEGIN PGP PRIVATE KEY BLOCK-----
	...

	Client role
	-----------

	Simple client with workflow job definition:

	.. code-block:: yaml

	jenkins:
	client:
	master:
	host: jenkins.example.com
	port: 80
	protocol: http
	job:
	jobname:
	type: workflow
	param:
	bool_param:
	type: boolean
	description: true/false
	default: true
	string_param:
	type: string
	description: 1 liner
	default: default_string
	text_param:
	type: text
	description: multi-liner
	default: default_text
	jobname_scm:
	type: workflow-scm
	concurrent: false
	scm:
	type: git
	url: https://github.com/jenkinsci/docker.git
	branch: master
	script: Jenkinsfile
	github:
	url: https://github.com/jenkinsci/docker
	name: "Jenkins Docker Image"
	trigger:
	timer:
	spec: "H H * * *"
	github:
	pollscm:
	spec: "H/15 * * * *"
	reverse:
	projects:
	- test1
	- test2
	state: SUCCESS
	param:
	bool_param:
	type: boolean
	description: true/false
	default: true
	string_param:
	type: string
	description: 1 liner
	default: default_string
	text_param:
	type: text
	description: multi-liner
	default: default_text

	Inline Groovy scripts:

	.. code-block:: yaml

	jenkins:
	client:
	job:
	test_workflow_jenkins_simple:
	type: workflow
	display_name: Test jenkins simple workflow
	script:
	content: \|
	node {
	stage 'Stage 1'
	echo 'Hello World 1'
	stage 'Stage 2'
	echo 'Hello World 2'
	}
	test_workflow_jenkins_input:
	type: workflow
	display_name: Test jenkins workflow inputs
	script:
	content: \|
	node {
	stage 'Enter string'
	input message: 'Enter job parameters', ok: 'OK', parameters: [
	string(defaultValue: 'default', description: 'Enter a string.', name: 'string'),
	]
	stage 'Enter boolean'
	input message: 'Enter job parameters', ok: 'OK', parameters: [
	booleanParam(defaultValue: false, description: 'Select boolean.', name: 'Bool'),
	]
	stage 'Enter text'
	input message: 'Enter job parameters', ok: 'OK', parameters: [
	text(defaultValue: '', description: 'Enter multiline', name: 'Multiline')
	]
	}

	GIT controlled groovy scripts:

	.. code-block:: yaml

	jenkins:
	client:
	source:
	base:
	engine: git
	address: repo_url
	branch: branch
	domain:
	engine: git
	address: domain_url
	branch: branch
	job:
	test_workflow_jenkins_simple:
	type: workflow
	display_name: Test jenkins simple workflow
	param:
	bool_param:
	type: boolean
	description: true/false
	default: true
	script:
	repository: base
	file: workflows/test_workflow_jenkins_simple.groovy
	test_workflow_jenkins_input:
	type: workflow
	display_name: Test jenkins workflow inputs
	script:
	repository: domain
	file: workflows/test_workflow_jenkins_input.groovy
	test_workflow_jenkins_input_jenkinsfile:
	type: workflow
	display_name: Test jenkins workflow inputs (jenknisfile)
	script:
	repository: domain
	file: workflows/test_workflow_jenkins_input/Jenkinsfile

	GIT controlled groovy script with shared libraries:

	.. code-block:: yaml

	jenkins:
	client:
	source:
	base:
	engine: git
	address: repo_url
	branch: branch
	domain:
	engine: git
	address: domain_url
	branch: branch
	job:
	test_workflow_jenkins_simple:
	type: workflow
	display_name: Test jenkins simple workflow
	param:
	bool_param:
	type: boolean
	description: true/false
	default: true
	script:
	repository: base
	file: workflows/test_workflow_jenkins_simple.groovy
	libs:
	- repository: base
	file: macros/cookiecutter.groovy
	- repository: base
	file: macros/git.groovy

	Setting job max builds to keep (amount of last builds stored on Jenkins master)

	.. code-block:: yaml

	jenkins:
	client:
	job:
	my-amazing-job:
	type: workflow
	discard:
	build:
	keep_num: 5
	keep_days: 5
	artifact:
	keep_num: 6
	keep_days: 6

	Using job templates in similar way as in jjb. For now just
	1 defined param is supported:

	.. code-block:: yaml

	jenkins:
	client:
	job_template:
	test_workflow_template:
	name: test-{{formula}}-workflow
	template:
	type: workflow
	display_name: Test jenkins {{name}} workflow
	param:
	repo_param:
	type: string
	default: repo/{{formula}}
	script:
	repository: base
	file: workflows/test_formula_workflow.groovy
	param:
	formula:
	- aodh
	- linux
	- openssh

	Interpolating parameters for job templates:

	.. code-block:: yaml

	_param:
	salt_formulas:
	- aodh
	- git
	- nova
	- xorg
	jenkins:
	client:
	job_template:
	test_workflow_template:
	name: test-{{formula}}-workflow
	template:
	...
	param:
	formula: ${_param:salt_formulas}

	Or simply define multiple jobs and it's parameters to
	replace from template:

	.. code-block:: yaml

	jenkins:
	client:
	job_template:
	test_workflow_template:
	name: test-{{name}}-{{myparam}}
	template:
	...
	jobs:
	- name: firstjob
	myparam: dummy
	- name: secondjob
	myparam: dummyaswell

	Purging undefined jobs from Jenkins:

	.. code-block:: yaml

	jenkins:
	client:
	purge_jobs: true
	job:
	my-amazing-job:
	type: workflow

	Plugins management from client:

	.. code-block:: yaml

	jenkins:
	client:
	plugin_remove_unwanted: false
	plugin_force_remove: false
	plugin:
	plugin1: 1.2.3
	plugin2:
	plugin3: {}
	plugin4:
	version: 3.2.1
	enabled: false
	plugin5: absent

	Adding plugin params to job:

	.. code-block:: yaml

	jenkins:
	client:
	job:
	my_plugin_parametrized_job:
	plugin_properties:
	throttleconcurrents:
	enabled: True
	max_concurrent_per_node: 3
	max_concurrent_total: 1
	throttle_option: category #one of project (default or category)
	categories:
	- my_throuttle_category
	plugin:
	throttle-concurrents:

	LDAP configuration (depends on LDAP plugin):

	.. code-block:: yaml

	jenkins:
	client:
	security:
	ldap:
	server: 1.2.3.4
	root_dn: dc=foo,dc=com
	user_search_base: cn=users,cn=accounts
	manager_dn: ""
	manager_password: password
	user_search: ""
	group_search_base: ""
	inhibit_infer_root_dn: false

	Matrix configuration (depends on auth-matrix plugin):

	.. code-block:: yaml

	jenkins:
	client:
	security:
	matrix:
	# set true for use ProjectMatrixAuthStrategy instead of GlobalMatrixAuthStrategy
	project_based: false
	permissions:
	Jenkins:
	# administrator access
	ADMINISTER:
	- admin
	# read access (anonymous too)
	READ:
	- anonymous
	- user1
	- user2
	# agents permissions
	MasterComputer:
	BUILD:
	- user3
	# jobs permissions
	hudson:
	model:
	Item:
	BUILD:
	- user4

	`Common matrix strategies <https://github.com/arbabnazar/configuration/blob/c08a5eaf4e04a68d2481375502a926517097b253/playbooks/roles/tools_jenkins/templates/projectBasedMatrixSecurity.groovy.j2>`_

	Views enforcing from client:

	.. code-block:: yaml

	jenkins:
	client:
	view:
	my-list-view:
	enabled: true
	type: ListView
	include_regex: ".*"
	my-view:
	# set false to disable
	enabled: true
	type: MyView

	View specific params:

	- ``include_regex`` for ``ListView`` and ``CategorizedJobsView``
	- categories for ``CategorizedJobsView``

	Categorized views:

	.. code-block:: yaml

	jenkins:
	client:
	view:
	my-categorized-view:
	enabled: true
	type: CategorizedJobsView
	include_regex: ".*"
	categories:
	- group_regex: "aptly-.*-nightly-testing"
	naming_rule: "Nightly -> Testing"
	- group_regex: "aptly-.*-nightly-production"
	naming_rule: "Nightly -> Production"

	Credentials enforcing from client:

	.. code-block:: yaml

	jenkins:
	client:
	credential:
	cred_first:
	username: admin
	password: password
	cred_second:
	username: salt
	password: password
	cred_with_key:
	username: admin
	key: SOMESSHKEY
	cred_with_text_secret:
	secret: SOMETEXTSECRET
	cred_with_secret_file:
	filename: somefile.json
	content: \|
	{ "Hello": "world!" }

	Users enforcing from client:

	.. code-block:: yaml

	jenkins:
	client:
	user:
	admin:
	password: admin_password
	admin: true
	user01:
	password: user_password

	Node enforcing from client using JNLP launcher:

	.. code-block:: yaml

	jenkins:
	client:
	node:
	node01:
	remote_home: /remote/home/path
	desc: node-description
	num_executors: 1
	node_mode: Normal
	ret_strategy: Always
	labels:
	- example
	- label
	launcher:
	type: jnlp

	Node enforcing from client using SSH launcher:

	.. code-block:: yaml

	jenkins:
	client:
	node:
	node01:
	remote_home: /remote/home/path
	desc: node-description
	num_executors: 1
	node_mode: Normal
	ret_strategy: Always
	labels:
	- example
	- label
	launcher:
	type: ssh
	host: test-launcher
	port: 22
	username: launcher-user
	password: launcher-pass

	Configure Jenkins master:

	.. code-block:: yaml

	jenkins:
	client:
	node:
	master:
	num_executors: 1
	node_mode: Normal # or Exclusive
	labels:
	- example
	- label

	Setting node labels:

	.. code-block:: yaml

	jenkins:
	client:
	label:
	node-name:
	lbl_text: label-offline
	append: false # set true for label append instead of replace

	SMTP server settings from client:

	.. code-block:: yaml

	jenkins:
	client:
	smtp:
	host: "smtp.domain.com"
	username: "user@domain.cz"
	password: "smtp-password"
	port: 25
	ssl: false
	reply_to: reply_to@address.com

	Jenkins admin user email enforcement from client:

	.. code-block:: yaml

	jenkins:
	client:
	smtp:
	admin_email: "My Jenkins <jenkins@myserver.com>"

	Slack plugin configuration:

	.. code-block:: yaml

	jenkins:
	client:
	slack:
	team_domain: example.com
	token: slack-token
	room: slack-room
	token_credential_id: cred_id
	send_as: Some slack user

	Pipeline global libraries setup:

	.. code-block:: yaml

	jenkins:
	client:
	lib:
	my-pipeline-library:
	enabled: true
	url: https://path-to-my-library
	credential_id: github
	branch: master # optional, default master
	implicit: true # optional default true

	Artifactory server enforcing:

	.. code-block:: yaml

	jenkins:
	client:
	artifactory:
	my-artifactory-server:
	enabled: true
	url: https://path-to-my-library
	credential_id: github

	Jenkins Global env properties enforcing:

	.. code-block:: yaml

	jenkins:
	client:
	globalenvprop:
	OFFLINE_DEPLOYMENT:
	enabled: true
	name: "OFFLINE_DEPLOYMENT" # optional, default using dict key
	value: "true"

	Throttle categories management from client (requires
	`Throttle Concurrent Builds <https://plugins.jenkins.io/throttle-concurrents>`_
	plugin):

	.. code-block:: yaml

	jenkins:
	client:
	throttle_category:
	'My First Category':
	max_total: 2
	max_per_node: 1
	'My Second Category':
	max_total: 5
	max_per_node: 2
	max_per_label:
	'node_label_1': 1
	'node_label_2': 2
	'My Category To Remove:
	enabled: false

	Jira sites management from client (requires
	`JIRA <https://plugins.jenkins.io/jira>`_ plugin):

	.. code-block:: yaml

	# Remove all sites
	jenkins:
	client:
	jira:
	enabled: False

	.. code-block:: yaml

	jenkins:
	client:
	jira:
	sites:
	'http://my.jira.site/':
	link_url: 'http://alternative.link/'
	http_auth: false
	use_wiki_notation: false
	record_scm: false
	disable_changelog: false
	issue_pattern: ''
	any_build_result: false
	user: 'username'
	password: 'passwd'
	conn_timeout: 10
	visible_for_group: ''
	visible_for_project: ''
	timestamps: false
	timestamp_format: ''

	Gerrit trigger plugin configuration:

	.. code-block:: yaml

	jenkins:
	client:
	gerrit:
	server1:
	host: "gerrit.domain.local"
	port: 29418
	username: "jenkins"
	email: "jenkins@domain.local"
	auth_key_file: "/var/jenkins_home/.ssh/id_rsa"
	frontendURL: "https://gerrit.domain.local"
	build_current_patches_only: true
	abort_new_patchsets: false
	abort_manual_patchsets: false
	abort_same_topic: false
	authkey: \|
	SOMESSHKEY
	server2:
	host: "gerrit2.domain.local"
	port: 29418
	username: "jenkins"
	email: "jenkins@domain.local"
	auth_key_file: "/var/jenkins_home/.ssh/id_rsa"
	frontendURL: "https://gerrit2.domain.local"
	build_current_patches_only: true
	abort_new_patchsets: false
	abort_manual_patchsets: false
	abort_same_topic: false
	authkey: \|
	SOMESSHKEY

	CSRF Protection configuration:

	.. code-block:: yaml

	jenkins:
	client:
	security:
	csrf:
	enabled: true
	proxy_compat: false

	Agent to Master Access Control:

	.. code-block:: yaml

	jenkins:
	client:
	security:
	agent2master:
	enabled: true
	whitelisted: ''
	file_path_rules: ''

	Content Security Policy configuration:

	.. code-block:: yaml

	jenkins:
	client:
	security:
	csp: "sandbox; default-src 'none'; img-src 'self'; style-src 'self';"

	Usage
	=====

	#. Generate password hash:

	.. code-block:: bash

	echo -n "salt{plainpassword}" \| openssl dgst -sha256

	#. Place in the configuration ``salt:hashpassword``.


	Read more
	=========

	* https://wiki.jenkins-ci.org/display/JENKINS/Use+Jenkins

	Documentation and Bugs
	======================

	* http://salt-formulas.readthedocs.io/
	Learn how to install and update salt-formulas

	* https://github.com/salt-formulas/salt-formula-jenkins/issues
	In the unfortunate event that bugs are discovered, report the issue to the
	appropriate issue tracker. Use the Github issue tracker for a specific salt
	formula

	* https://launchpad.net/salt-formulas
	For feature requests, bug reports, or blueprints affecting the entire
	ecosystem, use the Launchpad salt-formulas project

	* https://launchpad.net/~salt-formulas-users
	Join the salt-formulas-users team and subscribe to mailing list if required

	* https://github.com/salt-formulas/salt-formula-jenkins
	Develop the salt-formulas projects in the master branch and then submit pull
	requests against a specific formula

	* #salt-formulas @ irc.freenode.net
	Use this IRC channel in case of any questions or feedback which is always
	welcome