jenkinsflow.flow module

exception jenkinsflow.flow.Killed[source]

Bases: Exception

class jenkinsflow.flow.parallel(jenkins_api, timeout, securitytoken=None, username=None, password=None, job_name_prefix='', max_tries=1, propagation=<Propagation.NORMAL: 0>, report_interval=5, poll_interval=0.5, secret_params=re.compile('.*passw.*|.*PASSW.*'), allow_missing_jobs=False, json_dir=None, json_indent=None, json_strip_top_level_prefix=True, direct_url=None, require_idle=True, just_dump=False, params_display_order=(), kill_all=False, description=None, raise_if_unsuccessful=True)[source]

Bases: jenkinsflow.flow._Parallel, jenkinsflow.flow._TopLevelControllerMixin

Defines a parallel flow where nested jobs or flows are executed simultaneously.

See serial and _Flow.parallel() for a description.

class jenkinsflow.flow.serial(jenkins_api, timeout, securitytoken=None, username=None, password=None, job_name_prefix='', max_tries=1, propagation=<Propagation.NORMAL: 0>, report_interval=5, poll_interval=0.5, secret_params=re.compile('.*passw.*|.*PASSW.*'), allow_missing_jobs=False, json_dir=None, json_indent=None, json_strip_top_level_prefix=True, direct_url=None, require_idle=True, just_dump=False, params_display_order=(), kill_all=False, description=None, raise_if_unsuccessful=True)[source]

Bases: jenkinsflow.flow._Serial, jenkinsflow.flow._TopLevelControllerMixin

Defines a serial flow where nested jobs or flows are executed in order.

Only differences to _Flow.serial() are described.

Parameters:
  • jenkins_api (jenkins_api.Jenkins or script_api.Jenkins) – Jenkins Api instance used for accessing jenkins. If jenkins_api is instantiated with username/password you do not need to specify username/password to the flow (see below).
  • securitytoken (str) – Token to use on security enabled Jenkins instead of username/password. The Jenkins job must have the token configured.
  • username (str) – Name of user authorized to run Jenkins ‘cli’ and change job status.
  • password (str) – Password of user. The username/password here is are not used for running the jobs. See jenkins_api for that. If username/password is specified for jenkins_api, they will be used unless they are also specified on the flow.
  • job_name_prefix (str) – All jobs defined in flow will automatically be prefixed with this string before invoking Jenkins job.
  • poll_interval (float) – The interval in seconds between polling the status of unfinished Jenkins jobs.
  • allow_missing_jobs (boolean) – If true it is not considered an error if Jenkins jobs are missing when the flow starts. It is assumed that the missing jobs are created by other jobs in the flow
  • json_dir (str) – Directory in which to generate flow graph json file. If None, no flow graph is generated.
  • json_indent (int) – If not None json graph file is pretty printed with this indentation level.
  • json_strip_top_level_prefix (boolean) – If True, the job_name_prefix will be stripped from job names when generating json graph file
  • direct_url (str) – Non proxied url for accessing Jenkins, use this as an optimization to avoid routing rest calls from Jenkins through a proxy if the JENKINS_URL setting does not point directly to jenkins.
  • require_idle (boolean) – If True it is considered an error if any of the jobs in the flow are running when the flow starts.
  • just_dump (boolean) – If True, the flow is just printed, no jobs are invoked.
  • params_display_order (list) – List of job parameter names used for ordering the parameters in the output. The format is [first1, …, firstN, ‘*’, last1, …, lastN], where first…, last… are names that will be matched against the invoke **param names. Any of first…, ‘*’, last… may be omitted Any parameters that are not matched will be displayes at the place of the ‘*’, if specified, otherwise they will be displayed last.
  • kill_all (boolean) – If True, all running builds for jobs defined in the flow will be aborted, regardless which flow invocation started the build. Note: It also possible to send SIGTERM to an already running flow to make the flow abort all builds started by the current invocation of the flow, but not builds started by other invocations of the same flow.
  • raise_if_unsuccessful (bool) –

    If the result of the outermost flow is not BuildResult.SUCCESS and no exception was raised, then a FinalResultException will be raised. The result property of this exception should be checked and the proper value returned from the shell step. Use in combination with the ‘Exit code to set build unstable’ feature in the advanced section on freestyle jobs shell build step. E.g:

    try:
    with parallel(api) as ctrl1:
        ctrl1.invoke('j11')

        with ctrl1.serial() as ctrl2:
            ctrl2.invoke('j21')  # ends succesfully
            ctrl2.invoke('j22')  # ends in state UNSTABLE
            ctrl2.invoke('j23')

except FinalResultException as ex:
    if ex.result == BuildResult.UNSTABLE:
        return 77
    raise

    If set to False, then the propagated reult value is available as the attribute ‘result’ on the top level flow, so that it can be used to return the proper value.
Returns:

serial flow object
Raises:

JobControlException
class jenkinsflow.flow._Flow[source]
invoke(job_name, **params)[source]

Define a Jenkins job invocation that will be invoked under control of the surrounding flow.

This does not create the job in Jenkins. It defines how the job will be invoked by jenkinsflow.

