1. Documentation
  2. Integrations
  3. Continuous Integration Providers
  4. CircleCI

CircleCI

CircleCI is a continuous integration platform that integrates with GitHub, Bitbucket, AWS, and many more services.

If you want to run your PHPUnit tests or your Blackfire Player scenarios on CircleCI, read on to learn more about how to configure it.

Configuring the Project

To set up Blackfire on CircleCI, you need to define some environment variables in the build settings of your project.

Define environment variables for your Client credentials:

or to display your Blackfire's credentials.

Define environment variables for the Server credentials. Choose the credentials you want to use:

or to display your Blackfire's credentials.

Using the Blackfire Orbs

To ease the integration with your CircleCI workflows, Blackfire provides several orbs in the CircleCI Orb Registry:

To use the Blackfire orbs, you need to allow the use 3rd party orbs; this must be done on the Settings > Security page for your organization.

Note

This operation needs to be done by an administrator of your CircleCI organization.

Here is a configuration snippet using the Blackfire orb for PHP:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
version: 2.1

orbs:
    blackfire: blackfireio/php@1.1

jobs:
    build:
        docker:
            # You may use another Docker image.
            - image: circleci/php:7.4-fpm-node

        steps:
            - checkout

            - blackfire/setup

            - run:
                name: Tests
                environment:
                    APP_DEBUG: 0
                command: php bin/phpunit

Running Blackfire from CircleCI builds requires importing the blackfireio/php orb and running the setup command, right after the code checkout. The command will install the probe, the agent, and the player.

Note

Using orbs requires using version 2.1 of the CircleCI DSL. If your project was added to CircleCI before 2.1, you must enable “pipelines” in Your Project > Settings > Advanced Settings.

Note

The snippet above works with any Docker image provided by CircleCI as they are based on official PHP Debian images.

It also works when using the “machine” executor.

Triggering a Blackfire Build Requires Enterprise

A command is available in the Agent orb for triggering a Blackfire build:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
version: 2.1

orbs:
    blackfire: blackfireio/php@1.1
    blackfire-agent: blackfireio/agent@1.2

jobs:
    blackfire-build-example:
        docker:
            - image: circleci/php:7.4-fpm-node
        steps:
            - checkout
            - blackfire/setup
            - blackfire-agent/build-trigger:
                endpoint: "https://staging.my-webapp.tld/"
                # Blackfire Environment name or UUID
                # Can be only a part of the environment name, as long as it is not ambiguous.
                environment: My Blackfire Environment Name

Running Blackfire Player scenarios Requires Premium/Enterprise

The run-scenario command from the Player orb lets you run a specified scenario. Running a scenario is represented by a build in your Blackfire dashboard.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
version: 2.1

orbs:
    blackfire: blackfireio/php@1.1
    blackfire-player: blackfireio/player@1.0

blackfire_player:
    docker:
        - image: circleci/php:7.4-fpm-node
    steps:
        - checkout
        - blackfire/setup
        - blackfire-player/run-scenario:
              # Assuming scenario.bkf is at the root of your codebase.
              scenario: scenario.bkf
              # Can be only a part of the environment name, as long as it is not ambiguous.
              environment-name: MyEnvironmentName
              endpoint: "https://myendpoint.tld"
              variables: "variable_name1=value1,variable_name2=value2,foo=bar"

Note

To run multiple scenarios, make sure to use the load instruction in your BKF file.

You may also run your scenarios, directly from your CircleCI job with the help of Symfony local web server:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
version: 2.1

orbs:
    blackfire: blackfireio/php@1.1
    blackfire-player: blackfireio/player@1.0

blackfire_player:
    docker:
        - image: circleci/php:7.4-fpm-node
    steps:
        - checkout
        - run: composer install -n --prefer-dist
        - run:
              name: "Install & run Symfony server"
              environment:
                  # Ensure to run in "prod" Symfony environment
                  APP_ENV: prod
              command: |
                  wget https://get.symfony.com/cli/installer -O - | bash
                  ~/.symfony/bin/symfony local:server:start -d
                  # Now the server is listening to localhost:8000
        - blackfire/setup
        - blackfire-player/run-scenario:
              # Assuming scenario.bkf is at the root of the codebase.
              scenario: scenario.bkf
              # Can be only a part of the environment name, as long as it is not ambiguous.
              environment-name: MyEnvironmentName
              endpoint: "https://localhost:8000"
              variables: "variable_name1=value1,variable_name2=value2,foo=bar"