Configuring the GitLab CI/CD pipeline

Before you begin

Perform the following procedures:

• Preparing-for-configuration
• Creating-a-configuration-file

To create a new pipeline

1. On the GitLab Project dashboard, click Code to expand it.
2. From the list, select Repository.
3. In the root directory of the project or branch repository, select Add > New file.

4. In the Filename field, enter .gitlab-ci.yml.

   Important

   You must enter this name because it is a CI/CD pipeline.

5. Copy the following example pipeline syntax and paste into the .gitlab-ci.yml file.

   # Variable declaration for the Pipeline
   variables:
    PIPELINE_NAME: "pipeline-sql-assurance-static-sql"                     # pipeline name
    CONFIG_FILE: "Config_SQL_Assurance_Static_SQL.yml"                     # config file name
   
   image:attach:xwiki:Mainframe.Data-for-Db2.BMC-AMI-SQL-Assurance-for-Db2.COB13100.Using.Using-BMC-AMI-SQL-Assurance-with-Universal-Connector.Configuring-the-GitLab-pipeline.WebHome@filename <Image location>/sqlassuranceuc:13.01.00.0005-GA                  # image name
   
   stages:
    - static_sql                                                           # stage name
   
   build-job:                                                               # job name
    stage: static_sql
   
     # Perform various initialization functions using Linux based command sed
    before_script:
       # Use the config file name variable
      - echo "Replace variables defined in $CONFIG_FILE file"
       # Linux command sed is used to replace the config file variables with GitLab CI/CD variables
      - sed -i "s/USER_ID_AUTH/$user_id/" $CONFIG_FILE
      - sed -i "s/USER_PASS_AUTH/$user_pass/" $CONFIG_FILE
   
       # For certBased Authentication, uncomment the following 2 sed commands
       # - sed -i "s/CERT_PATH_AUTH/$cert_path/" $CONFIG_FILE
       # - sed -i "s/CERT_PASS_AUTH/$cert_pass/" $CONFIG_FILE
   
       # Use the pipeline name variable
      - sed -i "s/PIPELINENAME_VALUE/$PIPELINE_NAME/" $CONFIG_FILE
       # Use GitLab CI/CD environment variables to fetch pipeline id, run by and pipeline source of the executing pipeline
      - sed -i "s/RUNNUMBER_VALUE/$CI_PIPELINE_ID/" $CONFIG_FILE
      - sed -i "s/RUNBY_VALUE/$GITLAB_USER_LOGIN/" $CONFIG_FILE
      - sed -i "s/RUNMODE_VALUE/$CI_PIPELINE_SOURCE/" $CONFIG_FILE
      - echo "-   $CONFIG_FILE.yml file is updated -"
   
    script:
       # Execute application step - authentication
      - step authentication $CONFIG_FILE
   
       # Execute application step - analyzeStaticSql (static_sql_package)
      - step static_sql_package $CONFIG_FILE
   
    tags:
      - <runner tag name>                                          # runner tag name

6. Click Commit changes to save the pipeline.

   Important

   The pipeline runs automatically when the changes are committed unless you type [skip ci] in the Commit message field.

    

To upload an existing pipeline:

1. On the GitLab Project dashboard, select Code > Repository.
2. In the root directory of the repository, either in main or branch, select Add  > Upload file.
3. On the Upload new file page, drag or click the upload link to select the pipeline file, .gitlab-ci.yml.
4. Keep the default commit message or enter a message of your choice.
5. Specify the root directory of the repository as the target branch where the pipeline resides.
6. Click Upload file.

To configure your pipeline content for BMC AMI SQL Assurance

1. On the GitLab Project dashboard, select Build to expand it.
2. Select Pipeline editor.
3. In the Pipeline editor, select your branch.

4. Enter the following information to configure the pipeline for the following component sections:

   variables:
     PIPELINE_NAME: "pipeline-sql-assurance-static-sql"                     
     CONFIG_FILE: "Config_SQL_Assurance_Static_SQL.yml"                     
   
   image:attach:xwiki:Mainframe.Data-for-Db2.BMC-AMI-SQL-Assurance-for-Db2.COB13100.Using.Using-BMC-AMI-SQL-Assurance-with-Universal-Connector.Configuring-the-GitLab-pipeline.WebHome@filename <Image location>/sqlassuranceuc:13.01.00.0005-GA                  
   
   stages:
     - static_sql                                                           
   
   build-job:                                                               
     stage: static_sql
   
     tags:
       - <runner tag name>                                          

   1. The variable names are defined with values and referenced in the pipeline.
   2. The image name is your path location and image name for the BMC AMI SQL Assurance Universal Connector image in your environment.
   3. The Stage name is the indicator of when to run the job.
   4. Job name is the indicator for what is to run in the job.
   5. Tags is the runner name that will run the pipeline job.

