# Return Git deployment task status

This function retrieves the status of deployment tasks. Before deployment, repositories must meet the following requirements:
  * A valid checked-in .cpanel.yml file in the top-level directory.
  * One or more local or remote branches.
  * A clean working tree.

If a repository does not meet these requirements, the system will not display deployment information. Also, it will disable deployment functionality. For more information, read our Guide to Git™ - Deployment documentation.

Important:

The system logs messages for this function in the ~/.cpanel/logs/vc_TIMESTAMP_git_deploy.log file, where TIMESTAMP represents the time in Unix epoch time.

Endpoint: GET /VersionControlDeployment/retrieve
Version: 11.138.0.10
Security: BasicAuth

## Response 200 fields (application/json):

  - `apiversion` (integer)
    The version of the API.
    Example: 3

  - `func` (string)
    The name of the method called.
    Example: "retrieve"

  - `module` (string)
    The name of the module called.
    Example: "VersionControlDeployment"

  - `result` (object)

  - `result.data` (array)
    An array of objects containing deployment task data.

  - `result.data.deploy_id` (integer)
    The deployment ID number.
    Example: 13

  - `result.data.log_path` (string)
    The absolute path to the task's log file.
    Example: "/home/user/.cpanel/logs/vc_1525289448.759720_git_deploy.log"

  - `result.data.repository_root` (string)
    The aboslute path to the cPanel-managed repository directory.
    Example: "/home/username/example"

  - `result.data.repository_state` (object)
    An object containing information about the repository's state at the time of deployment.

  - `result.data.repository_state.author` (string)
    The most-recent commit's author's name and email address as they exist in the user's Git configuration files.
    Example: "Jane Doe <jane.doe@example.com>"

  - `result.data.repository_state.branch` (string)
    The repository's current branch.
    Example: "master"

  - `result.data.repository_state.date` (integer)
    The timestamp for the most-recent commit, in Unix time format.
    Example: 1410277881

  - `result.data.repository_state.identifier` (string)
    The identifier (SHA-1 value) for the most-recent commit.
    Example: "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12"

  - `result.data.repository_state.message` (string)
    The commit message.
    Example: "This is a commit."

  - `result.data.sse_url` (string)
    The SSE interface to track the progress of the deployment process.
    Example: "/sse/UserTasks/B3A27B96-51F7-11E8-92E3-CC90C4F823F0"

  - `result.data.task_id` (string)
    The [Task Queue](https://go.cpanel.net/whmdocsTaskQueueMonitor) system's task ID number.
    Example: "00000000/5aea11e886a5d8"

  - `result.data.timestamps` (object)
    An object containing timestamps for the deployment process.

  - `result.data.timestamps.active` (string)
    The time at which the system started the deployment process, in Unix time format.
    Example: "1525289448.83553"

  - `result.data.timestamps.canceled` (string)
    The time at which the system cancelled the deployment process, in Unix time format.

Note:

* The function only returns this value if the system cancelled the deployment process.
* The system logs messages for this function in the ~/.cpanel/logs/vc_TIMESTAMP_git_deploy.log file, where TIMESTAMP represents the Unix timestamp.
    Example: "1525289448.83553"

  - `result.data.timestamps.failed` (string)
    The time at which the deployment process failed, in Unix time format.

Note:

* The function only returns this value if the deployment process failed.
* The system logs messages for this function in the ~/.cpanel/logs/vc_TIMESTAMP_git_deploy.log file, where TIMESTAMP represents the Unix timestamp.
    Example: "1525289448.83553"

  - `result.data.timestamps.queued` (string)
    The time at which the deployment process entered the task queue, in Unix time format.
    Example: "1525289448.83553"

  - `result.data.timestamps.succeeded` (string)
    The time at which the deployment process finished successfully, in Unix time format.

Note:

 The function only returns this value if the deployment process succeeded.
    Example: "1525289448.83553"

  - `result.errors` (array,null)
    List of errors if the API failed.

  - `result.messages` (array,null)
    List of messages generated by the API.

  - `result.metadata` (object)

  - `result.status` (integer)
    - 1 - Success
- 0 - Failed: Check the errors field for more details.
    Enum: 0, 1

  - `result.warnings` (array,null)
    List of warnings generated by the API. Warnings describe non-critical failures or other problematic conditions noted while running a API.