Deploy Applications Using GitHub Actions and Digital.ai Deploy

This how-to demonstrates how you can set up a GitHub Actions CI/CD pipeline to build, publish, and deploy your applications using Digital.ai Deploy.

What's the objective?

The objective is to build, publish, and deploy a simple Java application—github-actions-deploy-demo—to an Amazon EKS cluster—using:

• Gradle
• Deploy's GitHub action—github-actions-deploy
• Docker Hub
• Digital.ai Deploy

Once you have this setup in place, all you would be doing is pushing a code change to trigger a GitHub Actions build job and have your application built and deployed to your cloud environment using the github-actions-deploy GitHub action.

Prerequisites

• Digital.ai Deploy (24.3 or later)
• A GitHub account
• A Docker Hub account
• Gradle
• AWS CLI
• An Amazon account and an EKS cluster
• kubectl

What do you need?

• A Linux or Windows server (with root and Internet access) that has Digital.ai Deploy 24.3 (or later) installed
• An AWS account
• An Amazon EKS cluster
• AWS CLI and kubectl
• A Docker Hub account—to push every new version of the demo application you generate to the Docker Hub repository

What do you have?

We have created a github-actions-deploy-demo GitHub repository that you can fork for illustrating how this works. This repository hosts the following:

• A build-deploy.yml GitHub Actions workflow that automates the process of building, publishing, and deploying the application package to Digital.ai Deploy.
• A deployit-manifest.xml file that defines the structure and contents of the deployment package.
• A demo Java application—DemoApplication.java.
• A build.gradle file for building the Java application.

Here's a step-by-step that illustrates how to have your application deployed using Digital.ai Deploy and GitHub Actions.

Step 1—Create an Amazon EKS Cluster

note

For illustrative purposes, this topic deals with Amazon EKS. You can have your cluster in other cloud platforms such as GKE too.

1. Log on to your AWS account and gather the AWSAccessKeyId and AWSSecretKey.

   Create an access key if you do not have one already. For more information, see Managing access keys.

important

It is recommended to download and save the AWS access key file immediately after creating the access key as you cannot retrieve your Secret Access Key later.

2. Create an Amazon EKS Cluster. For more information, see Creating an Amazon EKS cluster.

3. Gather the following information about your Amazon EKS cluster and keep them handy. The values you gather for these properties are added to the values.xlvals file and are passed to the As-code YAML files while creating the Deploy configuration items.

   • Your Amazon account's AWSAccessKeyId and AWSSecretKey
   • The AWS region code (for example, eu-west-2) that hosts the EKS cluster
   • The EKS cluster's name
   • The API server endpoint URL
   • The Certificate Authority (CA) cert

   Here's an example Amazon EKS cluster and its configuration—qe-cluster.

   
   

   Cluster Name: qe-cluster

   
   

   

   
   

   Cluster Configuration

   
   

   

Step 2—Install the NGINX Ingress Controller

The next step is to install an NGINX ingress controller to provide external access to the Kubernetes services in your Amazon EKS cluster.

For more information about installing the Bitnami/NGINX ingress controller, see INSTALL BITNAMI/NGINX. While this how-to uses the Bitnami/NGINX, you can install any other flavor of NGINX too.

Configure a Domain Name for Your Amazon EKS Cluster Using Amazon Route 53

This is required to map the IP addresses of your NGINX ingress controllers to fully qualified domain names (FQDNs).

You must choose a FQDNs for the NGINX ingress controller and configure the domain name mapping for the ingress controller using Amazon Route 53.

Let's use the following FQDN for this tutorial—test ingress controller's FQDN: testdigitalai.xldevinfra.com

For more information about how to configure the FQDNs in Route 53, see Configuring Amazon Route 53 as your DNS service.

Step 3—Set up Your Digital.ai Deploy Servers

1. Log on to your Linux/Windows server as a root user.

