diff --git a/doc/source/definition.rst b/doc/source/definition.rst index 7a9f80ff9..cbec164f0 100644 --- a/doc/source/definition.rst +++ b/doc/source/definition.rst @@ -70,6 +70,10 @@ itself (e.g. ``{name}-unit-tests`` in the above example) will be substituted in. This is useful in cases where you need to trace a job back to its template. +Sometimes it is useful to have the same job name format used even +where the template contents may vary. `Ids` provide a mechanism to +support such use cases. + .. _project: Project @@ -282,6 +286,27 @@ always use ``{{`` to achieve a literal ``{``. A generic builder will need to consider the correct quoting based on its use of parameters. +.. _ids: + +Item ID's +^^^^^^^^^ + +It's possible to assign an `id` to any of the blocks and then use that +to reference it instead of the name. This has two primary functions: + +* A unique identifier where you wish to use the same naming format for + multiple templates. This allows to follow a naming scheme while + still using multiple templates to handle subtle variables in job + requirements. +* Provides a simpler name for a `job-template` where you have multiple + variables in the name and don't wish to have to include this information + in every use. This also allows changing the template output name without + impacting references. + +Example: + +.. literalinclude:: /../../tests/yamlparser/fixtures/template_ids.yaml + .. _raw: Raw config diff --git a/jenkins_jobs/parser.py b/jenkins_jobs/parser.py index 5f4abb8b3..4d5cf2464 100644 --- a/jenkins_jobs/parser.py +++ b/jenkins_jobs/parser.py @@ -114,11 +114,13 @@ class YamlParser(object): raise JenkinsJobsException("Syntax error, for item " "named '{0}'. Missing indent?" .format(n)) - name = dfn['name'] - if name in group: - self._handle_dups("Duplicate entry found in '{0}: '{1}' " - "already defined".format(fp.name, name)) - group[name] = dfn + # allow any entry to specify an id that can also be used + id = dfn.get('id', dfn['name']) + if id in group: + self._handle_dups( + "Duplicate entry found in '{0}: '{1}' already " + "defined".format(fp.name, id)) + group[id] = dfn self.data[cls] = group def parse(self, fn): diff --git a/tests/yamlparser/fixtures/template_ids.xml b/tests/yamlparser/fixtures/template_ids.xml new file mode 100644 index 000000000..02c970e2b --- /dev/null +++ b/tests/yamlparser/fixtures/template_ids.xml @@ -0,0 +1,48 @@ +<?xml version="1.0" encoding="utf-8"?> +<project> + <actions/> + <description><!-- Managed by Jenkins Job Builder --></description> + <keepDependencies>false</keepDependencies> + <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding> + <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding> + <concurrentBuild>false</concurrentBuild> + <canRoam>true</canRoam> + <properties/> + <scm class="hudson.scm.NullSCM"/> + <builders> + <hudson.tasks.Shell> + <command>echo "Template name: template-test-ids-{num}-{type}" +echo "Job name: template-test-ids-1-periodic" +echo "Hello World" +</command> + </hudson.tasks.Shell> + </builders> + <publishers/> + <buildWrappers/> +</project> + +<?xml version="1.0" encoding="utf-8"?> +<project> + <actions/> + <description><!-- Managed by Jenkins Job Builder --></description> + <keepDependencies>false</keepDependencies> + <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding> + <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding> + <concurrentBuild>false</concurrentBuild> + <canRoam>true</canRoam> + <properties/> + <scm class="hudson.scm.NullSCM"/> + <builders> + <hudson.tasks.Shell> + <command>echo "Template name: template-test-ids-{num}-{type}" +echo "Job name: template-test-ids-2-canary" +</command> + </hudson.tasks.Shell> + <hudson.tasks.Shell> + <command>echo "Goodbye World" +</command> + </hudson.tasks.Shell> + </builders> + <publishers/> + <buildWrappers/> +</project> diff --git a/tests/yamlparser/fixtures/template_ids.yaml b/tests/yamlparser/fixtures/template_ids.yaml new file mode 100644 index 000000000..42733df8d --- /dev/null +++ b/tests/yamlparser/fixtures/template_ids.yaml @@ -0,0 +1,31 @@ +- project: + name: test_template_id + jobs: + - 'simple-template': + test_var: Hello World + type: periodic + num: 1 + - 'not-as-simple-template': + test_var: Goodbye World + type: canary + num: 2 + +- job-template: + name: 'template-test-ids-{num}-{type}' + id: simple-template + builders: + - shell: | + echo "Template name: {template-name}" + echo "Job name: template-test-ids-{num}-{type}" + echo "{test_var}" + +- job-template: + name: 'template-test-ids-{num}-{type}' + id: not-as-simple-template + builders: + - shell: | + echo "Template name: {template-name}" + echo "Job name: template-test-ids-{num}-{type}" + - shell: | + echo "{test_var}" +