Creating Tekton pipelines for Mobile Foundation

Mobile Foundation in Cloud Pak for Apps is bundled with Tekton pipelines for automating common DevOps tasks related to Mobile Foundation.

The steps to deploy Mobile Foundation on OpenShift Container Platform (OCP) are the same irrespective of how you have obtained the OCP entitlement.

Prerequisites

Following are the prerequisites before you begin installing Mobile Foundation instance using the Mobile Foundation Operator.

• Cloud Pak for Applications instance with Mobile Foundation installed.
• OpenShift CLI (oc).
• Tekton (available as part of Cloud Pak for Applications).
• Mobile Foundation application source containing Mobile Foundation application and server configuration definitions. For more information, see Mobile Foundation DevOps with OCP.

Tekton pipelines

Following Tekton Pipelines are available with Mobile Foundation on Cloud Pak for Apps.

1. Mobile App Configuration Pipeline (mobile-app-registration-pipeline)
2. Mobile App Build Pipeline for Android (mobile-app-build-android-pipeline)
3. Mobile App Build Pipeline for iOS (mobile-app-build-ios-pipeline)
4. Mobile App Distribution Pipeline (application-center-deploy)
5. Mobile App Test Pipeline for Android (mobile-app-test-android-pipeline)

Steps for running the pipelines

• Download the PPA for Mobile Foundation.
• Extract the IBM-MobileFoundation-Openshift-Pak-<version>.tar.gz file.
• cd to the location of the extracted folder
• Login to the Cloud Pak For Apps instance using the command below.

  oc login --token=<access_token> --server=<server_instance>
  

NOTE: Make sure that you deploy the pipelines to the default namespace/project. Pipelines might fail to run in other namespaces due to permission issues.

Mobile App Configuration Pipeline

Execute the following command.

oc apply -f pipeline/mobile-app-registration -n <projectname>

Following is the output produced.

pipelineresource.tekton.dev/mobile-app-registration-git-resource created
pipeline.tekton.dev/mobile-app-registration-pipeline created
task.tekton.dev/mobile-app-registration-task created

Mobile App Build Pipeline for Android

Execute the following command to deploy the pipeline

oc apply -f pipeline/mobile-app-build-android -n <projectname>

Following is the output produced.

pipelineresource.tekton.dev/mobile-app-build-android-git-sresource created
pipeline.tekton.dev/mobile-app-build-android-pipeline created
task.tekton.dev/mobile-app-build-android-task created

Mobile App Build Pipeline for iOS

Prerequisites

You need to have a Xcode server setup on a publicly accessible Mac machine. Check the section Xcode server setup for building iOS apps.

Execute the following command once you have addressed the prerequisite.

oc apply -f pipeline/mobile-app-build-ios -n <projectname>

Following is the output produced.

pipeline.tekton.dev/mobile-app-build-ios-pipeline created
task.tekton.dev/mobile-app-build-ios-task created
pipelineresource.tekton.dev/mobile-app-build-ios-git-resource created

Mobile App Distribution Pipeline

Execute the following command.

oc apply -f pipeline/mobile-app-publish -n <projectname>

Following is the output produced.

pipelineresource.tekton.dev/appcenter-git-resource created
pipeline.tekton.dev/application-center-deploy created
task.tekton.dev/application-center-upload created

Mobile App Test Pipeline for Android

Prerequisites

For running the android application test pipeline you need to have a BitBar account with API key, device ID, framework ID and project ID.

Execute the following command.

oc apply -f pipeline/mobile-app-test-android -n <projectname>

Following is the output produced.

pipelineresource.tekton.dev/mobile-app-test-android-git-resource created
pipeline.tekton.dev/mobile-app-test-android-pipeline created
task.tekton.dev/mobile-app-test-android-task created

Above commands creates the tasks, pipelines and resources. We can see the tasks, resources and pipelines in the OpenShift Pipelines view

Running the pipelines manually with appropriate resources

1. Edit the resource file with proper git repository URL of the application.

    pipeline/mobile-app-registration/appregistrationgitresource.yaml
    pipeline/mobile-app-build-android/ buildandoridgitresource.yaml
    pipeline/mobile-app-build-ios/ buildiosgitresource.yaml
    pipeline/mobile-app-publish/mobileapppublishgitresource.yaml
    pipeline/mobile-app-test-android/testandroidappgitresource.yaml
   

