Qaackfile 
=========

.. _qaackfile:

Qaackfile available options
---------------------------

Aliases
^^^^^^^

  .. _qaackfile-aliases:

  **aliases** *string : array*

  This defines extra domains for the environment to be public accessed.


Variables
^^^^^^^^^

  **variables** *string : string | dict*
  
  This defines variables. You can specify variables in two ways.
  
  The first one:
    
    You simply add a entry like *key:value*. For example:
  
    In this way, variables visibility will be **always**
    
    .. code-block:: yaml
    
      variables:
        test_variable: value
      
  
      
  The second one: 
    
    You specify the value but also visibility:
    
    **value** *string*
    
    The value of the variable
    
    **visibility** *string (optional)*
    
    Available visibility are *always* and *buildtime*
  
    .. code-block:: yaml
    
      variables:
        test_variable:
          value: var_value
          visibility: buildtime

Reuse
^^^^^

  .. _qaackfile-reuse:

  **reuse** *string*

  The reusable environment to use


Make reusable
^^^^^^^^^^^^^

  .. _qaackfile-make_reusable:

  **make_reusable** *dict*

    **[reusable_label]**: you can create multiple reusable environments from the same environment. Each one will be identified by a label, which is specified here.

        **on**: This option specifies in which point of the build process will the environment be saved. Its given in the format of ``[service_name].[step_name]``.  **It will save AFTER the execution of the given step, and the environment reusing will NOT execute it**

        **where**: This is a list of git references to restrict when the environments will be saved. This is useful to avoid that all branches saves a environment. If the ref of the environment is not here, this reusable environment will be ignored.


Example:

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





Quick Actions
^^^^^^^^^^^^^

  .. _qaackfile-quickactions:

  **quick_actions** *dict*

  Each quick action has a name, which the key of the dictionary, and the following options:

    **command** *string*

    Command to run inside the service.

    **service** *string*

    Service name to run the command, if not present the default service will be used.

    **output** *"string" | "file" | "none"*

    Default is *string*

    Kind of output, each one does:
        - ``string``: the command output will be showed in the interface.
        - ``file``: the output will be a downloadable file.
        - ``none``: the output is discarded.

    **filename** *string*
    
    Name of the file to download. (Only applies if ``file`` output mode used).

Services
^^^^^^^^

  .. _qaackfile-services:

  **services** *string : dict*

  This indicates the service that will compose the environment.
 
  .. important:: 

    **Service name can only contain letters and numbers.**


  Its a dictionary where the key is the name of the service and the value is a dictionary describing the service. 

  Each service has the following options:

    **image** *string*

    This is the Docker image that will run this service.

    .. _qaackfile-services-checkout:

    **checkout** *boolean*

    If place the data of the repository into the service filesystem
	
    **start** *string*
	
    Start command for the service.

    **port** *integer*

    Port to expose    
    
    **variables** *same as global variable config*
    
    Variables per service

    
Tests
^^^^^

  .. _qaackfile-tests:

  **tests** *dict*

  This indicates the tests that will be run for the environment.

  Each test has a name, which the key of the dictionary, and the following options:

    **type** *string*

    Type of test, available types are *screenshot* and *lighthouse*.

-------

Templating available variables
------------------------------

.. _qaackfile-templating:

The templating syntax used is the Golang one, check this `link <https://pkg.go.dev/text/template#pkg-overview>`_ for more information.

Qaack provides the following variables:

.. list-table:: Template variables
   :widths: 40 60
   :header-rows: 1

   * - Variable name
     - Description
   
   * - .Repository.Type
     - 

   * - .Repository.Name
     -

   * - .Repository.ID
     -

   * - .Environment.ID
     - 

   * - .Environment.Ref.Name
     - 

   * - .Environment.Ref.Type
     -

   * - .Environment.Ref.Hash
     -

   * - .Environment.Ref.Number
     - If the ref is a pull request or merge request, this will be the number of the request

   * - .Environment.Ref.SourceBranch
     - If the ref is a pull request or merge request, this will be the source branch of the request

   * - .Environment.Ref.TargetBranch
     - If the ref is a pull request or merge request, this will be the target branch of the request

In addition, you can call these functions to get :ref:`custom variables<custom-variables>` and repository specific parameters:

.. list-table:: Template functions
   :widths: 40 60
   :header-rows: 1

   * - Function name
     - Arguments

   * - Variable
     - 1: variable Name

   * - RepositoryParam
     - 1: parameter name, see table below

The following parameters are available depending on the repository type:

.. list-table:: Repository parameters
   :widths: 40 60
   :header-rows: 1

   * - Parameter name
     - Description

   * - GenericOrigin
     -

   * - GitlabProjectName
     - 

   * - GitlabProjectGroup
     - 

   * - GitlabProjectId
     - 
  
   * - GitlabInstanceUrl
     - 
   * - GitlabProjectUrl
     - 
   * - GitlabToken
     - 
   * - GitlabMergeRequestNumber
     - 
   * - GitlabMergeRequestTitle
     - 
   * - GitlabMergeRequestSourceBranch
     - 
   * - GitlabMergeRequestTargetBranch
     - 


   * - GithubRrojectName
     - 
   * - GithubProjectOwner
     - 
   * - GithubProjectUrl
     - 
   * - GithubToken
     - 
   * - GithubPullRequestNumber
     - 
   * - GithubPullRequestTitle
     - 
   * - GithubPullRequestSourceBranch
     - 
   * - GithubPullRequestTargetBranch
     - 

   * - BitbucketWorkspace
     - 
   * - BitbucketPepo
     - 
   * - BitbucketPrNumber
     - 
   * - BitbucketPrSourceBranch
     - 
   * - BitbucketPrTargetBranch
     - 
  
-----

Example files
------------

.. code-block:: yaml

    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

.. code-block:: yaml

    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 }}




----