Skip to content

Latest commit

 

History

History
403 lines (324 loc) · 14.9 KB

configuring_project.md

File metadata and controls

403 lines (324 loc) · 14.9 KB
Raw

Project Build Configurations in PHP Censor

Configuration methods

For builds configuration PHP Censor uses description in YAML (Like in Travis CI).

There are several ways of configuring build in PHP Censor project:

  1. Adding a project without any config (The easiest way).

    In this case build launches with the default config, which includes dependency plugin (Composer), code static analysis plugin ( TechnicalDebt, PHPLoc, PHPCpd, PHPCodeSniffer, PHPMessDetector, PHPDocblockChecker, PHPParallelLint), and test plugins(PHPUnit, Codeception).

    Test plugins will launch if there are tests and configuration files by default paths.

    Default config will look like this:

        build_settings:
      ignore:
        - "vendor"
    setup:
      composer_step:
        plugin: composer
        action: "install"
    test:
      technical_debt_step:
        plugin: technical_debt
        allowed_errors: -1
      php_code_sniffer_step:
        plugin: php_code_sniffer
        allowed_warnings: -1
        allowed_errors: -1
      php_mess_detector_step:
        plugin: php_mess_detector
        allowed_warnings: -1
      php_docblock_checker_step:
        plugin: php_docblock_checker
        allowed_warnings: -1
      security_checker_step:
        plugin: security_checker
        allowed_warnings: -1
      php_parallel_lint_step:
        plugin: php_parallel_lint
        allow_failures: true
      php_loc_step:
        plugin: php_loc
      php_cpd_step:
        plugin: php_cpd
      codeception_step:
        plugin: codeception
      php_unit_step:
        plugin: php_unit

  2. Adding a config .php-censor.yml to the root of the project.

  3. Adding a config via web-interface.

    By default, a config from web-interface replaces a config from repository (.php-censor.yml). But if you uncheck the option "Replace the configuration from file with the configuration from the database", configurations will be merged (the config from web-interface will have priority over the config from the repository).

    Setting config via web-interface and merging it with the config from the repo may be useful if you want to hide some secret data (passwords, keys) in case of using public repository. The most of the configuration can be stored as a public file in the repo, and passwords and keys may be added via web-interface.

    NOTE: Config added via web-interface has the highest priority.

Config file format

Config example:

build_settings:
  clone_depth: 1 # only in web-interface
  priority_path: binary_path
  binary_path:   /home/user/bin/
  directory:     /home/project
  build_priority: 1 # only in web-interface
  ignore:
    - "vendor"
    - "tests"
  mysql:
    host: "localhost"
    user: "root"
    pass: ""

setup:
  mysql_step:
    plugin: mysql
    queries:
      - "DROP DATABASE IF EXISTS test;"
      - "CREATE DATABASE test;"
      - "GRANT ALL PRIVILEGES ON test.* TO test@'localhost' IDENTIFIED BY 'test';"
  composer_step:
    plugin: composer
    action: "install"

test:
  php_unit_step:
    plugin: php_unit
    config:
      - "PHPUnit-all.xml"
      - "PHPUnit-ubuntu-fix.xml"
    directory:
      - "tests/"
    run_from: "phpunit/"
    coverage: "tests/logs/coverage"
  php_mess_detector_step:
    plugin: php_mess_detector
    priority_path: binary_path
    binary_path:   /home/user/sbin/
    binary_name:   phpmd-local
  php_code_sniffer_step:
    plugin: php_code_sniffer
    standard: "PSR2"
  php_cpd_step:
    plugin: php_cpd
    allow_failures: true
  grunt_step:
    plugin: grunt
    task: "build"

deploy:
  deployer_step:
    plugin:      deployer
    webhook_url: "http://deployer.local/deploy/QZaF1bMIUqbMFTmKDmgytUuykRN0cjCgW9SooTnwkIGETAYhDTTYoR8C431t"
    reason:      "PHP Censor Build #%BUILD_ID% - %COMMIT_MESSAGE%"
    update_only: true

