Notify your builder-ci to care of a build¶

Building any project requires to send a POST with more or less information about the project you wish to build. There are several method to trigger a build:

• Use git hooks (preferred)
• Use curl
• Use postman or similar

Using git hooks¶

Git hooks is the best way to notify your builder that a new change in your source code is required to be build. Two examples are provided into /usr/share/doc/builder-ci/helpers/ folders.

• git-core.py : this is an example when using with a git bare folder. It fits perfectly when you use Redmine with Git. Copy and adapt this file into /.git/hooks/post-receive (don't forget to add execution bit with chmod +x <git bare>/.git/hooks/post-receive).
• gitolite_hooks.py : use this file if you use gitolite. Copy and adapt this file into //local/hooks/common/post-receive.d

In all case, you will have to adapt in order to configure builder_url and git_url which is base git url.

Using curl¶

You can use curl with the similar format

json='{
  "project": "builder-ci",
  "sources": {
    "method": "git",
    "options": {
      "url": "https://github.com/iabsis/builder-ci",
      "branch": "master"
    }
  },
  "builder": {
    "method": "docker",
    "options": {
      "image": "builder-bullseye"
    }
  },
  "notify": {
    "method": "redmine"
  }
}'

And trigger your build with

curl -X 'POST' \
  'http://localhost:5000/build' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d ${json}

Of course change localhost if you put your builder onto an IP address or domain name.

Using postman¶

Simply send a POST of the following json to http://<ip of your server>:5000/build

{
  "project": "builder-ci",
  "sources": {
    "method": "git",
    "options": {
      "url": "https://github.com/iabsis/builder-ci",
      "branch": "master"
    }
  },
  "builder": {
    "method": "docker",
    "options": {
      "image": "builder-bullseye"
    }
  },
  "notify": {
    "method": "redmine"
  }
}

Steps and Methods¶

Before understand the Json format, you have to know that Builder-CI will run step into this following order:

1. sources (mandatory): provide methods to fetch source code. The supported method is only git for now, but can be extended in the future.
2. patcher (optional): provide methods to alter the source code. There is no supported option for now, but patching will be extended in the future.
3. builder (mandatory): provide methods to builder your source code. Methods available are docker, pbuilder and rpmbuild.
4. publish (mandatory): provide methods to publish your artifacts resulting of your build. Methods available are createrepo, local-folder, redmine and apt-ftparchive.

At each step, the following additional step is executed:

1. notify (optional): provide methods to update the build status. Method available is only redmine, but can be extended in the future.

Json format¶

The json format to be send is the following:

{
  "project": "<project name>",
  "<step>": {
    "method": "<method>",
    "options": {
      "<option 1>": "<value 1>",
      "<option 2>": "<value 2>"
    }
  },
  "<step>": {
    "method": "<method>",
    "options": {
      "<option 1>": "<value 1>"
    }
  },
  ...
}

By example:

{
  "project": "builder-ci",
  "sources": {
    "method": "git",
    "options": {
      "url": "https://projects.iabsis.com/git/builder-ci",
      "branch": "master"
    }
  },
  "builder": {
    "method": "docker",
    "options": {
      "image": "builder-bullseye"
    }
  }
}

Means:

1. git method is called at step sources. Gets sources code on https://projects.iabsis.com/git/builder-ci and branch master.
2. not method called at optional step patcher, this step will not be run.
3. docker method called at step builder. Use image builder-bullseye to make the build.
4. not method defined for mandatory step publish, auto method will be defined instead.
5. not method defined for optional step notify, this step will not be run.

You can get an generated json file with all method and options available here : https://projects.iabsis.com/projects/builder-ci/files

Yaml format¶

In case of you wish to let the project itself configure how it should be built, you can add a file called builder.yml in root of your source code project. This file can contain more or less the same data than the json, excepted step "sources" and attribute "project".

By example

builder:
- method: docker
  options:
    image: builder-centos8
    env:
      SPEC_PATH: redhat/builder.spec
publish:
- method: redmine
  options:
    file: builder.rpm

Fallback options into builder.conf¶

If you don't want to exposed sensitive data, you can configure fallback options into file /etc/builder-ci/builder-ci.conf. If an option is requires by a method (e.g. api key for redmine publish method), this options can be picked from the configuration file.

[redmine]

url = http://<redmine url>/
key = abcd1234efgh

Methods and Options overriding order¶

In case of you define the same option into yml + json POST + configuration file, the options will be picked in this order:

1. Attempt to get methods and options from YML
2. If no methods in YML, attempt to get methods and options from json POST
3. If no methods defined in both YML or json POST, try to guess automatically the methods
4. If option requested by method is missing from both YML or json POST, try to get value into config file.

About meta¶

Meta are pair of key/value fetched by various methods during build. By example git method will return commit_id which will be then used by redmine notify method. Main different between options and meta is meta is available globally while options is specific for the method currently ran.