Configuring the GitHub Actions workflow

To create a new workflow

1. On the GitHub Actions tab, click New workflow.
2. In the Simple workflow section, click Configure.
3. Select the name field that has the default name blank.yml, and enter your workflow name.
4. Select the editor and enter your workflow details.
5. To save, click Commit changes….

To upload an existing workflow

1. On the GitHub Code tab, click the .github/workflows directory to expand it.
2. In the upper right-hand corner of the .github/workflows directory, click Add file.
3. Click Upload files.
4. In the Upload files dialog box, drag the workflow YAML file into the upload files dialog box, or click choose your files to select a workflow YAML file and click Commit changes.
5. On the GitHub Code tab, click the .github/workflows directory to expand and select your workflow file.
6. On the Code tab, select Edit this file and customize your workflow as needed.
7. Click Commit changes….

Customizing your workflow content for BMC AMI DevOps

1. Define the workflow’s name, trigger event, jobs, container, and repository checkout step as configured in your environment.

   Example

   
   

   name: <Workflow name>             #specify workflow name
   
   on:
     workflow_dispatch               #manual trigger of the workflow
   
   jobs:
     <Job name>:                     #name of the job
       runs-on: <Runner name>        #specify runner name
       container:
       image:attach:xwiki:Mainframe.Data-for-Db2.BMC-AMI-DevOps-for-Db2.AMA13100.Using.Using-BMC-AMI-DevOps-with-Universal-Connector.Configuring-the-workflow.WebHome@filename <Image location>/devopsuc:13.01.00.0002-GA
       options: -u <uid>            #specify Linux user id for user running the runner

   In this example, the image specified is your path location for the BMC AMI DevOps Universal Connector image, and you must use the -u <uid> option to pass into the container host.

   Important

   For the BMC AMI DevOps Universal Connector image, GitHub Actions requires the same user id of the user running the self-hosted runner.

   In the following example, the image for the BMC AMI DevOps Universal Connector image tag and options use the user id, 1008, to run the container process because the self-hosted runner is running with the same user id, 1008.

   The runner creates a sub-folder in its working folder, which is used as the default working directory of the container. This sub-folder is created with the runner's user id.

   At the checkout step, the container process performs the following activities:

   • Deletes all files or folders from the working directory. 
   • Fetches the files or folders from the repository and creates them in the working directory.

   To create the file or folder in the working folder, the container process must have the same user id as the runner.    

   Example

   image:attach:xwiki:Mainframe.Data-for-Db2.BMC-AMI-DevOps-for-Db2.AMA13100.Using.Using-BMC-AMI-DevOps-with-Universal-Connector.Configuring-the-workflow.WebHome@filename <Image location>/devopsuc:13.01.00.0002-GA
   
   options: -u 1008