complete:
  mysql_step:
    plugin: mysql
    host:   "localhost"
    user:   "root"
    pass:   ""
    - "DROP DATABASE IF EXISTS test;"

branch-dev:
  run-option: replace
  test:
    grunt_step:
      plugin: grunt
      task: "build-dev"

Common build settings

Section build_settings contents common build settings:

  • Option verbose enable/disable verbosity of plugins output (Default value: verbose: true).

  • Option clone_depth: N allows cloning repository with partial history (Git clone option --depth=N). Option supports Git (GitHub, GitLab, BitBucket, Gogs) and Svn (Subversion) builds.

    ATTENTION!: Option clone_depth should be set only from web-interface (Project edit page) because it should be known before repository cloning. Also, you should understand that some features or plugins with the option may work with unpredictable result.

  • Option directory sets default directory path for all plugins (It may be overloaded by the plugin option directory).

  • Option ignore sets default ignore list for all plugins (It may be completed by the plugin option ignore). For example config returns ignore list: vendor, tests, docs:

    build_settings:
  ignore:
    - vendor
    - tests
...
test:
  example_step:
    plugin: example_plugin
    ignore:
      - ./vendor
      - ./docs

  • Option priority_path sets default searching binary priority path for all plugins (It may be overloaded by the plugin option priority_path).

  • Option binary_path sets default binary path for all plugins (It may be overloaded by the plugin option priority_path). For example: binary_path: /usr/local/bin.

  • Option prefer_symlink allows using symlinks as a source build path. The option works only for local build source (LocalBuild).

  • Option build_priority: N builds of a project with a higher value (like 1500) are handled after builds of projects with lower values (like 2). Default value is 1000. Allowed values range: [1, 2000].

    ATTENTION!: Option build_priority should be set only from web-interface (Project edit page) because it only has an effect before the repository is cloned.

  • Also, we have global options (Usually connection settings) for some plugins like: (Campfire, Irc, Mysql, Pgsql и Sqlite). See documentation of the plugins for more details.

  • Also, we have options for configuring connection parameters for Svn (Subversion) project source type. For example:

    build_settings:
  svn:
    username: "username"
    password: "password"

    ATTENTION!: Section svn should be set only from web-interface (Project edit page) because it should be known before repository cloning.

Build Stages

The build goes through some stages. During each stage some plugins can be executed.

  • setup - The stage of setting up the build (creating test database, setting dependencies, etc.).

  • test - The stage of testing. Runs after the setup stage if the setup was successful. In this stage all the main plugins and statistical code analyzers are executed.

    One plugin failing don't mean always failing of all stage. Option allow_failures (You may use it for all plugins) allow you to ignore failing of one plugin in the build/stage status (For example: allow_failures: true).

    Also you may limit quantity of allowed errors and warnings for one plugin. Use options allowed_errors and allowed_warnings for it (For example: allowed_warnings: 2). Value -1 means that it is unlimited quantity. This options don't available for all plugins, see details in plugins documentation.

    There is also a priority_path option available to all plugins. It allows you to change the search order of the plugin executable file. Possible option values are:

    • local - In the first place search in the build directory vendor/bin, then - in global, then - in system, then - in priority_path;

    • global - In the first place search in the directory vendor/bin PHP Censor, then - in local, then - in system, then - in priority_path;

    • system - In the first place search among the system utilities (/bin, /usr/bin etc., use which), then - in local, then - in global, then - in priority_path;

    • binary_path - First look for the specific path specified in the binary_path option, then - in local, then - in global, then - in system;

    The binary_path option allows you to set a specific path to the directory with the executable plugin file. There is also a binary_name option which allows to set an alternative name for the executable file (a string or an array of strings).

    Example:

    setup:
  composer_step:
    plugin: composer
    priority_path: binary_path
    binary_path: /home/user/bin/
    # Search will be by executable file name: composer-1.4, composer-local, composer, composer.phar
    binary_name:
      - composer-1.4
      - composer-local
    action: install

    Search order of the executable file by default: local -> global -> system -> binary_path.

  • deploy - The stage of the project deployment. Runs after the stage of testing, if the tests were successful. In this stage deployment plugins should be called (Shell, Deployer, Mage и etc.). This stage is very similar to test.

  • complete - Build completion stage. Always executes after the deploy (or after the test, in case deploy is missing), regardless of whether the build was successful or failed. In this stage it is possible to send notifications, to clear a database, etc.

  • success - Successful Build Stage. Called only when the build completed successfully.

  • failure - This stage is called only when the build failed.

  • fixed - Build recovery stage. Called only when the build completed successfully after a failed previous build.

  • broken - Build failure stage. Called only when the build failed after a successful previous build .

