Skip to content

Configuration

Damien Coraboeuf edited this page Sep 17, 2016 · 13 revisions

The configuration of a Seed job contains all the needed information to generate several projects.

Project parameters

Those parameters are specific to the project being generated and are usually either fixed or provided through job parameters.

Parameter Default Description
Project identifier Required Unique ID of the project - usually given as a parameter of the Seed job
Project SCM type Required Type of SCM for the project. Must be unique for all branches of the project. As of now, only git and svn are supported.
Project SCM URL Required URL to the project SCM. For Subversion, this must be the URL to the project base, without trunk or branch path.
Project SCM credentials None If access to the project SCM needs authentication, the credentials must be provided here. See [SCM credentials](SCM credentials) for more details.
Type of trigger authorised None If the generated project must have pipeline events triggered from SCM events, then the type of end point must be provided here. See Triggering for more information.
Trigger identifier None Trigger identifier, used to identify the project in the event sent by the trigger source. If blank, the project name is taken instead. For example, for the github trigger type, the project identifier must be the full name of the project, like nemerosa/ontrack, even if the project is left to be ontrack only. See the GitHub documentation for more information.
Secret token for trigger authorisation None If triggering from SCM events must be secured, a token must be provided here. See Triggering for more information.

Pipeline configuration

Those parameters define some global aspects of the pipeline generations. They are usually fixed at Seed job level and define a whole class of generated projects.

Parameter Default Description
Project branch destructor No Check if a branch destructor job must be generated at the same level of the branch generator job. This job takes the branch name as a unique parameter and will destroy the branch folder.
Authorisations for the project None Authorisations to grant to the generated project folder. See the authorisations documentation for more information.
Extra Branch SCM parameter No Asks for an extra Branch SCM parameter when generating a branch. See [Branch SCM path](Branch SCM path) for more information.
Extra branch parameters None Allows to define extra parameters when generating a branch. See Extensions for more information.
Extra DSL for project generation None Allows to define extra steps to run when generating a project. See Extensions for more information.
Extra DSL for pipeline generation None Allows to define extra steps to run when generating a branch. See Extensions for more information.
Disable DSL scripts No By default, when generating a branch, both property files and Groovy DSL files are allowed to define a pipeline. Setting this flag will disallow a branch to be generated from a DSL script. This is useful when you want to enforce that a given class of projects can only be generated through pipeline descriptors based on property files. See Generation for more information.
Script directory seed In some cases, you might want to use a custom directory to store the seed.properties or the seed.groovy file. It defaults to seed by default. If you want to store those files at the root, use . as a value for this property (dot).

Naming strategy

A project is associated with a naming strategy which allows to compute the paths of the different items of a pipeline.

Parameter Default Description
Project folder path ${project} Name of the project folder
Branch folder path ${project}-${branch} Name of the branch folder relative to the project folder
Project seed name ${project}-seed Name of the job, in the project folder, which is used to generate branch folders
Project destructor name ${project}-destructor Name of the job, in the project folder, which is used to remove branch folders (see also the Project branch destructor parameter in the Pipeline configuration)
Branch seed name ${project}-${branch}-seed Name of the job, in the branch folder, which generates or regenerates a branch pipeline
Branch start name ${project}-${branch}-build Name of the job, in the branch folder, which starts the branch pipeline for a given commit
Branch name ${branch} Expression which is used to translate the SCM branch name into a name useable for the creation of folders and jobs. Before this expression is evaluated, any defined branch prefix is removed (see below) and the name is normalised: any character other than A-Za-z0-9._- is replaced by a -
Ignored branch prefixes None When translating a SCM branch into a useable name (see just above), defines the list of prefixes to remove. In a SVN world, this will typically contain branches/

In all expressions, the following replacements are taken into account:

  • ${PROJECT} or ${BRANCH} - name of the project or the branch in UPPERCASE
  • ${PROJECT_} or ${BRANCH_} - name of the project or the branch in UPPERCASE and dashes (-) are replaced by underscores (_)
  • ${project} or ${branch} - name of the project or the branch in lowercase
  • ${Project} or ${Branch} - name of the project or the branch, capitalised
  • any other unsupported replacement expression will be left as is

Event strategy

If SCM-based triggering is enabled for a project, the following parameters allow to control the propagation of events.

Parameter Default Description
Delete complete pipeline on branch deletion Yes In case a deletion event is received for a branch, the default behaviour is to remove the whole branch folder. If this parameter is set to No, only the branch pipeline generator job will be deleted.
Regenerate pipeline when seed files changed Yes By default, when an event is sent after the seed files have changed (seed/seed.properties or seed/seed.groovy), the pipeline is regenerated automatically. Set this parameter to No to disable this behaviour. In this case, the pipeline will have to be (re)generated manually.
Triggers the pipeline start when commit received Yes By default, any commit related event will trigger the corresponding branch pipeline to be started. Set this parameter to No to disable this behaviour. In this case, the pipeline will have to be started manually.
Event parameter which contains the commit COMMIT Name of the parameter of the branch pipeline starting job which must contain the commit/revision to build.

Project cached configuration

Once a project has been seeded - its folder and seed job have been created - its actual configuration is saved in Jenkins and will be retrieved from this cache for all subsequent operations:

  • branch generation
  • branch pipeline generation
  • triggering

This allows the project configuration to be isolated from any change occurring in the origin seed job.

In order to realign the project with its seed, regenerate the project. Unless regenerated themselves, the existing branches are not impacted.

See also

You can’t perform that action at this time.