Branch & Hash Specific Options

By: Michael R. Bagnall

Last Updated: June 6, 2026

You can specify branch control over Assets or Build Steps.

Sometimes you will need to use a different database depending on the branch of code or take a special set of actions. An example of this would be the need to run additional steps for a feature branch or, more likely, your develop or staging branches. Probo.CI allows you to do this with special configurations and environment variables that you can use to operate different options for different reasons.

Using Branch-Specific Assets

Using Environment Variables, you can specify assets for specific purposes. In this case, a database specific to a branch of code. This requires some asset and database specific logic in your .probo.yaml file as well as a bit of ordering of assets.

The Default Asset

You will want to specify a default asset. This is an asset that will always be available to other build spaces. It will serve as a default asset when references to other assets are not found. In our example we’re going to discuss database assets and setting up a branch-specific database yet still have a default database available to other branches. This minimizes the amount of .probo.yaml file maintenance that is necessary when trying to accomplish this manually.

The $BRANCH_NAME_ESCAPED Environment Variable Each build contains environment variables that can be accessed during the build process. One of these is $BRANCH_NAME_ESCAPED. This contains the name of the branch with slashes (/) escaped to being dashes (-). This means you can specify a branch name as a database file using a standard file naming convention.

If your branch name is feature/TN-321-update-drupal then $BRANCH_NAME_ESCAPED will evaluate to feature-TN-321-update-drupal. You can refer to this filename synonymously in your assets directive:

assets:
  - feature-TN-321-update-drupal.tar.gz

This same name can be specified in the database directive used in LAMP, Drupal, WordPress and other plugins that utilize an asset driven database. If the filename does not exist, Probo.CI will check for a default asset file. As a matter of course, the first asset in the list of assets is considered the default asset. So if you wanted to have a default database that was present if ${BRANCH_NAME_ESCAPED} did not match a valid asset, it would use the first asset in the list of assets.

assets:
  - default-database.tar.gz
  - feature-TN-321-update-drupal.tar.gz
  - feature-branch-does-not-exist.tar.gz

In this example, if the branch specific database is not found, then the first one (default-database.tar.gz) will be used where ${BRANCH_NAME_ESCAPED} is referenced (regardless of file extension).

Full Example

assets:
  - default-database.tar.gz
  - feature-TN-321-update-drupal.tar.gz

steps:
  - name: Probo site setup
    plugin: LAMPApp
    database: ${BRANCH_NAME_ESCAPED}.tar.gz
    databaseGzipped: true
    mysqlCnfOptions:
      key_buffer_size: 16M
      max_allowed_packet: 128M

In our example above, when on branch feature/TN-321-update-drupal, it will use the asset with that name in the database step. Note that we had to add the .tar.gz as Probo.CI will not add the file extension. This means that your .probo.yaml file may contain assets not used in the build. You should delete any unused assets as part of a Probo.CI step to make sure they do not clutter up your builds and take up unnecessary disc quota space.

If you used this same configuration in another branch, the database directive would default to the first asset in the list, in this case default-database.tar.gz. You need to make sure for this use case, that your default asset is a database file and not a different form of asset.

Branch Specific Steps

You can also control which branches a step runs on. Instead of a single branch directive, Probo.CI now uses two keys that you can add to any step:

Each key accepts a single branch name or a list of names. A step with neither key always runs, preserving the default behavior. When both keys are present on the same step, skipBranches takes precedence.

For example, if you wanted to run a Script plugin set of commands only on the aforementioned feature/TN-321-update-drupal branch, you could do so via the following:

steps:
  - name: Run Cache Clear On Our Feature Branch
    branches: feature/TN-321-update-drupal
    plugin: Script
    script:
      - drush cr -y

Wildcards

A * acts as a wildcard that matches any run of characters, which is handy for matching a whole family of branches. Matching is performed against the full branch name.

steps:
  # Only runs on release branches.
  - name: Tag Release Build
    plugin: Script
    branches:
      - 'release/*'
    script:
      - ./tag-release.sh

  # Runs everywhere except release and hotfix branches.
  - name: Seed Demo Content
    plugin: Script
    skipBranches:
      - 'release/*'
      - 'hotfix/*'
    script:
      - drush en demo_content -y

Builds started from a specific commit or hash may not carry branch context. When no branch is known, restricted steps are run rather than skipped, so a step is never silently dropped when Probo.CI cannot determine the branch.

These keys can be specified for any plugin in the Probo.CI configuration. For the full reference, see Restricting Build Steps by Branch.

Related Articles & Information

---

Environment Setup Environment Variables & Secrets