Some plugins have restrictions on the stages in which they can be launched. For example, plugins TechnicalDept, PHPLoc, PHPCpd, PHPCodeSniffer, PHPMessDetector, PHPDocblockChecker, PHPParallelLint, Codeception, PhpUnit can only be launched at test stage. The plugin Composer, can only be launched at setup stage.

Redefining configuration for the specific branches.

The directive branch-<branch-name> (For example: branch-feature-1 for the branch feature-1) allows to redefine or to complete the main build configuration for the specific branches.

There is also a directive branch-regex:<branch-name-regex> which allows to compare branches by regexp for the same purposes (For example: branch-regex:^feature\-\d$ for the branches: feature-1, feature-2 etc.).

If there are several directives branch-regex:/branch-, the first directive that matches up with the name of the branch will be used.

The required parameter run-option allows defining, to redefine and to complete the configuration and can take different values:

  • replace - will cause the branch specific plugins to run and the default ones not.

  • before - will cause the branch specific plugins to run before the default ones.

  • after - will cause the branch specific plugins to run after the default ones.

Configuration example:

test

...

branch-regex:^feature\-\d$:
  run-option: replace
  test:
    grunt_step:
      plugin: grunt
      task:   build-feature
branch-dev:
  run-option: replace
  test:
    grunt_step:
      plugin: grunt
      task:   build-dev
branch-codeception:
  run-option: after
  test:
    codeception_step:
      plugin: codeception

How it works

When you have configured a branch eg "stable" in the project settings in the UI. Add a new config named branch-<branch> (or use regular expression like: branch-regex:^stable*), in this case "branch-stable" to the .php-censor.yml. In this config, specify all stages and plugins you wish to run.

Also add a new config value run-option, that can have 3 values:

  • before - will cause the branch specific plugins to run before the default ones.
  • after - will cause the branch specific plugins to run after the default ones.
  • replace - will cause the branch specific plugins to run and the default ones not.

Useful YAML features

Some features of YAML could be very handy. Here is a demonstration of multi line strings, and of anchors and aliases. See more details on symfonys yaml document on in the specification.

setup:
    # yaml comment
    shell_step:
        plugin: shell
        commands:
            - |
                echo a long shell command, multiple lines
                scriptPath=%BUILD_PATH%/../../hook-path/prepare-test5.sh
                if [ -f $scriptPath ]
                then
                    "$scriptPath" '%PROJECT_ID%' '%PROJECT_TITLE%' # script can read its path from $scriptPath
                    mkdir ../outputs_to_keep/%COMMIT_ID%
                fi
            - >
                echo this is a very long message I must write here, and it is much too long to allow good editing
                on only one line, therefore we break it up onto multiple lines, but the result will be on a single
                line.
            - echo a short command ...

branch-master:
    complete: &xmpp_notify
        xmpp_notify_step:
            plugin: xmpp_notify
            username: &userName "login@gmail.com"
            password: &password "AZERTY123"
            recipients:
                - "builds-infos@jabber.org"
            server: &xmppServer "gtalk.google.com"
            alias: "build infos for project"
            date_format: "%d/%m/%Y"
    broken:
        xmpp_notify_step:
            plugin: xmpp_notify
            username: *userName
            password: *password
            recipients:
                - "build-alters-infos@jabber.org"
            server: *xmppServer
branch-bugfix1.9:
    complete: *xmpp_notify
branch-bugfix2.0:
    complete: *xmpp_notify