Qaack file¶

The Qaack config file (qaack.yml) is a YAML file that defines how the environments are built and managed for a repository.

If you decide to include the config as a file in your repository, it should be placed in the root of the repository, in the .qaack directory. Like this:

/.qaack/qaack.yml

Otherwise, you can provide it in the setup of your repository using the "panel" or "both" Qaack file mode, learn more about this in the User Guide.

You can specify services, variables, tests, quick actions, and more in the Qaackfile. Keep reading to learn more about the available configuration options.

Available configuration options¶

Aliases¶

aliases string : array

Defines additional domains for the environment to be publicly accessible.

Variables¶

variables string : string | dict

Defines environment variables, which can be specified in two ways:

Option 1: Key-Value Pairs¶

Add entries in the format key:value to make variables always visible.

variables:
  test_variable: value

Option 2: Value with Visibility¶

Specify both the variable value and visibility. Options for visibility include always and buildtime.

variables:
  test_variable:
    value: var_value
    visibility: buildtime

Reuse¶

reuse string

Specifies a reusable environment to use in the current context, the value is the label of the reusable environment.

reuse: [reusable_label]

Make Reusable¶

make_reusable dict

Allows you to create reusable environments with unique labels. Each reusable environment has:

[reusable_label]: A unique label for each reusable environment.
on: Specifies the build process step at which the environment is saved, in the format [service_name].[step_name]. Environment is saved AFTER the specified step, and reuse will NOT re-run this step.
where: Git references that restrict when the environment is saved. If the Git reference is not listed, the reusable environment will be ignored.

make_reusable:
  [reusable_label]:
    on: [service].[step]
    where:
      - [git_reference_name]

Quick Actions¶

quick_actions dict

Defines actions with unique keys. Each quick action includes:

command string: Command to execute within the service.
service string: Service name for the command (defaults to the main service if omitted).
output "string" | "file" | "none" (Default: string):
string: Displays command output in the interface.
file: Provides output as a downloadable file.
none: Discards output.
filename string: Filename for downloads (applies if file output mode is used).

quick_actions:
  get_file:
    command: cat my_file
  reinstall_packages:
    command: npm ci
    output: none
  dump_database:
    command: "mysqldump | gzip"
    output: file
    service: mariadb
    filename: dump.sql.gz

Services¶

services string : dict

Defines services that make up the environment.

Note: Service names must contain only letters and numbers.

Each service includes the following options:

image string: Docker image for the service.
checkout boolean: Indicates whether to place repository data into the service’s filesystem.
start string: Command to start the service.
port integer: Port to expose.
variables: Service-specific variables, formatted similarly to global variables.

services:
  web:
    image: qaack/nginx-php81
    checkout: true
  db:
    image: qaack/mariadb

Tests¶

tests dict

Specifies tests for the environment. Each test is named by a unique key and includes:

type string: Type of test, options are:
- screenshot: Captures a screenshot of the environment.
- lighthouse: Runs a Lighthouse audit on the environment.
- playwright: Runs a custom playwright test on the environment.
- visual-regression: Compares screenshots of a MR/PR environment with the source branch environment.
params dict: Parameters for the test, depends of kind of test.

Parameters for different tests

screenshot:
- paths []string: Paths to capture screenshots of. Default is /.
lighthouse:
- threshold integer: Lighthouse score threshold. Will be applied to all of the following scores: performance, accessibility, best-practices, seo.
playwright:
- dir string: Path to the playwright directory where the package.json file is located. Default is test/playwright.
visual-regression:
- paths []string: Paths to capture screenshots of and later compare. Default is /.
- threshold integer: Threshold for the visual regression test. Will be applied to all of the screenshots.

tests:
  screenshots:
    type: screenshot
    params:
      paths:
        - /
        - /about
        - /contact

  lighthouse:
    type: lighthouse
    params:
      threshold: 80

  playwright:
    type: playwright
    params:
      dir: tests/test001

  visual-regression:
    type: visual-regression
    params:
      paths:
        - /
        - /about
        - /contact  
      threshold: 99

Templating Available Variables¶

Qaack uses Go templating syntax for variables. For more details, see the Go templating documentation.

Qaack provides these template variables:

Variable Name	Description
`.Repository.Type`	Repository type
`.Repository.Name`	Repository name
`.Repository.ID`	Repository ID
`.Environment.ID`	Environment ID
`.Environment.Ref.Name`	Name of the Git reference
`.Environment.Ref.Type`	Type of Git reference (e.g., branch, tag)
`.Environment.Ref.Hash`	Hash of the Git reference
`.Environment.Ref.Number`	PR/MR number, if applicable
`.Environment.Ref.SourceBranch`	Source branch for PR/MR
`.Environment.Ref.TargetBranch`	Target branch for PR/MR

Template Functions¶

Retrieve custom variables and repository-specific parameters with these functions:

Function Name	Arguments
`Variable`	1: variable Name
`RepositoryParam`	1: parameter name

Repository Parameters¶

Parameters vary by repository type:

Parameter Name	Description
`GenericOrigin`
`GitlabProjectName`	GitLab project name
`GitlabProjectGroup`	GitLab project group
`GitlabProjectId`	GitLab project ID
`GitlabInstanceUrl`	URL of the GitLab instance
`GitlabProjectUrl`	URL of the GitLab project
`GitlabToken`	GitLab access token
`GitlabMergeRequestNumber`	GitLab merge request number
`GitlabMergeRequestTitle`	GitLab merge request title
`GitlabMergeRequestSourceBranch`	GitLab merge request source branch
`GitlabMergeRequestTargetBranch`	GitLab merge request target branch
`GithubProjectName`	GitHub project name
`GithubProjectOwner`	GitHub project owner
`GithubProjectUrl`	GitHub project URL

Example Files¶

make_reusable:
  reusable1:
    on: Y.b
    where:
      - develop
  full_site:
    on: Z.f
    where:
      - develop

reuse: full_site

variables:
  var1: value1
  var2:
    value: value2

quick_actions:
  get_file:
    command: cat my_file
  reinstall_packages:
    command: npm ci
    output: none
  dump_database:
    command: "mysqldump | gzip"
    output: file
    service: mariadb
    filename: dump.sql.gz

tests:
  home-screenshot:
    type: screenshot
  lighthouse:
    type: lighthouse

services:
  web:
    image: qaack/nginx-php81
    checkout: true
  db:
    image: qaack/mariadb

services:
  php1:
    image: qaack/nginx-php74

  {{ if eq .Repository.Type "gitlab" }}
  phpGitlab:
    image: qaack/nginx-php74
    commands:
      dummy:
        - echo ID {{ RepositoryParam "GitlabProjectId" }}
        - echo Group {{ RepositoryParam "GitlabProjectGroup" }}
  {{ end }}

  {{ if eq .Repository.Type "generic"}}
  phpGeneric:
    image: qaack/nginx-php74
    commands:
      info:
        - echo {{ .Environment.Ref.Type }}
        - echo {{ .Repository.Type }}
  {{ end }}