Builder CI

# 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 bare>/.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 /<gitolite-path>/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

~~~ bash

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 

~~~ bash

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`

~~~ 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"

  }

}

~~~

# 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.

1. **patcher (optional)**: provide methods to alter the source code. There is no supported option for now, but patching will be extended in the future.

1. **builder (mandatory)**: provide methods to builder your source code. Methods available are docker, pbuilder and rpmbuild.

1. **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:

~~~ json

{

  "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:

~~~ json

{

  "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.

~~~ conf

[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.