2. Install Digital.ai Deploy.

   • You must have a database (including the database driver), PostgreSQL for example, installed and configured for use with Digital.ai Deploy

   Tip: If you want to install Deploy using Docker images:

   • Install Docker and Docker Compose
   • See Install Deploy.

3. Start your Digital.ai Deploy server and log on to it.

4. Fork the github-actions-deploy-demo repo GitHub repository and clone it.

5. Go to the forked repository in GitHub and enable GitHub Actions for the forked repository.

Step 4—Create an Environment and Infrastructure in Digital.ai Deploy

1. Log on to Digital.ai Deploy
2. Create an Environment and Infrastructure configuration items in Deploy.
3. Verify if the Environment and Infrastructure configuration items are created.
4. Check connection to the Amazon EKS cluster.

Step 5—Install and Configure AWS CLI and kubectl

1. Log on to your Linux/Windows server as a root user.

2. Install AWS CLI.

3. Run the following command to configure the AWS CLI. Enter the values when prompted

   $ aws configure
   AWS Access Key ID [None]: XXXXXEXAMPLEACCESSKEYIDXXXXXXXXXXX
   AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
   Default region name [None]: us-west-2
   Default output format [None]: json
   • For more information, see Quick configuration with aws configure.
   • By default, the AWS CLI uses the default profile. For illustrative purposes, let us use the default profile.

4. Install kubectl.

5. Configure the kubeconfig file with the EKS cluster's details.

   Here's a sample kubeconfig file:

   apiVersion: v1
   clusters:
   - cluster:
      certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUM1ekNDQWMrZ0F3SUJBZ0lCQURBTkJna3Foa2lHOXcwQkFRc0ZBREFWTVJNd0VRWURWUVFERXdwcmRXSmwKY201bGRHVnpNQjRYRFRJeE1EVXdNekEwTlRrd01Gb1hEVE14TURVd01UQTBOVGt3TUZvd0ZURVRNQkVHQTFVRQpBeE1LYTNWaVpYSnVaWFJsY3pDQ0FTSXdEUVlKS29aSWh2Y05BUUVCQlFBRGdnRVBBRENDQVFvQ2dnRUJBTXZICnR1alhCSE5NWDdWT0pSbVRKUFUyVkVib2E5S3psdkd5OFF6Q1VSR2dLY1E0QlRvclh2cmJ0MzY4Y0xoOEF0REEKOUQ2emExZFh2YW1IWkg1WG1ldWI1MCs3ZFRLSDVXQWdZeWlvM1hRak9vZWpBMzlUYUx3eU9CNVAzcWJRczlpSwpJN3VlbzlZKzNiUEdZbGVMa2RuelhhSE04bnNYRU1Wek4xQzhQdENTZVluQlZHQ3R1elVTd3pNWHZDS1NsS0tECmc4ZjUxMXViK3d5YllpOEVESVc2UjN6b2JWK200NUZrUHVCTXFQek9heEQxeHdqMTIzKzFkMFByWHNlRHBBYTEKeFIyVHVnRVd6ZEVDTTFtK3QzclQ4Z1BhVHRWWkJRUVp5dlVacXBPaHhnMFlyWTAvczRtUXZiOUlDbjhONkVjMwpoWis3b3BFaTgxRm0wRWw1UUZFQ0F3RUFBYU5DTUVBd0RnWURWUjBQQVFIL0JBUURBZ0trTUE4R0ExVWRFd0VCCi93UUZNQU1CQWY4d0hRWURWUjBPQkJZRUZIWXMxQlF4SWJxQ3kvMEpMS3BqR25HOFl1YW1NQTBHQ1NxR1NJYjMKRFFFQkN3VUFBNElCQVFBRlZDdjVhN0Q2L0tMdUdvaEM0aWJlcHkyZVprRCtNNFBCSjFoTWNYcS8vck53a284cwp0OW40WDJrcDh1L1lkOGhJZ1paODlzMmRvaVJEc0dOejRQNUFnbkU3RXhnTUYxSDV0ejFxSHpDVXp1dXdYbmJLCm9TWkhFRFdLKzhsc3ZjVVNkTUNtZ2RPUDNza1dQNjNJazNqcFlwQUNnUUxYemkxMmNQTVBuVEtPekVULzNQcmIKYmV5ZzJGZ1pCWW0rVE15Wi93ektGb2hGV3Z1WW1oSWFHUkRkeUpENmZBdWFKOG9rYTFnVXBKZ0pqTkhOWmJ6dgppNmMyVTIwS0M1aUhiTFdkRnkvb3YxaktYMzBUMk9qV0wxSG13TzR6SHZ2UjFHLy84RGxkNEpSQnVha283S1FhCk5qQnE2R1F6bEdsT2FScXFPVXNzSC9kUXRNdEFvbk1KeVpwWgotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
      server: https://A9C912D6785C0AD9C144C7056440E559.gr7.eu-west-2.eks.amazonaws.com
   name: arn:aws:eks:eu-west-2:274820375133:cluster/qe-cluster
   contexts:
   - context:
      cluster: arn:aws:eks:eu-west-2:274820375133:cluster/qe-cluster
      user: arn:aws:eks:eu-west-2:274820375133:cluster/qe-cluster
   name: arn:aws:eks:eu-west-2:274820375133:cluster/qe-cluster
   current-context: arn:aws:eks:eu-west-2:274820375133:cluster/qe-cluster
   kind: Config
   preferences: {}
   users:
   - name: arn:aws:eks:eu-west-2:274820375133:cluster/qe-cluster
   user:
      exec:
         apiVersion: client.authentication.k8s.io/v1alpha1
         args:
         - --region
         - eu-west-2
         - eks
         - get-token
         - --cluster-name
         - qe-cluster
         command: aws