5. Define the pipeline steps as follows:

   • Linux commands
   • BMC AMI SQL Assurance application steps

   1. To display text in logs, use the Linux echo command.

      Example

        - echo "Replace variables defined in $CONFIG_FILE file"

   2. To replace variable values, use the Linux sed -i command. This applies to all GitLab CI/CD variable types. You must provide the absolute path of the config YAML file in which the variable is used.

      Example

      before_script:        
        # Linux command sed is used to replace the config file variables with GitLab CI/CD variables
        - sed -i "s/USER_ID_AUTH/$user_id/" $CONFIG_FILE
        - sed -i "s/USER_PASS_AUTH/$user_pass/" $CONFIG_FILE
      
        # For certBased Authentication, uncomment the following 2 sed commands
        # - sed -i "s/CERT_PATH_AUTH/$cert_path/" $CONFIG_FILE
        # - sed -i "s/CERT_PASS_AUTH/$cert_pass/" $CONFIG_FILE
      
        # Use the pipeline name variable
        - sed -i "s/PIPELINENAME_VALUE/$PIPELINE_NAME/" $CONFIG_FILE
        # Use GitLab CI/CD environment variables to fetch pipeline id, run by and pipeline source of the executing pipeline
        - sed -i "s/RUNNUMBER_VALUE/$CI_PIPELINE_ID/" $CONFIG_FILE
        - sed -i "s/RUNBY_VALUE/$GITLAB_USER_LOGIN/" $CONFIG_FILE
        - sed -i "s/RUNMODE_VALUE/$CI_PIPELINE_SOURCE/" $CONFIG_FILE

   3. To concatenate the config YAML file in the log and preview the contents, use the Linux cat command.

      Example

        - cat $CONFIG_FILE

   1. To run the steps from the config YAML file, specify step stepName and the config YAML file with its repository path. If the config YAML file resides in the repository root path, then the path is not required. The arguments for this command are the application step name, config YAML file path, and debug flag.
      To use the debug parser option, specify true after the step's config file.

      Example

      script:    
        - step authentication GitLab/SAMPLE/configFiles/Config_SQL_Assurance_Static_SQL.yml true

   2. To print the step name in the pipeline log, specify - echo and the step name enclosed in quotation marks.

      Example

        - echo “Authentication application step”

   3. To retain and access job output from your pipeline run, use the artifacts keyword in your pipeline yaml file.

      • Set paths to the workspace relative path (.) to get the files from the pipeline workspace.
      • Set name to define the artifacts archive.
      • Set when as always so that it will retain the artifacts archive no matter the previous step result.
        After the pipeline runs, in the pipeline job console log, it displays the Job artifacts section which allows you to download the named zip folder including the output files from the job and repository files.

      For more information on the artifacts keyword, see the GitLab documentation.

      Example

       artifacts:  
         paths:
           - .
         name: "report"
         when: always

   4. To allow a job to continue with failures of a certain exit code, use the allow_failure: exit_codes keyword, which enables the exit code failure, as seen in the example below. Alternatively, you can allow failures for all exit codes by specifying allow_failure: true.

      Example

      allow_failure:
        exit_codes: 1

   The example for a job script with application steps is as follows:

   build-job:                                                               
     stage: static_sql
   
     # Perform various initialization functions using Linux based command sed
     before_script:
       # Use the config file name variable
       - echo "Replace variables defined in Config_SQL_Assurance_Static_SQL.yml file"
       # Linux command sed is used to replace the config file variables with GitLab CI/CD variables
       - sed -i "s/USER_ID_AUTH/$user_id/" Config_SQL_Assurance_Static_SQL.yml
       - sed -i "s/USER_PASS_AUTH/$user_pass/" Config_SQL_Assurance_Static_SQL.yml
   
       # For certBased Authentication, uncomment the following 2 sed commands
       # - sed -i "s/CERT_PATH_AUTH/$cert_path/" Config_SQL_Assurance_Static_SQL.yml
       # - sed -i "s/CERT_PASS_AUTH/$cert_pass/" Config_SQL_Assurance_Static_SQL.yml
   
       # Use the pipeline name variable
       - sed -i "s/PIPELINENAME_VALUE/$PIPELINE_NAME/" Config_SQL_Assurance_Static_SQL.yml
       # Use GitLab CI/CD environment variables to fetch pipeline id, run by and pipeline source of the executing pipeline
       - sed -i "s/RUNNUMBER_VALUE/$CI_PIPELINE_ID/" Config_SQL_Assurance_Static_SQL.yml
       - sed -i "s/RUNBY_VALUE/$GITLAB_USER_LOGIN/" Config_SQL_Assurance_Static_SQL.yml
       - sed -i "s/RUNMODE_VALUE/$CI_PIPELINE_SOURCE/" Config_SQL_Assurance_Static_SQL.yml
       - echo "-----   Config_SQL_Assurance_Static_SQL.yml file is updated -----"
   
     script:
       # Execute application step - authentication
       - step authentication Config_SQL_Assurance_Static_SQL.yml
   
       # Execute application step - analyzeStaticSql (static_sql_package)
       - step static_sql_package Config_SQL_Assurance_Static_SQL.yml

   The detailed explanation of the syntax used in the above example is as follows:

   • The script command is a shell script that defines the actions to be taken for a job in a GitLab CI/CD pipeline.
     

     script:

   • The step command with the default configuration file config.yaml that is maintained under the root directory is as follows:
     

       - step authentication
       - step static_sql_package

   • The step command for an application step with more than one argument is as follows:
     

     - step <arg1> <arg2> <arg3>

     In this example, the arguments are defined as follows:

     • <arg1> Required application step name.
     • <arg2> (Optional) Config YAML file path and file name.
     • <arg3> (Optional) Debug flag set as Boolean. The default value is false.
       

   • The step command with the user-defined config YAML file that is maintained under the root directory is as follows:
     

       - step authentication Config_SQL_Assurance_Static_SQL.yml
       - step static_sql_package Config_SQL_Assurance_Static_SQL.yml

   • The step command with a user-defined config YAML file that is maintained under a directory or sub-directory is as follows:
     

       - step authentication GitLab/SAMPLE/configFiles/Config_SQL_Assurance_Static_SQL.yml
      - step static_sql_package GitLab/SAMPLE/configFiles/Config_SQL_Assurance_Static_SQL.yml

To define a variable in the pipeline

You can define variables in the pipeline script for use in a single pipeline as a pipeline variable or as CI/CD variables for use in multiple pipelines. For more information, see Variables-for-Universal-Connector.