Merge pull request #119 from morphis/add-gh-action

feat: explain how to use the github action

howto/install-appliance/install-on-github.md

@@ -0,0 +1,52 @@
+(howto-install-appliance-github)=
+# How to install the appliance within a GitHub Action workflow
+
+For use within a [GitHub Action workflow](https://github.com/features/actions), a simple action named [`canonical/anbox-cloud-github-action`](https://github.com/canonical/anbox-cloud-github-action) is available. This action can be easily integrated into existing workflows and it will install and configure the Anbox Cloud Appliance for direct use on a GitHub runner.
+
+## Prerequisites
+
+* A repository on GitHub which can host GitHub Action workflows
+* The token for your Ubuntu Pro subscription
+
+## Create a new workflow
+
+One example of where this GitHub Action could be helpful is when setting up a new workflow to run integration tests for an Android application. In this case, the action can be used as one of the first steps before the actual test is executed. The example workflow below implements the following steps:
+
+1. Set up Anbox Cloud
+2. Create a new Android 13 instance and configure it to allow external ADB access
+3. Connect the instance to ADB running on the host of the runner
+4. Perform a simple test to check the `ro.product.model` property for a specified value
+
+The workflow runs only on `push` trigger because access to a repository secret is required, which should not be granted on pull requests for security reasons. See [here](https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/) for more details.
+
+```yaml
+name: Run integration tests
+on: push
+jobs:
+  run-tests:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Setup Anbox Cloud
+      uses: canonical/anbox-cloud-github-action@main
+      with:
+        channel: 1.23/stable
+        ubuntu-pro-token: ${{ secrets.UBUNTU_PRO_TOKEN }}
+    - name: Create Android instance
+      id: create-instance
+      run: |
+        set -x
+        id="$(amc launch -r -s adb jammy:android13:amd64)"
+        amc wait -c status=running "$id"
+        echo "id=$id" >> "$GITHUB_OUTPUT"
+    - name: Access Android over ADB
+      run: |
+        sudo apt install -y adb
+        id=${{ steps.create-instance.outputs.id }}
+        addr="$(amc show "$id" --format=json | jq -r .network.address)"
+        adb connect "$addr":5559
+    - name: Run tests
+      run: |
+        test "$(adb shell getprop ro.product.model)" = Anbox
+```
+
+Alternatively, you can also integrate the execution of actual integration tests in the test step. As the Android instance is connected over ADB, you can perform any operation as with any other connected Android device.

howto/install-appliance/landing.md

@@ -3,9 +3,9 @@
 
 The Anbox Cloud Appliance provides a deployment of Anbox Cloud to a single machine. This offering is well suited for initial prototype and small scale deployments.
 
-The guides in this section describe how to install the Anbox Cloud Appliance on different cloud platforms. There is a difference between the full Anbox Cloud installation and the Anbox Cloud Appliance (see {ref}`sec-variants`). This section focuses on the **Anbox Cloud Appliance**. For instructions on how to install **Anbox Cloud**, see {ref}`howto-install-anbox-cloud`.
+The guides in this section describe how to install the Anbox Cloud Appliance on different cloud and CI/CD platforms. There is a difference between the full Anbox Cloud installation and the Anbox Cloud Appliance (see {ref}`sec-variants`). This section focuses on the **Anbox Cloud Appliance**. For instructions on how to install **Anbox Cloud**, see {ref}`howto-install-anbox-cloud`.
 
-We strongly recommend that you follow the {ref}`tut-installing-appliance` tutorial before you install the appliance on a cloud platform. The tutorial guides you through installing the appliance on a machine dedicated to Anbox Cloud and makes you familiar with the installation process and the general concepts of the Anbox Cloud Appliance.
+We strongly recommend that you follow the {ref}`tut-installing-appliance` tutorial before you install the appliance on a cloud or CI/CD platform. The tutorial guides you through installing the appliance on a machine dedicated to Anbox Cloud and makes you familiar with the installation process and the general concepts of the Anbox Cloud Appliance.
 
 Also, see {ref}`ref-requirements` before you start your installation.
 
@@ -20,12 +20,17 @@ Other clouds are also supported, but the Anbox Cloud Appliance is not available
 * For [Azure](https://azure.microsoft.com/) : {ref}`howto-install-appliance-azure`
 * For [Google Cloud](https://cloud.google.com/) : {ref}`howto-install-appliance-google-cloud`
 
-For all other cloud platforms, follow the steps detailed in {ref}`tut-installing-appliance`.
+## Supported CI/CD platforms
+
+The Anbox Cloud Appliance is currently available on the following CI/CD platforms:
+
+* {ref}`howto-install-appliance-github`
 
 ```{toctree}
 :hidden:
 
 Install on AWS <install-on-aws>
 Install on Azure <install-on-azure>
 Install on Google Cloud <install-on-google-cloud>
+Install on GitHub <install-on-github>
 ```