Add mobile ci/cd content (#205)

* update mobile ci cd topic

* update based on feedback from reviews

modules/ROOT/nav.adoc

@@ -56,11 +56,11 @@ include::{partialsdir}/attributes.adoc[]
 *** xref:mobile-cicd.adoc#introduction[Introduction]
 *** xref:mobile-cicd.adoc#setup[Setting Up]
 *** xref:mobile-cicd.adoc#build-config[Creating a Build Configuration]
-// *** xref:mobile-cicd.adoc#jenkins[Adding a Jenkins file]
-// *** xref:mobile-cicd.adoc#building[Building Apps]
-// *** xref:mobile-cicd.adoc#logs[Accessing Build Logs]
+*** xref:mobile-cicd.adoc#jenkins[Adding a Jenkins file]
+*** xref:mobile-cicd.adoc#building[Building Apps]
+*** xref:mobile-cicd.adoc#logs[Accessing Build Logs]
 *** xref:mobile-cicd.adoc#deploy[Deploying Apps]
-// *** xref:mobile-cicd.adoc#clean[Cleaning up Builds]
+*** xref:mobile-cicd.adoc#clean[Cleaning up Builds]
 
 
 ** xref:device-security.adoc[{device-security-service}]

modules/ROOT/pages/digger/access-mobile-client-build-logs.adoc

@@ -0,0 +1,24 @@
+[[access-mobile-client-build-logs]]
+= Viewing Build Logs
+
+== Viewing Build History in the OpenShift Console
+
+All of the builds related to your mobile client can be seen in the **Builds** tab of your {mobile-client}. Each build can be expanded to show further information about the build configuration, latest build and build history.
+
+All builds have a *View Log* link associated with them to access the detailed logs of that build.
+
+image::mobile-clients-builds-complete.png[access-build-from-notification][align="center"]
+
+
+== Viewing Build Logs in Jenkins
+
+. Navigate to the {mobile-client} and click the *Builds* tab.
+
+. Click the *View Log* link for the build, you are redirected to the Jenkins instance that has been running your build.
+
+. If prompted, log into OpenShift and accept the authorization request for:
++
+* user:info permission
+* user:check-access permission
+
+. View the log of the build. Based on your permissions to the OpenShift project, you might have access to other Jenkins capabilities, such as inspecting the build configuration or re-running the build with changes in the pipeline script.

modules/ROOT/pages/digger/cleaning-up-client-builds.adoc

@@ -0,0 +1,13 @@
+[[cleaning-up-mobile-client-builds]]
+= Cleaning up a Mobile Client Build
+
+== Deleting a Build Instance
+
+After creating and running a build, you can click through to your mobile client screen from the project overview and into the *Builds* tab. In this tab you see the details of your various mobile client builds.
+
+1. Click the build number of the build you want to delete. The build details screen is displayed.
+2. Choose *Delete* from the *Actions* menu. The build resource is removed from OpenShift along with the corrosponding build in the CI/CD service and any artefacts.
+
+== Deleting a {digger-service} Build Configuration
+
+When you create a {mobile-client} build configuration, you create a https://docs.openshift.org/latest/dev_guide/builds/index.html#defining-a-buildconfig[BuildConfig] resource in OpenShift. This build config is then translated into a Jenkins Build for your mobile client in the CI/CD service. If you want to remove the entire Job from the CI/CD service and clean up everything in OpenShift, then deleting the build config  will achieve this. To delete the build config, click into your mobile client and open the builds tab. From here you can select the delete option from the more actions (the three dots) at the far right of the build row. Once deleted associated resources and builds with that Job will be removed as will the underlying Jenkins Job in the CI/CD service.

modules/ROOT/pages/digger/proc_adding-a-jenkinsfile.adoc

@@ -0,0 +1,134 @@
+= Adding a Jenkinsfile
+
+To build a mobile app using the {digger-service} service, you must add a `Jenkinsfile` to your git repository, typically in the root directory of that repository.
+
+The following sample files are suitable for the link:showcase-apps.html[Showcase Apps]. You may need a different configuration for your mobile app.
+
+== Sample Android Jenkinsfile for Debug Build Type
+
+```groovy
+node("android") {
+  stage("Checkout") {
+    checkout scm
+  }
+
+  stage("Prepare") {
+    sh 'chmod +x ./gradlew'
+  }
+
+  stage("Build") {
+    sh './gradlew clean assembleDebug' //comment for debug builds
+  }
+
+  uncomment the following stage if running a release build
+  stage("Sign") {
+
+  }
+
+ stage("Archive") {
+    archiveArtifacts artifacts: 'app/build/outputs/apk/**/app-debug.apk', excludes: 'app/build/outputs/apk/*-unaligned.apk'
+  }
+}
+
+```
+
+== Sample Android Jenkinsfile for Release Build Type
+
+```groovy
+node("android") {
+  stage("Checkout") {
+    checkout scm
+  }
+
+  stage("Prepare") {
+    sh 'chmod +x ./gradlew'
+  }
+
+  stage("Build"){
+    sh './gradlew clean assembleRelease' // uncomment for release build
+  }
+
+  stage("Sign") {
+    signAndroidApks (
+      keyStoreId: "myproject-testandroidcert",
+      keyAlias: "aerogear",
+      apksToSign: "**/*-unsigned.apk",
+      // uncomment the following line to output the signed APK to a separate directory as described above
+      // signedApkMapping: [ $class: UnsignedApkBuilderDirMapping ],
+      // uncomment the following line to output the signed APK as a sibling of the unsigned APK, as described above, or just omit signedApkMapping
+      // you can override these within the script if necessary
+      // androidHome: '/usr/local/Cellar/android-sdk'
+    )
+  }
+
+ stage("Archive") {
+    archiveArtifacts artifacts: 'app/build/outputs/apk/**/app-release.apk', excludes: 'app/build/outputs/apk/*-unaligned.apk'
+  }
+}
+
+```
+
+== Sample iOS Jenkinsfile for Release Build Type
+
+```groovy
+CODE_SIGN_PROFILE_ID = "myproject-iostestcert"
+BUILD_CONFIG = "Debug" // Use either "Debug" or "Release"
+
+PROJECT_NAME = "helloworld-ios-app"
+INFO_PLIST = "helloworld-ios-app/helloworld-ios-app-Info.plist"
+VERSION = "1.0.0"
+SHORT_VERSION = "1.0"
+BUNDLE_ID = "org.aerogear.helloworld-ios-app"
+OUTPUT_FILE_NAME="${PROJECT_NAME}-${BUILD_CONFIG}.ipa"
+SDK = "iphoneos"
+
+// use something like 8.3 to use a specific XCode version, default version is used if not set
+XC_VERSION = ""
+
+// do a clean build and sign
+CLEAN = true
+
+node('ios') {
+    stage('Checkout') {
+        checkout scm
+    }
+
+    stage('Prepare') {
+      sh '/usr/local/bin/pod install'
+    }
+
+    stage('Build') {
+        withEnv(["XC_VERSION=${XC_VERSION}"]) {
+            xcodeBuild(
+                    cleanBeforeBuild: CLEAN,
+                    src: './',
+                    schema: "${PROJECT_NAME}",
+                    workspace: "${PROJECT_NAME}",
+                    buildDir: "build",
+                    sdk: "${SDK}",
+                    version: "${VERSION}",
+                    shortVersion: "${SHORT_VERSION}",
+                    bundleId: "${BUNDLE_ID}",
+                    infoPlistPath: "${INFO_PLIST}",
+                    xcodeBuildArgs: 'ENABLE_BITCODE=NO OTHER_CFLAGS="-fstack-protector -fstack-protector-all"',
+                    autoSign: false,
+                    config: "${BUILD_CONFIG}"
+            )
+        }
+    }
+
+    stage('CodeSign') {
+        codeSign(
+                profileId: "${CODE_SIGN_PROFILE_ID}",
+                clean: CLEAN,
+                verify: true,
+                ipaName: "${OUTPUT_FILE_NAME}",
+                appPath: "build/${BUILD_CONFIG}-${SDK}/${PROJECT_NAME}.app"
+        )
+    }
+
+    stage('Archive') {
+        archiveArtifacts "build/${BUILD_CONFIG}-${SDK}/${OUTPUT_FILE_NAME}"
+    }
+}
+```

modules/ROOT/pages/digger/proc_creating-a-build-configuration.adoc

@@ -8,12 +8,33 @@ include::{partialsdir}/attributes.adoc[]
 
 You can use the OpenShift UI to create a new client build for an existing mobile client.
 
-. Open the OpenShift UI.
+. Log in to the OpenShift Console.
 
-. Browse to the *Project Overview* screen and find the mobile client you want to build.
+. Browse to the *Project Overview* screen and find the {mobile-client} you want to build.
 
-. Click on the name of the mobile client to open the details view.
+. Click on the name of the {mobile-client} to open the details view.
 
-. At the top right of the screen, click the *drop down* and select *Create Build*.
+. From the *Builds* tab, select *Create Build* in the *Actions* menu. If no build configuration  exists, a *Start Build* button is displayed which allows you create a build configuration.
++
+image:mobile-clients-builds-empty.png[]
++
+The *Client Build Form* is displayed.
 
-. When the *Client Build Form* screen opens, give the new build a unique name.
+.. Enter a unique name for the build configuration in the *Name* field.
+
+.. Enter the *Git Repository URL* for the {mobile-client} you want to build.
+
+.. Select the *Authentication Type* for the Git repository. For example, the {product-name} showcase apps are available to everyone, so you would choose *Public*. If your repo URL starts with `git@`, select *SSH*. If your repo URl starts with `http` and requires authentication, select *Basic*.
+
+.. If you select *Advanced Options* you can also specify:
++
+* Git Reference:: Optional branch, tag, or commit to checkout, default is master. This option can be used to select different branches of you application repo for different builds, for example, release vs develop.
+* Jenkins file path:: Optional path to where the Jenkinsfile is located in your application repo. The default is the root of the repo.
+
+. Select the *Build Type* for the build configuration. Typically you create two build configurations, one for debugging and and another for release. 
++
+NOTE: Typically, for a *Release* build configuration, you need to add more information as described in xref:ref_source-configuration_ref_source-configuration[].
+
+. Create any environment variables that you want to pass to the build process and set values in the *Environment Variable* section of the form.
+
+. Click *Create*

modules/ROOT/pages/digger/ref_source-configuration.adoc

@@ -5,45 +5,24 @@ include::{partialsdir}/attributes.adoc[]
 
 [id='{context}_ref_source-configuration']
 
-= Source Configuration Reference material
+= Debug and Release Build Types
 
-To build your mobile client, you need to provide source configuration.
-This section describes aspects of a mobile client's source configuration.
+Use the following information to configure debug and release type builds.
 
-== Repository
-
-Add Git Repository URL:: To provide additional advanced information such as a different git ref (default is master), or Jenkinsfile path (default is the root of the repo), use the advanced options.
-Authentication Type Public:: Use this for public repos that require no authentication.
-Authentication Type Basic:: Username/password credentials, use this for https/http repo urls that require authentication.
-Authentication Type SSH:: SSH Private Key Authentication, use this for ssh repo urls (git@).
-
-NOTE: When adding credentials for Authentication Type Basic, ensure the name is unique.
-
-== Advanced Options
-
-Selecting *Advanced Options* in the source configuration section displays a number of additional options:
-Git Reference:: Optional branch, tag, or commit to checkout, default is master. This option can be used to select different branches of you application repo for different builds, for example, release vs develop.
-Jenkins file path:: Optional path to where the Jenkinsfile is located in your application repo. The default is the root of the repo.
-
-== Build Configuration
-
-Add configuration relating to the type of build being created e.g debug or release.
-The type of information required here will depend on the type of application being built.
-
-=== Android
+== Android
 Add Build Type:
 Debug:: An Android debug build, no additional information required
 Release:: An Android release build, requires an upload of a password protected PKCS12 file containing a key protected by the same password.
 
-==== Release Build Type
+=== Release Build Type
 
 As a release build will need to be signed, you need to specify the keystore and private key passwords.
 
-==== Keystore located in source code
+=== Keystore located in source code
 
 If your keystore is checked into your source code, you will need to take the password value in your build script as an environmental variable. This will allow you to set this environmental variable as part of your client build from within the OpenShift UI. This can be done directly when creating the mobile client build or afterwards by editing the build config.
 
-==== External keystore
+=== External keystore
 
 If you have an external keystore, you should ensure to select the checkbox to use an external keystore once this is done, you will be asked for the following additional information:
 
@@ -58,14 +37,14 @@ The PKSC12 archive of your android keystore certificate can be generated using t
 keytool -importkeystore -srckeystore <your-android-cert.keystore> -destkeystore <your-android-cert>.p12 -deststoretype PKCS12 -srcalias <your-android-cert-alias>
 ----
 
-=== iOS
+== iOS
 
 Build Type:: Build type value to be used by xcodebuild
 Name:: The unique credential name to be used in jenkins
 Apple Developer Profile:: An xcode zip generated file that contains all required files (certificate, private key and provisioning profile) to sign an iOS app. For more information, see this documentation on exporting developer accounts in XCode.
 Apple Developer Profile Password:: The developer profile password to be used by jenkins when importing the developer profiles private key.
 
-=== Cordova
+== Cordova
 
 Platform:: The platform that the app will target.
 Build Type:: The build type value (debug or release). Depending on the platform selected, this may result in additional parameters to be required.

modules/ROOT/pages/digger/running-a-build.adoc

@@ -0,0 +1,28 @@
+
+//':context:' is a vital parameter. See: http://asciidoctor.org/docs/user-manual/#include-multiple
+:context: proc_building-a-mobile-app
+
+[id='{context}_proc_building-a-mobile-app']
+= Building a Mobile App
+
+To build a mobile app.
+
+. Log in to the OpenShift Console.
+
+. Browse to the *Project Overview* screen and find the {mobile-client} you want to build.
+
+. Click on the name of the {mobile-client} to open the details view.
+
+. From the *Builds* tab, select the mobile app you want to build click *Start Build*.
++
+NOTE: Expanding the build section will show the current status of this build.
+
+. Check the mobile app build status by expanding the mobile client box.
++
+NOTE: This box lists the last 5 builds for this client.
+
+. To view the mobile app as a pipeline build, from the left menu, click *Builds > Pipeline*.
++
+Each build step is displayed (along with the current step status: completed, error or running) based on the stages in your Jenkinsfile code.
+
+.  To view the full build log, click *view log* which redirects you to your Jenkins instance.

modules/ROOT/pages/mobile-cicd.adoc

@@ -2,7 +2,6 @@
 :toc:
 include::digger/index.adoc[leveloffset=1]
 include::digger/ref_terminology.adoc[leveloffset=+1]
-include::digger/ref_source-configuration.adoc[leveloffset=+1]
 [#setup]
 
 == Prerequisites
@@ -12,6 +11,15 @@ include::{partialsdir}/generic-provisioning-pre-req.adoc[]
 include::digger/provisioning.adoc[leveloffset=1]
 [#build-config]
 include::digger/proc_creating-a-build-configuration.adoc[leveloffset=1]
+[#jenkins]
+include::digger/proc_adding-a-jenkinsfile.adoc[leveloffset=1]
+[#building]
 include::digger/running-a-build.adoc[leveloffset=1]
+[#logs]
+include::digger/access-mobile-client-build-logs.adoc[leveloffset=1]
 [#deploy]
 include::digger/proc_deploying-a-mobile-app.adoc[leveloffset=1]
+[#clean]
+include::digger/cleaning-up-client-builds.adoc[leveloffset=1]
+include::digger/ref_source-configuration.adoc[leveloffset=+1]
+