| |
@@ -571,166 +571,15 @@
|
| |
- 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
|
| |
==================
|
| |
Should this be removed from the index if we're keeping it as a separate file?