GitLab CI template for Bruno

This project implements a GitLab CI/CD template to run your automated API tests with Bruno.

Usage

This template can be used both as a CI/CD component or using the legacy include:project syntax.

Use as a CI/CD component

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the component
  - component: $CI_SERVER_FQDN/to-be-continuous/bruno/gitlab-ci-bruno@1.11.0
    # 2: set/override component inputs
    inputs:
      review-enabled: true # ⚠ this is only an example

Use as a CI/CD template (legacy)

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the template
  - project: 'to-be-continuous/bruno'
    ref: '1.11.0'
    file: '/templates/gitlab-ci-bruno.yml'

variables:
  # 2: set/override template variables
  REVIEW_ENABLED: "true" # ⚠ this is only an example

bruno job

This job starts Bruno (functional) tests.

It uses the following variable:

Input / Variable	Description	Default value
image / BRU_IMAGE	The Docker image used to run the Bruno CLI.	docker.io/library/node:lts-alpine
version / BRU_VERSION	The version of Bruno to use (leave empty to use latest)	none
collections / BRU_COLLECTIONS	The matcher to select Bruno collection directory(ies) to run.	bruno
base-url / BRU_BASE_URL	Explicit base url environment to test. Auto-evaluated by default (see below chapter).	none (auto-evaluated)
extra-args / BRU_EXTRA_ARGS	Bruno extra run options	none
review-enabled / REVIEW_ENABLED	Set to true to enable Bruno tests on review environments (dynamic environments instantiated on development branches)	none (disabled)

In addition to a textual report in the console, this job produces the following reports, kept for one day:

Report	Format	Usage
reports/bruno-*.xunit.xml	junit test report(s)	GitLab integration

base url auto evaluation

By default, the Bruno template tries to auto-evaluate a {{base_url}} variable (i.e. the variable pointing at server under test) by looking either for a $environment_url variable or for an environment_url.txt file.

Therefore if an upstream job in the pipeline deployed your code to a server and propagated the deployed server url, either through a dotenv variable $environment_url or through a basic environment_url.txt file, then the Bruno test will automatically be run on this server.

all our deployment templates implement this design. Therefore even purely dynamic environments (such as review environments) will automatically be propagated to your Bruno tests.

Hook scripts

The Bruno template supports optional hook scripts from your project, located in the root directory to perform additional project-specific logic:

• pre-bruno.sh is executed before running Bruno,
• post-bruno.sh is executed after running Bruno (whichever the tests status).

Variants

The Bruno template can be used in conjunction with template variants to cover specific cases.

Vault variant

This variant allows delegating your secrets management to a Vault server.

Configuration

In order to be able to communicate with the Vault server, the variant requires the additional configuration parameters:

Input / Variable	Description	Default value
TBC_VAULT_IMAGE	The Vault Secrets Provider image to use (can be overridden)	registry.gitlab.com/to-be-continuous/tools/vault-secrets-provider:latest
vault-base-url / VAULT_BASE_URL	The Vault server base API url	must be defined
vault-oidc-aud / VAULT_OIDC_AUD	The aud claim for the JWT	$CI_SERVER_URL
VAULT_ROLE_ID	The AppRole RoleID	none
VAULT_SECRET_ID	The AppRole SecretID	none

By default, the variant will authentifacte using a JWT ID token. To use AppRole instead the VAULT_ROLE_ID and VAULT_SECRET_ID should be defined as secret project variables.

Usage

Then you may retrieve any of your secret(s) from Vault using the following syntax:

@url@http://vault-secrets-provider/api/secrets/{secret_path}?field={field}

With:

Parameter	Description
secret_path (path parameter)	this is your secret location in the Vault server
field (query parameter)	parameter to access a single basic field from the secret JSON payload

Example

include:
  # main template
  - component: $CI_SERVER_FQDN/to-be-continuous/bruno/gitlab-ci-bruno@1.11.0
  # Vault variant
  - component: $CI_SERVER_FQDN/to-be-continuous/bruno/gitlab-ci-bruno-vault@1.11.0
    inputs:
      # audience claim for JWT
      vault-oidc-aud: "https://vault.acme.host"
      vault-base-url: "https://vault.acme.host/v1"

variables:
  # Secrets managed by Vault
  MY_APP_TESTING_USER: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/testing/snapshot/credentials?field=user"
  MY_APP_TESTING_PASSWORD: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/testing/snapshot/credentials?field=password"