Tomas Kopecek
parent
3c4377e8e2
commit
64566ca172
3 changed files with 21 additions and 178 deletions
|
|
@ -571,166 +571,15 @@ them are:
|
|||
- test-rpm: like rpm, but append the Release field with a date and time
|
||||
stamp for easy upgrade-deployment
|
||||
|
||||
Plugins
|
||||
=======
|
||||
Writing Koji plugins
|
||||
====================
|
||||
|
||||
This section is copied from the ``docs/Writing_a_plugin.md`` file.
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
Koji supports different types of plugins, three of which are captured
|
||||
here. Depending on what you are trying to do, there are different ways
|
||||
to write a Koji plugin.
|
||||
writing_a_plugin
|
||||
|
||||
Koji Builder Plugins
|
||||
--------------------
|
||||
|
||||
Koji can do several things, for example build RPMs, or live CDs. Those
|
||||
are types of tasks which Koji knows about. If you need to do something
|
||||
which Koji does not know yet how to do, you could create a Koji Builder
|
||||
plugin. Such a plugin would minimally look like this:
|
||||
|
||||
::
|
||||
|
||||
from koji.tasks import BaseTaskHandler
|
||||
|
||||
class MyTask(BaseTaskHandler):
|
||||
Methods = ['mytask']
|
||||
_taskWeight = 2.0
|
||||
|
||||
def handler(self, arg1, arg2, kwarg1=None):
|
||||
self.logger.debug("Running my task...")
|
||||
# Here is where you actually do something
|
||||
|
||||
A few explanations on what goes on here:
|
||||
|
||||
- Your task needs to inherit from \`koji.tasks.BaseTaskHandler\`
|
||||
- Your task must have a \`Methods\` attribute, which is a list of the
|
||||
method names your task can handle.
|
||||
- You can specify the weight of your task with the \`\_taskWeight\`
|
||||
attribute. The more intensive (CPU, IO, ...) your task is, the higher
|
||||
this number should be.
|
||||
- The task object has a ``logger`` attribute, which is a Python logger
|
||||
with the usual \`debug\`, \`info\`, \`warning\` and \`error\`
|
||||
methods. The messages you send with it will end up in the Koji
|
||||
Builder log.
|
||||
- Your task must have a \`handler()\` method. That is the method Koji
|
||||
will call to run your task. It is the method that should actually do
|
||||
what you need. It can have as many positional and named arguments as
|
||||
you want.
|
||||
|
||||
Save your plugin as e.g ``mytask.py``, then install it in the Koji
|
||||
Builder plugins folder: ``/usr/lib/koji-builder-plugins/``. Finally,
|
||||
edit the Koji Builder config file, ``/etc/kojid/kojid.conf``:
|
||||
|
||||
::
|
||||
|
||||
# A space-separated list of plugins to enable
|
||||
plugins = mytask
|
||||
|
||||
Restart the Koji Builder service, and your plugin will be enabled. You
|
||||
can try running a task from your new task type with the command-line:
|
||||
``$ koji make-task mytask arg1 arg2 kwarg1``
|
||||
|
||||
Hub Plugins
|
||||
-----------
|
||||
|
||||
Koji clients talk to the Koji Hub via an XMLRPC API. It is sometimes
|
||||
desirable to add to that API, so that clients can request things Koji
|
||||
does not expose right now. Such a plugin would minimally look like this:
|
||||
|
||||
::
|
||||
|
||||
def mymethod(arg1, arg2, kwarg1=None):
|
||||
# Here is where you actually do something
|
||||
mymethod.exported = True
|
||||
|
||||
What's happening?
|
||||
|
||||
- Your plugin is just a method, with whatever positional and/or named
|
||||
arguments you need.
|
||||
- You must export your method by setting its ``exported`` attribute to
|
||||
``True``
|
||||
- The ``context.session.assertPerm()`` is how you ensure that the
|
||||
correct permissions are available.
|
||||
|
||||
Save your plugin as e.g \`mymethod.py\`, then install it in the Koji Hub
|
||||
plugins folder, which is ``/usr/lib/koji-hub-plugins/``
|
||||
|
||||
Finally, edit the Koji Hub config file, ``/etc/koji-hub/hub.conf``:
|
||||
|
||||
::
|
||||
|
||||
# A space-separated list of plugins to enable
|
||||
Plugins = mymethod
|
||||
|
||||
Restart the Koji Hub service, and your plugin will be enabled. You can
|
||||
try calling the new XMLRPC API with the Python client library:
|
||||
|
||||
::
|
||||
|
||||
>>> import koji
|
||||
>>> session = koji.ClientSession("http://koji/example.org/kojihub")
|
||||
>>> session.mymethod(arg1, arg2, kwarg1='some value')
|
||||
|
||||
If you want your new XMLRPC API to require specific permissions from the
|
||||
user, all you need to do is add the following to your method:
|
||||
|
||||
::
|
||||
|
||||
from koji.context import context
|
||||
|
||||
def mymethod(arg1, arg2, kwarg1=None):
|
||||
context.session.assertPerm("admin")
|
||||
# Here is where you actually do something
|
||||
mymethod.exported = True
|
||||
|
||||
In the example above, Koji will ensure that the user is an
|
||||
administrator. You could of course create your own permission, and check
|
||||
for that.
|
||||
|
||||
Event Plugin
|
||||
------------
|
||||
|
||||
You might want to run something automatically when something else
|
||||
happens in Koji. A typical example is to automatically sign a package
|
||||
right after a build finished. Another would be to send a notification to
|
||||
a message bus after any kind of event.
|
||||
|
||||
This can be achieved with a plugin too, which would look minimally as
|
||||
follows:
|
||||
|
||||
::
|
||||
|
||||
from koji.plugin import callback
|
||||
|
||||
@callback('preTag', 'postTag')
|
||||
def mycallback(cbtype, tag, build, user, force=False):
|
||||
# Here is where you actually do something
|
||||
|
||||
So what is this doing?
|
||||
|
||||
- The ``@callback`` decorator allows you to declare which events should
|
||||
trigger your function. You can pass as many as you want. For a list
|
||||
of supported events, see ``koji/plugins.py``.
|
||||
- The arguments of the function depend on the event you subscribed to.
|
||||
As a result, you need to know how it will be called by Koji. You
|
||||
probably should use ``*kwargs`` to be safe. You can see how callbacks
|
||||
are called in the ``hub/kojihub.py`` file, search for calls of the
|
||||
``run_callbacks`` function.
|
||||
|
||||
Save your plugin as e.g ``mycallback.py``, then install it in the Koji
|
||||
Hub plugins folder: ``/usr/lib/koji-hub-plugins``
|
||||
|
||||
Finally, edit the Koji Hub config file, ``/etc/koji-hub/hub.conf``:
|
||||
|
||||
::
|
||||
|
||||
# A space-separated list of plugins to enable
|
||||
Plugins = mycallback
|
||||
|
||||
Restart the Koji Hub service, and your plugin will be enabled. You can
|
||||
try triggering your callback plugin with the command-line. For example,
|
||||
if you registered a callback for the ``postTag`` event, try tagging a
|
||||
build: ``$ koji tag-build mytag mypkg-1.0-1``
|
||||
There is a separate documentation page :doc:`writing_a_plugin`.
|
||||
|
||||
Submitting Changes
|
||||
==================
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue