gh-agent-task

List the most recent agent tasks

$ gh [[agent|agent-task]] list

$ gh [[agent|agent-task]] create "[Improve the performance of the data processing pipeline]"

$ gh [[agent|agent-task]] create [[-F|--from-file]] [path/to/file]

$ gh [[agent|agent-task]] view [session_id|pr_number|url|branch]

$ gh [[agent|agent-task]] view --log [session_id|pr_number|url|branch]

gh-agent-task [OPTIONS] <task-definition-path>

--config
    Specifies the path to a JSON or YAML file containing the detailed definition of the task to be executed. This file typically includes script content, environment variables, working directory, and other execution parameters.

--working-directory
    Sets the working directory where the task's commands and scripts will be executed. This is usually the repository checkout directory.

--log-level
    Defines the verbosity of the logging output for the task execution (e.g., 'debug', 'info', 'warn', 'error'). This aids in troubleshooting workflow failures.

--trace
    Enables detailed tracing for the task execution, providing more granular insights into its operations and sub-processes.

--help
    Displays a help message with available options and exits.

--version
    Shows the version information of the gh-agent-task utility and exits.

gh-agent-task is an internal utility command primarily used by the GitHub Actions self-hosted runner application. Its core function is to execute a specific task or step within a GitHub Actions workflow job. When the runner agent receives a job assignment from the GitHub Actions service, it leverages this command (or a similar internal mechanism) to spin up a process that performs the actual work defined in a workflow step, such as running scripts, installing dependencies, or executing actions. This command is not intended for direct invocation by users from the command line but rather forms a crucial component of the runner's execution engine, providing the isolation and execution context for each step of a job.

This command is an internal component of the GitHub Actions self-hosted runner application. It is not designed for direct user interaction or standalone execution outside of the runner's context. Attempting to run it directly may lead to unexpected behavior or errors as it relies on specific environmental conditions and configurations set up by the runner agent. Users should interact with GitHub Actions workflows through the GitHub web interface or GitHub CLI, not by invoking this low-level utility.

gh-agent-task executes within a tightly controlled environment established by the main runner process. This includes setting up necessary environment variables (e.g., GITHUB_TOKEN, RUNNER_TEMP), path configurations, and potentially container isolation (e.g., Docker) if the job specifies a container image for execution. It ensures that each step runs with the correct prerequisites and isolation from other jobs or system processes.

As this command is responsible for executing code provided by GitHub Actions workflows, it operates under the security model of the self-hosted runner. It's crucial for administrators to understand the implications of running untrusted code on their machines, as gh-agent-task is the direct executor of potentially malicious scripts. Best practices include running self-hosted runners on dedicated, isolated machines, and carefully reviewing workflow definitions, especially those from external repositories.

The gh-agent-task utility (or its functional equivalent) has been an integral part of the GitHub Actions self-hosted runner's architecture since its inception. It evolved alongside the runner application, adapting to new features and execution models introduced in GitHub Actions. Its primary design goal is to provide a robust and isolated execution environment for workflow steps, ensuring consistency and reliability across diverse self-hosted environments. Its development tracks the evolution of the GitHub Actions platform, including support for different operating systems and execution methods.

gh(1), bash(1), sh(1), docker(1), git(1)