Integrate the ADT CLI with a Build Pipeline
Overview
The AccelByte Development Toolkit (ADT) CLI provides a non-interactive mode that makes it easy to integrate it with build pipelines like Jenkins or GitLab.
This guide shows you the general workflow for integrating the ADT CLI with Jenkins or any other pipeline.
Create a new game version
Use ADT Web or the ADT CLI to create a new game version.
PS> ./BlackBoxCLI.exe version add --name <version name> --namespace <your game namespace> --apikey <the apikey> --game-project <G:\path\to\your_game_project_folder>
Here is an example of how to create a new version 1.100.20.99987 in the mygame namespace:
PS> ./BlackBoxCLI.exe version add --name 1.100.20.99987 --namespace mygame --apikey XXX123 --game-project G:\game\MyGame
This command creates a Blackbox.ini file in the <yourgame>/Config> folder. The ADT Unreal SDK reads the contents of that file and when a crash occurs, sends it to the ADT Backend.
Register a build
You must register a new build for each platform to upload the PDB files. You can have multiple platforms in a single version.
PS> ./BlackBoxCLI.exe build register --new --namespace <your game namespace> --apikey <the apikey> --game-project <path to gameproject> --platform-name <platform name> --platform-arch <platform architecture> --game-engine <path to engine root>
Here is an example when you upload Windows 64 bit PDB files:
PS> ./BlackBoxCLI.exe build register --new --namespace mygame --apikey XXX123 --game-project G:\game\MyGame --platform-name windows --platform-arch x64 --game-engine G:\GameEngine\UE4-425
This command needs a Blackbox.ini file to run. To learn how to create a BlackBox.ini file, follow the steps in the Create a New Game Version section at the start of this guide.
The command adds BuildId information to the BlackBox.ini file, which the ADT Backend uses to determine build and symbol information.
Build your game
The next step is to build your game, as shown in this example.
PS> G:\game\Engine\Build\BatchFiles\RunUAT.bat -ScriptsForProject="G:\game\MyGame\MyGame.uproject" BuildCookRun -project="G:\game\MyGame.uproject" -noP4 -clientconfig=Development -serverconfig=Development -nocompileeditor -ue4exe=UE4Editor-Cmd.exe -utf8output -platform=Win64 -build -cook -stage -package -pak -stagingdirectory=G:\output -compile -client -serverplatform=Win64 -CrashReporter -prereqs
Upload the PDB file
Use this command to upload your PDB file for the package build.
PS> ./BlackBoxCLI.exe upload --namespace <your game namespace> --apikey <the apikey> --game-project <path to gameproject> --game-engine <path to game engine root> --game-archive <path to packaged game>
This example shows what the parameters look like:
PS> ./BlackBoxCLI.exe upload --namespace mygame --apikey XXX123 --game-project G:\game\MyGame --game-engine G:\game --game-archive G:\game\packaged\game\exe\dir
Upload metadata (optional)
This step is optional, but doing this enables you to use the ADT CLI to upload metadata with your build. Metadata can be a log file, performance test result, automated test result, etc.
> ./BlackBoxCLI.exe build upload-metadata --type buildLog --namespace <your game namespace> --apikey <the apikey> --game-project G:\game\MyGame --directory <metadata dir path>
This example shows what the completed parameters look like:
> ./BlackBoxCLI.exe build upload-metadata --type buildLog --namespace mygame --apikey XXX123 --game-project G:\game\MyGame --directory G:\game\Engine\AutomationTool\Saved\Logs
Example of a Jenkins file setup
def FAILED_STAGE = "";
def CURRENT_VERSION = "";
pipeline {
agent {
node {
label 'windows-sdk'
}
}
stages {
stage('cleanup') {
steps {
bat '''
git clean -dfx
git reset --hard
'''
}
}
stage('Creating a new version') {
steps {
powershell '''
BlackBoxCLI.exe version add --name 1.100.20.99987 --namespace mygame --apikey XXX123 --game-project G:\game\MyGame
'''
}
post {
failure {
script {
FAILED_STAGE = "build";
}
}
}
}
stage('Registering a build') {
steps {
powershell '''
BlackBoxCLI.exe build register --new --namespace mygame --apikey XXX123 --game-project G:\game\MyGame --game-engine G:\game --platform-name windows --platform-arch x64
'''
}
post {
failure {
script {
FAILED_STAGE = "build";
}
}
}
}
stage('Build The Game') {
steps {
bat '''
G:\game\Engine\Build\BatchFiles\RunUAT.bat -ScriptsForProject="G:\game\MyGame\MyGame.uproject" BuildCookRun -project="G:\game\MyGame.uproject" -noP4 -clientconfig=Development -serverconfig=Development -nocompileeditor -ue4exe=UE4Editor-Cmd.exe -utf8output -platform=Win64 -build -cook -stage -package -pak -stagingdirectory=G:\output -compile -client -serverplatform=Win64 -CrashReporter -prereqs
'''
}
post {
failure {
script {
FAILED_STAGE = "build";
}
}
}
}
stage('Upload the PDB files') {
steps {
powershell '''
BlackBoxCLI.exe upload --namespace mygame --apikey XXX123 --game-project G:\game\MyGame --game-engine G:\game --game-archive G:\output\WindowsNoEditor
'''
}
post {
failure {
script {
FAILED_STAGE = "build";
}
}
}
}
stage('upload the logs file') {
steps {
powershell '''
BlackBoxCLI.exe version upload-metadata --type buildLog --namespace mygame --apikey XXX123 --game-project G:\game\MyGame --directory G:\game\Engine\AutomationTool\Saved\Logs
'''
}
post {
failure {
script {
FAILED_STAGE = "build";
}
}
}
}
}
post {
success {
script {
def message = ""
message = sh(returnStdout: true, script: 'git log -1 --pretty=%B').trim()
echo "jobName: ${JOB_NAME}"
echo "buildNumber: ${BUILD_NUMBER}"
echo "gitBranch: ${GIT_BRANCH}"
echo "buildURL: ${BUILD_URL}"
slackSend (channel: "game-pipeline", color: '36B37E', message: "<${env.BUILD_URL}console|Jenkin's Job ${env.BUILD_NUMBER}> *SUCCESSFUL* for `${env.JOB_NAME}` on branch `${env.GIT_BRANCH}` \n `${env.GIT_COMMIT}`: ${message} ")
}
}
failure {
script {
def message = ""
message = sh(returnStdout: true, script: 'git log -1 --pretty=%B').trim()
echo "jobName: ${JOB_NAME}"
echo "buildNumber: ${BUILD_NUMBER}"
echo "gitBranch: ${GIT_BRANCH}"
echo "buildURL: ${BUILD_URL}"
slackSend (channel: "game-pipeline", color: 'FF0000', message: "<${env.BUILD_URL}console|Jenkin's Job ${env.BUILD_NUMBER}> *FAILED* on Stage `${FAILED_STAGE}` \nProject: `${env.JOB_NAME}` \nBranch: `${env.GIT_BRANCH}` \nCommit: `${env.GIT_COMMIT}` \nMessage: `${message}` ")
}
}
}
}
Register or upload the PDB file
If you choose to register or upload your PDB file using the --editor build parameter, follow the steps below:
Register a build
If you want to upload the editor build or the UE4Editor.exe along with the PDB file, add the --editor-build parameter.
PS> ./BlackBoxCLI.exe build register --new --namespace <your game namespace> --apikey <the apikey> --game-project <path to gameproject> --platform-name windows --platform-arch x64 --game-engine <path to engine root> --editor-build
Here is an example for when you want to upload Editor Build 64 bit PDB files:
PS> ./BlackBoxCLI.exe build register --new --namespace mygame --apikey XXX123 --game-project G:\game\MyGame --platform-name windows --platform-arch x64 --game-engine G:\GameEngine\UE4-425 --editor-build
Upload the PDB file
You can also use the --editor-build option to upload the editor's PDB information. In this case, you don't need to specify the --game-archive argument.
PS> ./BlackBoxCLI.exe upload --namespace <your game namespace> --apikey <the apikey> --game-project <path to gameproject> --game-engine <path to game engine root> --editor-build
Here is an example after you've defined the value for the parameters:
PS> ./BlackBoxCLI.exe upload --namespace mygame --apikey XXX123 --game-project G:\game\MyGame --game-engine G:\game --editor-build