blob: 521e4edde1201d6ae97216254c05ff5de103cc22 [file] [log] [blame]
Joshua Heskethfe485c62015-08-11 23:42:34 +10001:title: Connections
2
3.. _connections:
4
5Connections
6===========
7
8zuul coordinates talking to multiple different systems via the concept
9of connections. A connection is listed in the :ref:`zuulconf` file and is
10then referred to from the :ref:`layoutyaml`. This makes it possible to
11receive events from gerrit via one connection and post results from another
12connection that may report back as a different user.
13
14Gerrit
15------
16
17Create a connection with gerrit.
18
19**driver=gerrit**
20
21**server**
22 FQDN of Gerrit server.
23 ``server=review.example.com``
24
James E. Blair1c774422017-03-28 16:16:34 -070025**canonical_hostname**
26 The canonical hostname associated with the git repos on the Gerrit
27 server. Defaults to the value of **server**. This is used to
28 identify repos from this connection by name and in preparing repos
29 on the filesystem for use by jobs.
30 ``canonical_hostname=git.example.com``
31
Joshua Heskethfe485c62015-08-11 23:42:34 +100032**port**
33 Optional: Gerrit server port.
34 ``port=29418``
35
36**baseurl**
37 Optional: path to Gerrit web interface. Defaults to ``https://<value
38 of server>/``. ``baseurl=https://review.example.com/review_site/``
39
40**user**
41 User name to use when logging into above server via ssh.
42 ``user=zuul``
43
44**sshkey**
45 Path to SSH key to use when logging into above server.
46 ``sshkey=/home/zuul/.ssh/id_rsa``
47
Evgeny Antyshev9f0a3222015-10-23 16:03:10 +000048**keepalive**
49 Optional: Keepalive timeout, 0 means no keepalive.
50 ``keepalive=60``
Joshua Heskethfe485c62015-08-11 23:42:34 +100051
52Gerrit Configuration
53~~~~~~~~~~~~~~~~~~~~
54
55Zuul will need access to a Gerrit user.
56
57Create an SSH keypair for Zuul to use if there isn't one already, and
58create a Gerrit user with that key::
59
60 cat ~/id_rsa.pub | ssh -p29418 gerrit.example.com gerrit create-account --ssh-key - --full-name Jenkins jenkins
61
62Give that user whatever permissions will be needed on the projects you
63want Zuul to gate. For instance, you may want to grant ``Verified
64+/-1`` and ``Submit`` to the user. Additional categories or values may
65be added to Gerrit. Zuul is very flexible and can take advantage of
66those.
67
Gregory Haynes4fc12542015-04-22 20:38:06 -070068GitHub
69------
70
71Create a connection with GitHub.
72
73**driver=github**
74
75**api_token**
76 API token for accessing GitHub.
77 See `Creating an access token for command-line use
78 <https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`_.
79
80**webhook_token**
81 Optional: Token for validating the webhook event payloads.
82 If not specified, payloads are not validated.
83 See `Securing your webhooks
84 <https://developer.github.com/webhooks/securing/>`_.
85
Joshua Heskethfe485c62015-08-11 23:42:34 +100086SMTP
87----
88
89**driver=smtp**
90
91**server**
92 SMTP server hostname or address to use.
93 ``server=localhost``
94
95**port**
96 Optional: SMTP server port.
97 ``port=25``
98
99**default_from**
100 Who the email should appear to be sent from when emailing the report.
101 This can be overridden by individual pipelines.
102 ``default_from=zuul@example.com``
103
104**default_to**
105 Who the report should be emailed to by default.
106 This can be overridden by individual pipelines.
107 ``default_to=you@example.com``
Joshua Heskethd78b4482015-09-14 16:56:34 -0600108
109SQL
110----
111
112 Only one connection per a database is permitted.
113
114 **driver=sql**
115
116 **dburi**
117 Database connection information in the form of a URI understood by
118 sqlalchemy. eg http://docs.sqlalchemy.org/en/rel_1_0/core/engines.html#database-urls
119 ``dburi=mysql://user:pass@localhost/db``