6. Verify the kubectl configuration by getting your EKS cluster state, for example.

   kubectl cluster-info

Step 6—Create Amazon EKS Namespaces

With AWS CLI and kubectl utilities installed and configured, let us now create a namespace, test, on the EKS cluster.

Run the following commands to create two namespace—test

kubectl create namespace test

Step 7—Review the Application Deployment Manifest File

Now that your Amazon EKS cluster is set up and your Digital.ai Deploy instance is running, you can review your deployment manifest file and make changes to the application version, for example.

1. Go to your forked repository github-actions-deploy-demo on GitHub.
2. The deployit-manifest.xml file is included. This file contains the configuration for the deployment package.

<?xml version="1.0" encoding="UTF-8"?>
<udm.DeploymentPackage version="2.0" application="appForAction">
  <application />
  <orchestrator />
  <deployables>
    <file.Archive name="/demoJar" file="/build/libs/demo-0.0.1.jar">
      <targetPath>/tmp</targetPath>
      <targetFileName>demo-0.0.1.jar</targetFileName>
    </file.Archive>
  </deployables>
  <applicationDependencies />
  <dependencyResolution>LATEST</dependencyResolution>
  <undeployDependencies>false</undeployDependencies>
  <templates />
  <boundTemplates />
</udm.DeploymentPackage>

• udm.DeploymentPackage version: Defines the overall deployment package and its metadata. In the manifest file, version="2.0" indicates that this is the first version of the package and application - 'appForAction'.
• deployables: Specifies the artifacts to be deployed. The demoJAR file is deployed to the /tmp directory.
• applicationDependencies: Placeholder for application dependencies.
• dependencyResolution: Specifies how dependencies should be resolved. Here it is set to LATEST.
• undeployDependencies: Indicates whether to undeploy dependencies during undeployment. Set to false.
• templates: Placeholder for deployment templates.

Step 8—Add GitHub Actions Secrets

1. Go to Settings > Secrets of your forked GitHub repository and add the following secrets.

   • SERVERURL—the URL of the Digital.ai Deploy server

   • USERNAME—the username for authenticating with Digital.ai Deploy

   • PASSWORD—the password for authenticating with Digital.ai Deploy

   • VERSIONNUMBER—the deployment package version number