Parameters:
  • job_name (str) – The last part of the name of the job in jenkins. If the surrounding flow sets the job_name_prefix the actual name of the invoked job will be the parent flow job_name_prefix + job_name.
  • **params (str, int, boolean) – Arguments passed to Jenkins when invoking the job. Strings are passed as they are, booleans are automatically converted to strings and lowercased, integers are automatically converted to strings.
invoke_unchecked(job_name, **params)[source]

Define a Jenkins job invocation that will be invoked under control of the surrounding flow, but will never cause the flow to fail.

The job is always run in parallel with other jobs in the flow, even when invoked in a serial flow. It is not started out of order, but following jobs will be started immediately after this is started. The job will be monitored and reported on, only as long as regular “checked” jobs are still running. If it fails, it may be retried (depending on surrounding flows max_tries option), but only as long as regular jobs are still running. If the job is still running when all normal jobs are finished, the flow will exit, and the job is left running.

See invoke() for parameter description.

parallel(timeout=0, securitytoken=None, job_name_prefix='', max_tries=1, propagation=<Propagation.NORMAL: 0>, report_interval=None, secret_params=None, allow_missing_jobs=None)[source]

Defines a parallel flow where nested jobs or flows are executed simultaneously.

Only differences to serial() are described.

Parameters:max_tries (int) –

Maximum number of times to invoke the jobs in the flow. Default is 1, meaning no retry will be attempted in case jobs fails. If a job fails it is immediately retried:

with parallel(..., max_tries=3) as sf:
    sf.invoke('a', ...)
    sf.invoke('b', ...)  # fail -> restart job 'b'
    sf.invoke('c', ...)
Returns:parallel flow object
serial(timeout=0, securitytoken=None, job_name_prefix='', max_tries=1, propagation=<Propagation.NORMAL: 0>, report_interval=None, secret_params=None, allow_missing_jobs=None)[source]

Defines a serial flow where nested jobs or flows are executed in order.

Parameters:
  • timeout (float) – Maximum time in seconds to wait for flow jobs to finish. 0 means infinite, however, this flow can not run longer than the minimum timeout of any parent flows. Note that jenkins jobs are NOT terminated when the flow times out.
  • securitytoken (str) – Token to use on security enabled Jenkins instead of username/password. The Jenkins job must have the token configured. If None, the parent flow securitytoken is used.
  • job_name_prefix (str) – All jobs defined in flow will automatically be prefixed with the parent flow job_name_prefix + this job_name_prefix before invoking Jenkins job. To reset prefixing (i.e. don’t use parent flow prefix either), set the value to None
  • max_tries (int) –

    Maximum number of times to invoke the flow. Default is 1, meaning no retry will be attempted in case a job fails. If a job fails, jobs are retried from start of the parallel flow:

    with serial(..., max_tries=3) as sf:
    sf.invoke('a', ...)
    sf.invoke('b', ...)  # fail -> restart flow from job 'a'
    sf.invoke('c', ...)

    Retries may be nested:

    with parallel(..., max_tries=2) as pf:
    with pf.serial(..., max_tries=3) as sf:
        sf.invoke('a', ...)  # If job 'a' fails it could be invoked up to 6 times
  • propagation (Propagation) –

    How to propagate errors from failed Jenkins jobs. This can be used to downgrade a ‘FAILURE’ result to ‘UNSTABLE’. This will not change the result of a failed job, the result of jobs are used in caculating the propagated result. E.g:

    with parallel(...) as pf:
    with pf.serial(..., propagation=Propagation.UNSTABLE) as sf1:
        sf1.invoke('a', ...)  # If job 'a' fails the result propagated to sf1 will be 'UNSTABLE' and sf1 will propagate
                              #  'UNSTABLE' on to pf

    with pf.serial(...) as sf2:
        sf2.invoke('b', ...)  # If job 'b' fails the result propagated to sf2 and pf will be 'FAILURE'

sys.exit(77 if pf.result == Propagation.UNSTABLE else 0)
# Assuming the Jenkins job was configured with 'Exit code to set build unstable==77'

    NOTE: You must make sure that the jobs are configured correctly and that the correct exit code is used in the shell step, otherwise the propagation value will have no effect on the final job status. NOTE: Also see the raise_if_unsuccessful argument to the top level serial and parallel flows.

  • report_interval (float) – The interval in seconds between reporting the status of polled Jenkins jobs. If None the parent flow report_interval is used.
  • secret_params (re.RegexObject) – Regex of Jenkins job invocation parameter names, for which the value will be masked out with ‘**’ when parameters are printed. If None the parent flow secret_params is used.
  • allow_missing_jobs (boolean) – If true it is not considered an error if Jenkins jobs are missing when the flow starts. It is assumed that the missing jobs are created by jobs in the flow, prior to the missing jobs being invoked. If None the parent flow allow_missing_jobs is used.
Returns:

serial flow object
Raises:

JobControlException
class jenkinsflow.flow._JobControl[source]
message(msg)[source]

Define a message that will be printed before the invocation of the job or flow on which it is defined.

Parameters:msg (object) – The message that will be printed.