Using Github Actions to Deploy a CAP App (MTA)

[Christopher_Ketzler]

Software development is not always easy. After developing sophisticated coding, many iterations of discussions with the business department, and of course debugging, you also need to take care of Continuous Integration and Continuous Delivery (CI/CD - CI/CD - Wikipedia). The CAPire documentation (SAP Capire - Deploy using CI/CD Pipelines) provides an approach based on a Docker image, which is marked as not working (Github CAP sample). So, I want to provide a basic approach from scratch.

Github Actions helps you automate CI/CD tasks with pipelines. Typical tasks include linting, building, testing, or deploying repositories after pushing code to a central Github repository. Pipelines in Github actions are called workflows. Workflows are triggered by certain events in the repository, such as pushing code or creating a new release. After the workflow is triggered, one or more jobs are executed. A job is assigned to a runner, which defines the virtual machine that will execute the job, and one or more execution steps. A step is either the execution of a predefined action or a bash command. If no execution order is defined, Github will execute all jobs in parallel. Actions are reusable workflow steps. The marketplace offers many predefined actions that you can reference in your workflow.

Creating a BTP deployment workflow

Perquisitions:

• Set up a SAP BTP subaccount. Activate Cloud Foundry and map the subaccount in your Hana Cloud instance.
• You need a deployable CAP project with a MTA descriptor. The easiest way is to create a sample CAP project (cds init and cds add sample /  tiny-sample) and follow the deployment guide: Deploy to Cloud Foundry | CAPire
• Register at GitHub and create a new repository for your CAP project.

Steps:

1. Add secrets and variables to your Github repository.

Avoid exposing readable credentials in your workflow definitions. Secrets and variables defined in the repository settings and resolved during execution. Access your git repository and click the “Settings” tab. Navigate to the “Secrets and variables”>”Actions” section. Add the BTP credentials to the “Secrets” tab and the remaining information to the “Variables” tab as described below:

Secrets:

• CF_USER = The user executing the deployment.
• CF_PASSWORD = The user password.

Variables:

• CF_API_URL = Find the “API Endpoint” on the subaccount overview page.
• CF_ORG = The “Org Name” is displayed on the overview page of the target subaccount.
• CF_SPACE = The target space name.

1. Create the Github workflow.

Github Actions workflows are defined in the repository to which they apply. Create a new folder called “.github” in your root and another called “workflows” within the first one. Here we will add the workflow configuration and scripts. Since workflows are defined as yml files, add a new file named “on_push.yml” to the workflows folder.

1. Configure the workflow.

Now we want to define a workflow that includes one step to deploy your app. The workflow definition consists of a name, run-name, trigger event, and jobs:  

• The name is displayed in the "Actions" tab on Github.
• The on property defines the trigger event. If necessary you can also add a branch name, meaning that only an event on a specific branch will triggers the workflow.
• The jobs section lists all jobs that will executed in this workflow.

 A Job consists of:

• A name that is displayed on the Github website.
• The runs-on property, which assigns the runner to the job. A runner is a virtual machine used during execution. Below we use the latest version of ubuntu.
• The steps section lists the execution steps of this job.

Steps are usually defined by the keyword “uses” or “run”.  “Uses”  invokes a predefined action. Common examples are “actions/checkout@v4” and “setup-node@v4”. The checkout action checks out the project and allows you to run bash commands against the project. The second one installs node.js, which means that we can then use node and npm commands using the keyword “run”. The “run” keyword executes terminal commands, such as bash or npm statements, on the runner.

The workflow below consists of one job, which runs a bash script that deploys the repository to SAP BTP. Before running the deployment script we need to prepare the project and make the script executable by running a chmod command. When the bash script is invoked, variables and secrets, defined in the repository settings, are provided as environment variables.

name: SAP Bookshop - Release (Deploy)
run-name: Release Bookshop
on:
  push:
    branches:
      - "main"
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Make the script files executable
        run: chmod +x ./.github/workflows/scripts/btp_deploy.sh
      - name: Run a script
        env:
          cf_user: ${{ secrets.CF_USER }}
          cf_password: ${{ secrets.CF_PASSWORD }}
          cf_api_url: ${{vars.CF_API_URL}}
          cf_org: ${{vars.CF_ORG}}
          cf_space: ${{vars.CF_SPACE}}
        run: ./.github/workflows/scripts/btp_deploy.sh

Optional: You can add additional jobs such as test, test build, or linter. For example, you might want to run tests first. If you want one job to run before another, you can add the "needs: <jobname>" property. The code snippet below needs a package.json script "test" to run the test.

test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run test

1. Add the deployment script.

Create a new subfolder “scripts” in the “workflows” folder, add a new file “btp_deploy.sh” and copy the script below. Basically, it installs the Cloud Foundry client with the MTA plugin, builds the MTA, connects to the target space, and deploys the MTA archive. Environment variables prefixed with "$". You defined the variables and secrets in the first step. In the yml you have mapped them to the environment variables used in the script. Push the changes to your remote repository.

#!/bin/bash
set -e

echo '############## Get cf Client ##############'
wget -q -O - https://packages.cloudfoundry.org/debian/cli.cloudfoundry.org.key | sudo apt-key add -
echo "deb https://packages.cloudfoundry.org/debian stable main" | sudo tee /etc/apt/sources.list.d/cloudfoundry-cli.list
sudo apt-get update
sudo apt-get install cf8-cli

echo '############## Check Installation ##############'
cf -v

echo '############## Install Plugins ##############'
cf add-plugin-repo CF-Community https://plugins.cloudfoundry.org
cf install-plugin multiapps -f
cf install-plugin html5-plugin -f

echo '############## Build ##############'
npx mbt build --mtar app.mtar

echo '############## Authorizations ##############'
cf api $cf_api_url
cf auth $cf_user "$cf_password"

echo '############## Deploy ##############'
cf target -o $cf_org -s $cf_space
cf deploy mta_archives/app.mtar -f

Alternatively, you can use a predefined action (e.g. SAP BTP Action · Actions · GitHub Marketplace). But keep in mind that there is no SAP or Github authorized or maintained action for this.

Your ".github" folder should look like this.

1. Test the workflow,

Make one or more changes to your repository (e.g. add something to your Readme) and push the changes to Github. A new workflow should be triggered and be listed in the “Actions” Tab. Click on the workflow and check the jobs. A successful job is marked green and running one yellow.

You can check the jobs and logs. Press on the deploy job.

After the workflow changed its status into green. You can the deploy app in your BTP space.

(Optional) Make the workflow reusable

Usually you are not interested in copying  the same workflow into every project and keeping them synchronized. Github allows you to reuse workflows by defining template workflows in a separated repository. These templates can be referenced in other projects.

Link: Reusing workflows - GitHub Docs

[MioYasutake]

@Christopher_Ketzler 

Great blog! While I have used the predefined action before, I hadn't thought of creating my own script instead. Thank you for sharing this.