important

The Deploy server must have a public IP address assigned to it. If you are trying this out for testing purposes and if you run the Deploy server in your localhost (in the absence of public IPs), use utilities such as ngrok to create a tunnel to expose your localhost (ports: 4516 and 5516 for Deploy and Release respectively) to the internet.

Step 9—Review the GitHub Actions Workflow

Review the build-deploy.yml GitHub Actions workflow file. This file includes steps to:

• Checkout the code: Uses the actions/checkout@v2 action to clone the repository.
• Set up JDK 17: Uses the actions/setup-java@v2 action to set up OpenJDK 17.
• Grant Execute Permissions to Gradlew: Runs a shell command to make the Gradle wrapper executable.
• Build with Gradle: Executes the Gradle build command.
• Create, Publish, and Deploy Package: Uses the digital-ai/github-actions-deploy@v1.0.0 action to create, publish, and deploy the package.

Here's the build-deploy.yml file.

name: Build and Deploy Package

on: [workflow_dispatch]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Set up JDK 17
        uses: actions/setup-java@v2
        with:
          distribution: 'adopt'
          java-version: '17'

      - name: Grant execute permissions to gradlew
        run: chmod +x ./gradlew

      - name: Build with Gradle
        id: build
        run: ./gradlew build --no-daemon --console=plain

      - name: Create Publish and Deploy Package
        id: deploy
        uses: digital-ai/github-actions-deploy@v1.0.0
        with:
          serverUrl: ${{ secrets.SERVERURL }}
          username: ${{ secrets.USERNAME }}
          password: ${{ secrets.PASSWORD }}
          manifestPath: '/deployit-manifest.xml'
          action: 'create_publish_deploy'        
          outputPath: '/outputdar'               
          versionNumber: ${{ secrets.VERSIONNUMBER }}
          packageName: 'appForAction-1.0.dar'    
          environmentId: 'Environments/envForAction'
          rollback: 'yes'

note

The above workflow is triggered manually (workflow_dispatch). You can also trigger workflows through external events, scheduled events, or GitHub repository events (e.g., push, pull request, issue creation).

The action allows for customizable inputs, which you can modify according to your specific requirements:

Name	Description	Required	Default
serverUrl	The URL of the Digital.ai Deploy server.	Yes
username	The username for authenticating with Digital.ai Deploy.	Yes
password	The password for authenticating with Digital.ai Deploy.	Yes
action	Action to perform: create, publish, deploy. Supported actions are: create_publish, publish_deploy, create_publish_deploy.	No	create_publish_deploy
manifestPath	The path to the deployit-manifest.xml file. Required for create_publish, create_publish_deploy actions.	Yes
outputPath	The path for storing the newly created DAR package. Required for create_publish, create_publish_deploy actions.	Yes
packageName	Optional. The name of the newly created DAR package.	No	package.dar
versionNumber	Optional. Specify a version number to set in your manifest file.	No
darPackagePath	The path to the DAR package. Required for publish_deploy action.	Yes*
environmentId	ID of the target environment in Digital.ai Deploy. Required for publish_deploy, create_publish_deploy actions.	Yes*
rollback	Optional. Invoke a rollback in case of deployment failure.	No	false

You are all set. Create a new version of the demo Java application, push the changes to the repository, and trigger the GitHun Actions workflow to deploy the application to the Amazon EKS cluster.

Step 10—Run the GitHub Actions Workflow

1. Navigate to the Actions tab in your GitHub repository.
2. Select the Build and Deploy Package workflow.
3. Click the Run workflow.

Step 11—View the GitHub Actions Build Job and Steps in the Console

After triggering the workflow, you can view the logs for the workflow job in the console:

Step 12—Verify in Deploy

After running the workflow successfully, you can verify the deployment in Deploy. To do so:

1. Log in to Digital.ai Deploy.
2. Go to Applications and expand it.
3. Verify that appForAction has been deployed to the specified target environment, envForAction.