2. Run the command to update the resources of the Tekton pipeline mobile-app-registration.

     oc apply -f pipeline/mobile-app-registration/appregistrationgitresource.yaml -n <projectname>
   

   Following is the output produced.

     pipelineresource.tekton.dev/mobile-app-registration-git-resource configured
   

3. Run the command to update the resources of the Tekton pipeline mobile-app-build-android.

     oc apply -f pipeline/mobile-app-build-andorid/buildandoridgitresource -n <projectname>
   

   Following is the output produced.

     pipelineresource.tekton.dev/mobile-app-build-android-git-resource configured
   

4. Run the command to update the resources of the Tekton pipeline mobile-app-build-ios.

     oc apply -f pipleline/mobile-app-build-ios/buildiosgitresource -n <projectname>
   

   Following is the output produced.

     pipelineresource.tekton.dev/mobile-app-build-ios-git-resource configured
   

5. Run the command to update the resources of the Tekton pipeline mobile-app-publish.

     oc apply -f pipeline/mobile-app-publish/mobileapppublishgitresource.yaml -n <projectname>
   

   Following is the output produced.

     pipelineresource.tekton.dev/appcenter-git-resource configured
   

6. Run the command to update the resources of the Tekton pipeline mobile-app-test-android.

     oc apply -f pipeline/mobile-app-test-android/testandroidappgitresource.yaml -n <projectname>
   

   Following is the output produced.

     pipelineresource.tekton.dev/mobile-app-test-android-git-resource configured
   

7. Make sure your application consists of the mfpconfig folder with all the config files.

   NOTE: If your application is not created using the MobileFirst CLI or you don’t want to use the app_config.json and server_config.json then this can be skipped.

   a. server_config.json with all the server details.
   For more details, refer to Using the MobileFirst CLI. Following is a sample server_config.json file.

      {
        "mfp" : {
            "name": "test",
            "protocol": "http",
            "host": "127.0.0.0",
            "port": "9080",
            "servercred": "admin:admin"
        }
      }
   

   b. app_config.json with all the application configuration details.
   For more information, refer to Using the MobileFirst CLI. Following is a sample app_config.json config file.

      {
      "platforms": [
        {
          "applicationKey": {
            "version": "1.0.0",
            "clientPlatform": "android",
            "packageName": "com.demo.push"
          },
          "displayName": "DemoAppB",
          "scopeElementMapping": {
            "push.mobileclient": "",
            "liveupdate.mobileclient": ""
          }
        }
      ],
      "services": [
        {
          "name": "push",
          "settings": {
            "fcm": {
              "apiKey": "AAAAGq1Fpbw:APA91bEjhjZLuFMC4hG46nJ4zbL7dyU-BHyNOFqfC_JVOx1JElg_1029_JwliDvYbcsoRe0lS4XOMjawCh09FhVY7-1DbKyjDJBzfuM2_cXOUjLSjnJ1rscqzV1muGJ3e938W17bQxgV2kZPM-nD0I7dNdh37o378A",
              "senderId": "114576172476"
            }
          },
          "tags": [
            {
              "name": "Tag1",
              "description": "Abt Tag1"
            },
            {
              "name": "Tag2",
              "description": "Abt Tag2"
            }
          ]
        },
        {
          "name": "liveupdate",
          "schema": {
            "features": {
              "enableButton": {
                "name": "enableButton",
                "internalId": "enableButton",
                "description": "Show the feature button",
                "defaultValue": false
              }
            },
            "properties": {
              "titleColour": {
                "name": "titleColour",
                "internalId": "titleColour",
                "description": "Change colour of the title",
                "defaultValue": "black"
              }
            }
          }
        },
        {
          "name": "analytics"
        }
      ],
      "confidentialClients": [
        {
          "id": "SampleClient",
          "secret": "12345",
          "allowedScope": "clients:read-public clients:read-protected update",
          "displayName": "SampleClient"
        }
      ],
        "appPublish": {
            "android": {
                "release": {
                    "keystore": "dab-android.keystore",
                  "storePassword": "mfp123",
                  "alias": "dab-key",
                  "password" : "mfp123"
                }
          }
        }
      }
   

8. If you are not using the config files you need to pass these as parameters to the pipleines using pipelinerun or using the triggerbindings(If webhooks are being used), which can be found in the coming section.

Running the pipelines using PipelineRun

1. Create a pipeline run yaml file for a pipeline that you want to run.

   Here is an example of a pipeline run for mobile-app-build-android pipeline

      apiVersion: tekton.dev/v1alpha1
      kind: PipelineRun
      metadata:
        name: mobile-app-build-android-pipeline-run
      spec:
        pipelineRef:
          name: mobile-app-build-android-pipeline
        serviceAccountName: 'default'
        params:
          - name: gitUserName
            value: "gitUserName"
          - name: gitRepositoryName
            value: "gitRepositoryName"
          - name: githubToken
            value: "githubToken"
          - name: ignoreProguardWarnings
            value: "yes"
          - name: productionBuild
            value: "no"
          # The below parameters are optional parameters and these can be used if your git source does not contain the mfconfig/server_config.json file.
          # - name: mfServerProtocol
          #   value: "http"
          # - name: mfServerHost
          #   value: "mfServerHost"
          # - name: mfServerPort
          #   value: "80"
        resources:
        - name: git-source
          resourceRef:
            name: mobile-app-build-android-git-resource
   

   Here is an example of a pipeline run for mobile-app-registration pipeline

      apiVersion: tekton.dev/v1alpha1
      kind: PipelineRun
      metadata:
        name: mobile-app-registration-pipeline-run
      spec:
        pipelineRef:
          name: mobile-app-registration-pipeline
        serviceAccountName: 'default'
        # All the parameters are optional, use these parameters if your git source does not contain the mfconfig/server_config.json and app_config.json files.
        # params:
        #   - name: mfServerProtocol
        #     value: "http"
        #   - name: mfServerHost
        #     value: "mfServerHost"
        #   - name: mfServerPort
        #     value: "80"
        #   - name: mfServerUserName
        #     value: "admin"
        #   - name: mfServerPassword
        #     value: "admin"
        #   - name: appDisplayName
        #     value: "TestApp"
        #   - name: appPackageOrBundleIdentifier
        #     value: "packageName"
        #   - name: appPlatform
        #     value: "android"
        #   - name: appVersion
        #     value: "1.0"   
        resources:
        - name: git-source
          resourceRef:
            name: mobile-app-registration-git-resource
   

   Here is an example of a pipeline run for mobile-app-publish pipeline

      apiVersion: tekton.dev/v1alpha1
      kind: PipelineRun
      metadata:
        name: application-center-deploy-run
      spec:
        pipelineRef:
          name: application-center-deploy
        serviceAccountName: 'default'
        params:
          - name: gitUserName
            value: "gitUserName"
          - name: gitRepositoryName
            value: "gitRepositoryName"
          # The below are the optional parameters. use these parameters if you git source does not contain the mfconfig/server_config.json file
          # - name: mfAppCenterProtocol
          #   value: "http"
          # - name: mfAppCenterHost
          #   value: "mfAppCenterHost"
          # - name: mfAppCenterPort
          #   value: "80"
          # - name: mfAppCenterUserName
          #   value: "admin"
          # - name: mfAppCenterPassword
          #   value: "admin"
        resources:
        - name: git-source
          resourceRef:
            name: appcenter-git-resource
   

   Here is an example of a pipeline run for mobile-app-build-ios pipeline

      apiVersion: tekton.dev/v1alpha1
      kind: PipelineRun
      metadata:
        name: mobile-app-build-ios-pipeline-run
      spec:
        pipelineRef:
          name: mobile-app-build-ios-pipeline
        params:
        - name: gitRepositoryName
          value: "gitRepositoryName"
        - name: gitUserName
          value: "gitUserName"
        - name: githubToken
          value: "githubToken"
        - name: xcodeServerHost
          value: "127.0.0.1"
        - name: xcodeServerBot
          value: "bd821f9aa599721db5104a2cf400000a"
        resources:
        - name: git-source
          resourceRef:
            name: mobile-app-build-ios-git-resource
   

2. Once all the required parameters an resources are added to the pipeline run execute the oc apply <pipelinerun>.yaml file. This will trigger a pipleine run.
3. The pipeline runs can be accessed from the openshift dashboard pipelines view

Deploying tekton triggers for webhooks

NOTE: These steps are needed only if you need to trigger the pipelines using github webhooks.

Configuring tekton triggers for Android build pipeline

Prerequisites

Before using the tekton triggers for android a few parameters needs to be configured in pipeline/android-pipeline-trigger/mfpandroidtriggerbinding.yaml file or the mfp-android-trigger-binding resource from the openshift dashboard search view.

• gitrevision : This parameter git revision refers to the github branch name. By default is set to get the default branch $(body.repository.default_branch) from the webhook payload. If pipeline needs to be configured for a different branch please refer to github webhook payload documentation and change accordingly.
• githubToken : This is the personal access token of your github account. Replace the place holder {githubToken} with a valid github-token. Make sure the token provided has proper access to push apk to releases.
• ignoreProguardWarnings : Set this value to yes if proguard warnings are to be ignored and continue the build else the build will fail if there are any proguard warnings.
• productionBuild : If the app is an ionic app then this parameter allows you toggle the production build on/off. If set to yes then the pipeline does a production build, else it will do a normal build.

OPTIONAL PARAMETERS:

NOTE: Edit these values only if your git source does not contain the mfconfig/server_config.json file

• mfServerProtocol: Protocol for the Mobile Foundation server.
• mfServerHost: Fully qualified service name/host name of Mobile Foundation server.
• mfServerPort: Listener port for Mobile Foundation server.

Execute the following command.

oc apply -f pipeline/android-pipeline-trigger -n <projectname>

Following is the output produced.

eventlistener.tekton.dev/mfp-android-webhook-listener created
route.route.openshift.io/mfp-android-webhook-route created
triggerbinding.tekton.dev/mfp-android-trigger-binding created
rolebinding.rbac.authorization.k8s.io/mfp-android-trigger-binding created
serviceaccount/mfp-android-triggers-sa created
triggertemplate.tekton.dev/mfp-android-trigger-template created
role.rbac.authorization.k8s.io/mfp-trigger-role created

Configuring tekton triggers for iOS build pipeline

Prerequisites

Before using the tekton triggers for ios a few parameters needs to be configured in the pipeline/ios-pipeline-trigger/mfpiostriggerbinding.yaml file or the mfp-ios-trigger-binding resource from the openshift search view.

• gitrevision : This parameter git revision refers to the github branch name. By default is set to get the default branch $(body.repository.default_branch) from the webhook payload. If pipeline needs to be configured for a different branch please refer to github webhook payload and change accordingly.
• githubToken : This is the personal access token of your github account. Replace the place holder {githubToken} with a valid github-token. Make sure the token provided has proper access to push apk to releases.
• xcodeServerHost : The ip adress of the machine on which XCode server is running
• xcodeServerBot : The BotID for the configured application.

Execute the following command.

oc apply -f pipeline/ios-pipeline-trigger -n <projectname>

Following is the output produced.

eventlistener.tekton.dev/mfp-ios-webhook-listener created
route.route.openshift.io/mfp-ios-webhook-route created
triggerbinding.tekton.dev/mfp-ios-trigger-binding created
rolebinding.rbac.authorization.k8s.io/mfp-ios-trigger-binding created
serviceaccount/mfp-ios-triggers-sa created
triggertemplate.tekton.dev/mfp-ios-trigger-template created

Configuring tekton triggers for Application Registration pipeline

Before using the tekton triggers for app registration a few parameters needs to be configured in pipeline/app-reg-pipeline-trigger/mfpapptriggerbinding.yaml file or the mfp-app-register-trigger-binding resource from the openshift search view.

NOTE: Edit the below values only if your git source does not contain the mfconfig/server_config.json file

• mfServerProtocol: Protocol for the Mobile Foundation server.
• mfServerHost: Fully qualified service name/host name of Mobile Foundation server.
• mfServerPort: Listener port for Mobile Foundation server.
• mfServerUserName: Mobile Foundation server admin username.
• mfServerPassword: Mobile Foundation server admin password.

NOTE: Edit the below values only if your git source does not contain the mfconfig/app_config.json file

• appPackageOrBundleIdentifier: Application Package name or Bundler Indentifier.
• appPlatform: Application platform that you want to register (android/ios).
• appVersion: Application version.
• appDisplayName: Application Display Name

Execute the following command.

oc apply -f pipeline/app-reg-pipeline-trigger -n <projectname>

Following is the output produced.

eventlistener.triggers.tekton.dev/mfp-app-register-webhook-listener created
route.route.openshift.io/mfp-app-register-webhook-route created
triggerbinding.triggers.tekton.dev/mfp-app-register-trigger-binding created
rolebinding.rbac.authorization.k8s.io/mfp-app-register-trigger-binding created
serviceaccount/mfp-app-register-triggers-sa created
triggertemplate.triggers.tekton.dev/mfp-app-register-trigger-template created

Configuring tekton triggers for Application Deploy pipeline

Before using the tekton triggers for app registration a few parameters needs to be configured in pipeline/app-publish-pipeline-trigger/mfpapppublishtriggerbinding.yaml file or the mfp-app-publish-trigger-binding resource from the openshift search view.

NOTE: Edit the below values only if your git source does not contain the mfconfig/server_config.json file

• mfAppCenterProtocol: Protocol for Mobile Foundation application center.
• mfAppCenterHost: Fully qualified service name/host name of Mobile Foundation application center.
• mfAppCenterPort: Listener port for Mobile Foundation application center.
• mfAppCenterUserName: Mobile Foundation application center admin username.
• mfAppCenterPassword: Mobile Foundation application center admin password.

Execute the following command.

oc apply -f pipeline/app-publish-pipeline-trigger -n <projectname>

Following is the output produced.

rolebinding.rbac.authorization.k8s.io/mfp-app-publish-trigger-binding created
eventlistener.triggers.tekton.dev/mfp-app-publish-webhook-listener created
route.route.openshift.io/mfp-app-publish-webhook-route created
triggerbinding.triggers.tekton.dev/mfp-app-publish-trigger-binding created
serviceaccount/mfp-app-publish-triggers-sa created
triggertemplate.triggers.tekton.dev/mfp-app-publish-trigger-template created

Above commands creates the EventListeners,TriggerBindings and TriggerTemplates that can be accessed from the openshift dashboard search view.

They also expose a total of 4 routes that can be used to configure webhooks. From the openshift dashboard navigate to Networking and Routes, you should be seeing the following routes

1. mfp-app-register-webhook-route (for mobile-app-registration-pipeline)
2. mfp-android-webhook-route (for mobile-app-build-android-pipeline)
3. mfp-ios-webhook-route (for mobile-app-build-ios-pipeline)
4. mfp-app-publish-webhook-route (for application-center-deploy)

Triggering pipelines using webhook

Run the pipeline with webhook to automatically trigger the PipelineRun whenever there are changes in the application git repository.

Creation of Webhooks

1. Go to the Git repository for which you want to configure the webhook.
2. Navigate to the Settings tab of the respository.
3. Click and Webhooks on the left navbar and then click on Add webhook.
4. Provide the Payload URL field with one the routes that was created previously when tekton triggers are configured. The Content type should be set to application/json and select the event when you want the webhook to run.
5. Click Add Webhook

The event to the git repository shall trigger creation of a PipelineRun configured for that route. To view the logs and status of the PipelineRun. Go to the openshift pipelines view and select the PipelineRuns.

XCode Server setup for building iOS apps

1. On a Mac machine, setup Xcode.
2. Open Xcode.
3. From the top menu select Xcode Server.
4. Turn on the Xcode Server to run integrations.
5. After the server is turned on go to Permissions section and change Create and View Bots option to all users.
6. Go to Accounts section and add a new account with the account type Xcode Server and then choose the server that is available.
7. After the Xcode Server is setup, the bot needs to be configured in order to run integrations and generate an ipa. Open the iOS project that you want to build in Xcode.
8. Go to the build log for the project and select By Group option. The configured server should be visible.
9. Right click the server and then click Create Bot.
10. Give a name for the bot and click Next. Please make sure that the bot name does not contain any spaces. Configure the source control for the bot and click Next.
11. In the build configuration under the Actions section, make sure Archive option is selected. Under the Export option select Use Custom Export Options Plist. Make sure you have a plist file in the following format.
12. In the Schedule bot integrations section, select the integrations to run Manually and then click Next.
13. Select the relevant build options for your project and click Next.
14. In the Certificates and Profiles sections make sure relevant certificates and profiles required for the generating the ipa are added to the server and click Next.
15. Add these arguments and provide relevant values for the xcodebuild command in the Arguments and Environment Variables section and click Next.
16. In the Triggers section click Add and select Pre-Integration script, give it a name, download and copy the below script and add it in the script section that downloads the dependencies for the app (if any) and then click Create. Download script
17. After the bot is successfully created wait for the integration to run. After the integration is successful, go to the integration and go to Logs. In the logs you should be able to see the botId. The botId is needed for running the integrations from the Tekton pipelines.
18. Now the Xcode Server setup is successful. Use the bot ID to trigger the iOS build pipeline.

Known Issues

For an ionic app, if the tekton build fails with the error Cannot find type definition file for '@types'. then open the package.json of the app and change the @ionic/app-scripts version to 3.2.3.