blob: 58f337125bdfc0a5f23c67e0359b5ecb2f10e6ed [file] [log] [blame]
James E. Blaireff5a9d2017-06-20 00:00:37 -07001:title: Job Content
2
3Job Content
4===========
5
6Zuul jobs are implemneted as Ansible playbooks. Zuul prepares the
7repositories used for a job, installs any required Ansible roles, and
8then executes the job's playbooks. Any setup or artifact collection
9required is the responsibility of the job itself. While this flexible
10arrangement allows for almost any kind of job to be run by Zuul,
11batteries are included. Zuul has a standard library of jobs upon
12which to build.
13
14Working Directory
15-----------------
16
17Before starting each job, the Zuul executor creates a directory to
18hold all of the content related to the job. This includes some
19directories which are used by Zuul to configure and run Ansible and
20may not be accessible, as well as a directory tree, under ``work/``,
21that is readable and writable by the job. The hierarchy is:
22
23**work/**
24 The working directory of the job.
25
26**work/src/**
27 Contains the prepared git repositories for the job.
28
29**work/logs/**
30 Where the Ansible log for the job is written; your job
31 may place other logs here as well.
32
33Git Repositories
34----------------
35
36The git repositories in ``work/src`` contain the repositories for all
37of the projects specified in the ``required-projects`` section of the
38job, plus the project associated with the queue item if it isn't
39already in that list. In the case of a proposed change, that change
40and all of the changes ahead of it in the pipeline queue will already
41be merged into their respective repositories and target branches. The
42change's project will have the change's branch checked out, as will
43all of the other projects, if that branch exists (otherwise, a
44fallback or default branch will be used). If your job needs to
45operate on multiple branches, simply checkout the appropriate branches
46of these git repos to ensure that the job results reflect the proposed
47future state that Zuul is testing, and all dependencies are present.
48Do not use any git remotes; the local repositories are guaranteed to
49be up to date.
50
James E. Blair4d5dd252017-06-23 21:40:56 +010051The repositories will be placed on the filesystem in directories
52corresponding with the canonical hostname of their source connection.
53For example::
54
55 work/src/git.example.com/project1
56 work/src/github.com/project2
57
58Is the layout that would be present for a job which included project1
59from the connection associated to git.example.com and project2 from
60GitHub. This helps avoid collisions between projects with the same
61name, and some language environments, such as Go, expect repositories
62in this format.
63
James E. Blaireff5a9d2017-06-20 00:00:37 -070064Note that these git repositories are located on the executor; in order
65to be useful to most kinds of jobs, they will need to be present on
66the test nodes. The ``base`` job in the standard library contains a
67pre-playbook which copies the repositories to all of the job's nodes.
68It is recommended to always inherit from this base job to ensure that
69behavior.
70
71.. TODO: link to base job documentation and/or document src (and logs?) directory
72
73Zuul Variables
74--------------
75
76Zuul supplies not only the variables specified by the job definition
77to Ansible, but also some variables from the executor itself. They
78are:
79
80**zuul.executor.hostname**
81 The hostname of the executor.
82
83**zuul.executor.src_root**
84 The path to the source directory.
85
86**zuul.executor.log_root**
87 The path to the logs directory.
88
89SSH Keys
90--------
91
92Zuul starts each job with an SSH agent running and the key used to
93access the job's nodes added to that agent. Generally you won't need
94to be aware of this since Ansible will use this when performing any
95tasks on remote nodes. However, under some circumstances you may want
96to interact with the agent. For example, you may wish to add a key
97provided as a secret to the job in order to access a specific host, or
98you may want to, in a pre-playbook, replace the key used to log into
99the assigned nodes in order to further protect it from being abused by
100untrusted job content.
101
102.. TODO: describe standard lib and link to published docs for it.
103
James E. Blair196f61a2017-06-30 15:42:29 -0700104Return Values
105-------------
106
107The job may return some values to Zuul to affect its behavior. To
108return a value, use the *zuul_return* Ansible module in a job
109playbook. For example::
110
111 tasks:
112 - zuul_return:
113 data:
114 foo: bar
115
116Will return the dictionary "{'foo': 'bar'}" to Zuul.
117
118.. TODO: xref to section describing formatting
119
120Several uses of these values are planned, but the only currently
121implemented use is to set the log URL for a build. To do so, set the
122**zuul.log_url** value. For example::
123
124 tasks:
125 - zuul_return:
126 data:
127 zuul:
128 log_url: http://logs.example.com/path/to/build/logs