Creating a Task Configuration

This is an introduction to githubTaskManager.json config. If you are already familiar how tasks are structured and executed, and want a reference guide to supported tasks and options, please see: Structure of .githubTaskManager.json

The GitHub Task Manager uses a configuration file in each repository to determine what actions to take. This file is called .githubTaskManager.json by default, and is branched with your code so that you can take branch specific actions.

The contents of this file are a JSON object defining 'tasks' to be performed by the GTM agent, which can include Jenkins jobs, TeamCity builds, Docker commands, HttpRequests, Ping tests, and other tasks defined by the user in an 'Executor'.

An example configuration file is shown below. Note that tasks can themselves also contain an array of 'tasks', which will be executed after the main task has completed successfully.

{
    "pull_request": {
        "tasks": [
            {
                "executor": "Jenkins",
                "context": "build and deploy",
                "options": {
                    "jobName": "BUILD_DEPLOY_ARTIFACT",
                    "parameters": {
                        "environment": "development",
                        "artifact": "develop"
                    }
                },
                "tasks": [
                    {
                        "executor": "Docker",                        
                        "context": "active security scan",
                        "options": {
                            "parameters": {
                                "target": "https://hostname",
                                "image": "owasp/zap2docker-stable",
                                "command": ["zap.sh"],
                                "proxyPort": "8080"
                            }
                        }
                    },
                    {
                        "executor": "TeamCity",                        
                        "context": "accessibility",
                        "options": {
                            "jobName": "EXECUTE_A11Y",
                            "parameters": {
                                "environment": "development",
                                "tags": [
                                    "@a11y"
                                ]
                            }
                        }
                    }
                ]
            }
        ]
    }
}

In this configuration file, we can see three tasks. The first task, calls a Jenkins job to build and deploy an asset. This task has two subtasks, which will be executed in parallel once the build and deploy task completes - one to run a pentest, and one to perform an accessibility audit.

Child tasks can nest tasks infinitely, allowing for build chains to be created if desired. If a given task fails, its subtasks will not be executed. A comment will be added to the pull request to notify you of the failure.

For details of supported tasks and options, please see: Structure of .githubTaskManager.json