2. Define the workflow steps as follows:

   • Linux commands
   • BMC AMI DevOps application steps

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

      Example

      run: |
             echo "Replace variables defined in GitHub/SAMPLE/MAA/configFiles/Config_Schema_Migration_CompareDDL.yml file"

   2. To replace variable values, use the Linux sed -i command. This applies to all secrets and variables defined in GitHub Actions. You must provide the absolute path of the config YAML file in which the variable is used.

      Example

      run: |
        sed -i "s/USER_ID_AUTH/${{vars.user_id}}/" GitHub/SAMPLE/MAA/configFiles/Config_Schema_Migration_CompareDDL.yml
        sed -i "s/USER_PASS_AUTH/${{secrets.user_pass}}/" GitHub/SAMPLE/MAA/configFiles/Config_Schema_Migration_CompareDDL.yml

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

      Example

      run: |
      
        cat GitHub/SAMPLE/MAA/configFiles/Config_Schema_Migration_CompareDDL.yml

   1. To run the steps from the config YAML file, specify step stepName and the config YAML file with its repository path. Use the step command to run the application step from the GitHub Actions workflow configuration file. If the config YAML file resides in the repository root path, then the path is not required. The arguments for this command are 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

       

      run:|
        step authentication GitHub/SAMPLE/MAA/configFiles/Config_Schema_Migration_CompareDDL.yml true

   2. To print the step name in the workflow log, specify - name: and the stepName.

      Example

      - name: Authentication 

   3. To retain and access job output from your workflow run, use GitHub Actions’ actions/upload-artifact@v4, in your workflow yaml file.

      • Give the action a name, like ‘Upload artifacts’.
      • Set the if condition (${{ success() || failure() }}), so the upload-artifact@v4 runs no matter the previous step result.
      • Set path to the workspace relative path (.) to get the files from the workflow workspace.
        After the workflow runs, in the beginning of the workflow job console log, it produces an artifact link to the folder and saves the output files from the job as well as repository files.

      For more information on the upload-artifact action, see the GitHub Actions documentation.

      Example

      - name: Upload artifacts
        if: ${{ success() || failure() }}
        uses: actions/upload-artifact@v4
        with:
          name: report
          path: . 

   Sample workflow step script

   steps:
         # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
         - name: Check out repository
           uses: actions/checkout@v3
              
         # Perform various initialization functions using Linux based command sed
         - name: Initialization
           run: |
             echo "Replace variables defined in Config_File_Transmission.yml file"
             # Linux command sed is used to replace the config file variables with GitHub Actions secrets and variables
             sed -i "s/USER_ID_AUTH/${{vars.user_id}}/" Config_File_Transmission.yml
             sed -i "s/USER_PASS_AUTH/${{secrets.user_pass}}/" Config_File_Transmission.yml
             # For certBased Authentication, uncomment the following 2 sed commands
             # sed -i "s|CERT_PATH_AUTH|/opt/secret/<clientCertificateName>.p12|" Config_File_Transmission.yml
             # sed -i "s/CERT_PASS_AUTH/${{secrets.cert_pass}}/" Config_File_Transmission.yml
             # Use syntax \<var name\> to find and replace the exact matching word
             sed -i "s/\<JOB_ID\>/${{vars.job_id}}/" Config_File_Transmission.yml
             sed -i "s/DDL_FILE_FT_UPLOAD/${{vars.ddl_file}}/" Config_File_Transmission.yml
             # Use GitHub Actions environment variables to fetch workflow name, run number, run by and run mode of the executing workflow
             sed -i "s/PIPELINENAME_VALUE/${{github.workflow}}/" Config_File_Transmission.yml
             sed -i "s/RUNNUMBER_VALUE/${{github.run_id}}/" Config_File_Transmission.yml
             sed -i "s/RUNBY_VALUE/${{github.actor}}/" Config_File_Transmission.yml
             sed -i "s/RUNMODE_VALUE/${{github.event_name}}/" Config_File_Transmission.yml         
             echo "-----   Config_File_Transmission.yml file is updated -----"
        
         # Execute application step - authentication
         - name: Authentication
           run:
             step authentication Config_File_Transmission.yml
            
         # Execute application step - fileUpload (local_to_mainframe)
         - name: File Transmission
           run:
             step local_to_mainframe Config_File_Transmission.yml
            
         - name: Upload artifacts
           uses: actions/upload-artifact@v2
           with:
             name: report
             path: .

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

   • The step command for an application step with one mandatory argument is as follows, where <arg> is a required application step name:

     step <arg>

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

     # Execute application step - authentication
     - name: Authentication
       run:
         step authentication
              
     # Execute application step - fileUpload (local_to_mainframe)
     - name: File Transmission
       run:
         step local_to_mainframe 

   • The example for 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 user-defined config YAML file that is maintained under the root directory is as follows:
     

     # Execute application step - authentication
     - name: Authentication
       run:
         step authentication Config_File_Transmission.yml
              
     # Execute application step - fileUpload (local_to_mainframe)
     - name: File Transmission
       run:
         step local_to_mainframe Config_File_Transmission.yml

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

     # Execute application step - authentication
     - name: Authentication
       run:
         step authentication /directory/sub-directory(s)/Config_File_Transmission.yml
              
     # Execute application step - fileUpload (local_to_mainframe)
     - name: File Transmission
       run:
         step local_to_mainframe /directory/sub-directory(s)/Config_File_Transmission.yml

Defining a variable in the workflow

You can define variables for use in a single workflow as an environment variable in the workflow script or for use in multiple workflows as Actions secrets and variables.

For more information, see Variables-for-Universal-Connector.