github-comment

https://suzuki-shunsuke.github.io/github-comment
Admin
A CLI tool to create and hide GitHub comments via the GitHub REST API. It improves CI user...
Tokens:7,927
Snippets:52
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Define comment templates in github-comment.yaml

Source: https://suzuki-shunsuke.github.io/github-comment/getting-started

Example `github-comment.yaml` configuration file demonstrating how to define multiple named templates (`default`, `hello`) for the `post` subcommand. These templates use Go's `text/template` syntax, allowing dynamic content based on context.

```YAML
post:
  default:
    template: |
      {{.Org}}/{{.Repo}} test
  hello:
    template: |
      hello world
```

--------------------------------

### github-comment CLI Subcommands Overview

Source: https://suzuki-shunsuke.github.io/github-comment/getting-started

Overview of the main subcommands provided by the `github-comment` command-line tool, detailing their primary functions and available parameters for the `post` subcommand.

```APIDOC
github-comment subcommands:

init
  - Description: Generates a configuration file template.

post
  - Description: Creates a comment on a GitHub Pull Request or Commit.
  - Parameters:
    - -token <token>: GitHub personal access token (optional, can use GITHUB_TOKEN/GITHUB_ACCESS_TOKEN env vars).
    - -org <org>: GitHub organization name.
    - -repo <repo>: GitHub repository name.
    - -pr <number>: Pull Request number (for PR comments).
    - -sha1 <hash>: Commit SHA1 hash (for commit comments).
    - -template <text>: Inline template content (overrides config).
    - -template-key (-k) <key>: Key of a predefined template in the configuration file.

exec
  - Description: Executes a shell command and creates a comment based on the command's result.

hide
  - Description: Hides existing pull request or issue comments.
```

--------------------------------

### Example execution of github-comment exec with a successful command

Source: https://suzuki-shunsuke.github.io/github-comment/getting-started

This shell command demonstrates how to invoke `github-comment exec` to run a simple bash command (`echo foo; echo bar >&2; echo zoo`). It targets a specific GitHub repository and pull request, using the 'hello' configuration key. The output shows the combined stdout and stderr from the executed bash command.

```Shell
$ github-comment exec -org suzuki-shunsuke -repo github-comment -pr 1 -k hello -- bash -c "echo foo; echo bar >&2; echo zoo"
bar
foo
zoo
```

--------------------------------

### Post a comment using a named template from config

Source: https://suzuki-shunsuke.github.io/github-comment/getting-started

Illustrates how to use the `github-comment post` subcommand with the `-template-key` (or `-k`) argument to select a predefined template from the `github-comment.yaml` configuration file. If neither `-template` nor `-template-key` is set, the `default` template is used.

```Shell
$ github-comment post -k hello
```

--------------------------------

### github-comment exec Command Line Interface and Configuration Reference

Source: https://suzuki-shunsuke.github.io/github-comment/getting-started

Comprehensive documentation for the `github-comment exec` command-line tool and its associated YAML configuration. This command executes an arbitrary shell command and posts its output to a GitHub pull request comment, with extensive options for conditional commenting and templating.

```APIDOC
github-comment exec -org <org> -repo <repo> -pr <pr_id> -k <key> -- <command>

Parameters:
  -org <org>: (Required) GitHub organization name.
  -repo <repo>: (Required) GitHub repository name.
  -pr <pr_id>: (Required) Pull request ID.
  -k <key>: (Required) Configuration key referencing an `exec` block (e.g., `hello`).
  --: (Required) Separator indicating the start of the command to be executed.
  <command>: (Required) The shell command to execute.

YAML Configuration Structure (`exec.<key>`):
exec:
  <key>:
    - when: <condition>
      template: |
        <Go template string>
      dont_comment: <boolean_condition>

Configuration Fields:
  <key>: A user-defined string identifier for this execution block (e.g., `hello`).
  when: (Optional) A Go template condition that must evaluate to true for the comment to be considered for creation.
    Available variables: `ExitCode` (integer), `Stdout` (string), `Stderr` (string), `CombinedOutput` (string), `Command` (string).
    Examples: `true`, `ExitCode != 0`, `ExitCode == 0`.
  template: (Optional) A multi-line Go template string defining the content of the GitHub comment.
    Available variables: `ExitCode`, `Command`, `Stdout`, `Stderr`, `CombinedOutput`.
    Example: `exit code: {{.ExitCode}}\nStdout:\n{{.Stdout}}`.
  dont_comment: (Optional) A Go template condition that, if true, prevents the comment from being created, overriding `when`.
    Available variables: Same as `when`.
    Example: `ExitCode != 0`.
```

--------------------------------

### Example execution of github-comment exec with a failing command

Source: https://suzuki-shunsuke.github.io/github-comment/getting-started

This shell command illustrates `github-comment exec` running a `curl` command that intentionally fails (HTTP 404 Not Found). It demonstrates how the tool captures the error output and exit status (22), which would trigger a comment based on a `when: ExitCode != 0` condition in the configuration.

```Shell
$ github-comment exec -org suzuki-shunsuke -repo github-comment -pr 1 -k hello -- curl -f https://github.com/suzuki-shunsuke/not_found
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
curl: (22) The requested URL returned error: 404 Not Found
exit status 22
```

--------------------------------

### Post a comment to a GitHub Commit

Source: https://suzuki-shunsuke.github.io/github-comment/getting-started

Shows how to use the `github-comment post` subcommand to add a comment to a specific commit, identified by its SHA1 hash, organization, and repository. The template content is 'test'.

```Shell
$ github-comment post -org suzuki-shunsuke -repo github-comment -sha1 36b1ade9740768f3645c240d487b53bee9e42702 -template test
```

--------------------------------

### Initial github-comment exec YAML configuration with full output template

Source: https://suzuki-shunsuke.github.io/github-comment/getting-started

This YAML configuration block defines the 'hello' execution rule for `github-comment exec`. It specifies a `when: true` condition, meaning the comment is always created, and provides a detailed Go template to display the executed command's exit code, command string, standard output, standard error, and combined output within the GitHub comment.

```YAML
exec:
  hello:
    - when: true
      template: |
        exit code: {{.ExitCode}}

        ```
        $ {{.Command}}
        ```

        Stdout:

        ```
        {{.Stdout}}
        ```

        Stderr:

        ```
        {{.Stderr}}
        ```

        CombinedOutput:

        ```
        {{.CombinedOutput}}
        ```
```

--------------------------------

### Install github-comment via Homebrew, Scoop, Aqua, or Go

Source: https://suzuki-shunsuke.github.io/github-comment/install

Provides commands to install the `github-comment` tool using popular package managers like Homebrew, Scoop, and Aqua, or by building directly from source using Go.

```Shell
brew install suzuki-shunsuke/github-comment/github-comment
```

```Shell
scoop bucket add suzuki-shunsuke https://github.com/suzuki-shunsuke/scoop-bucket
scoop install github-comment
```

```Shell
aqua g -i suzuki-shunsuke/github-comment
```

```Go
go install github.com/suzuki-shunsuke/github-comment/v6/cmd/github-comment@latest
```

--------------------------------

### github-comment exec YAML configuration to comment only on failure

Source: https://suzuki-shunsuke.github.io/github-comment/getting-started

This updated YAML configuration for the 'hello' rule modifies the `when` condition to `ExitCode != 0`. This ensures that a GitHub comment is only created if the executed command returns a non-zero exit code, indicating an error or failure. The template content is abbreviated.

```YAML
exec:
  hello:
    - when: ExitCode != 0
      template: |
        ...
```

--------------------------------

### Install Cosign using Aqua

Source: https://suzuki-shunsuke.github.io/github-comment/install

This command installs the Cosign tool using the Aqua package manager. Aqua is a declarative CLI version manager that helps manage and install various command-line tools.

```shell
aqua g -i sigstore/cosign
```

--------------------------------

### github-comment init Command Reference

Source: https://suzuki-shunsuke.github.io/github-comment/usage

Documents the `init` subcommand of `github-comment`, which scaffolds a configuration file if one doesn't exist. It currently has no specific options beyond standard help, making it a simple utility for initial setup.

```Shell
$ github-comment init --help
NAME:
   github-comment init - scaffold a configuration file if it doesn't exist

USAGE:
   github-comment init [command options]

OPTIONS:
   --help, -h  show help


```

--------------------------------

### Scaffold github-comment configuration file

Source: https://suzuki-shunsuke.github.io/github-comment/config

Uses the `github-comment init` command to generate a boilerplate configuration file. This provides a convenient starting point for users to customize their `github-comment` setup.

```bash
github-comment init
```

--------------------------------

### github-comment exec YAML configuration with multiple conditional templates

Source: https://suzuki-shunsuke.github.io/github-comment/getting-started

This YAML configuration defines two distinct template blocks for the 'hello' rule, each with a specific `when` condition. One template is used when the command fails (`ExitCode != 0`), displaying 'command failed', while the other is used when it succeeds (`ExitCode == 0`), displaying 'command is succeeded'. This allows for dynamic comment content based on command outcome.

```YAML
exec:
  hello:
    - when: ExitCode != 0
      template: |
        command failed
    - when: ExitCode == 0
      template: |
        command is succeeded
```

--------------------------------

### Post a comment to a GitHub Pull Request

Source: https://suzuki-shunsuke.github.io/github-comment/getting-started

Demonstrates how to use the `github-comment post` subcommand to add a comment to a specific pull request, requiring a GitHub personal access token, organization, repository, and PR number. The token can also be provided via environment variables `GITHUB_TOKEN` or `GITHUB_ACCESS_TOKEN`.

```Shell
$ github-comment post -token <your GitHub personal access token> -org suzuki-shunsuke -repo github-comment -pr 1 -template test
```

--------------------------------

### github-comment exec YAML configuration with dont_comment condition

Source: https://suzuki-shunsuke.github.io/github-comment/getting-started

This YAML configuration demonstrates the `dont_comment` option for the 'hello' rule. If the command fails (`ExitCode != 0`), `dont_comment: true` prevents any comment from being created. Otherwise (`when: true`), a default 'Hello, world' comment is generated. This provides fine-grained control over comment suppression.

```YAML
exec:
  hello:
    - when: ExitCode != 0
      dont_comment: true
    - when: true
      template: |
        Hello, world
```

--------------------------------

### Verify github-comment assets with GitHub CLI and SLSA Verifier

Source: https://suzuki-shunsuke.github.io/github-comment/install

Demonstrates how to install and use GitHub CLI and SLSA Verifier to verify the integrity and authenticity of `github-comment` assets downloaded from GitHub Releases.

```Shell
aqua g -i cli/cli
```

```Shell
version=v6.3.2
asset=github-comment_${version#v}_darwin_arm64.tar.gz
gh release download -R suzuki-shunsuke/github-comment "$version" -p "$asset"
gh attestation verify "$asset" \
  -R suzuki-shunsuke/github-comment \
  --signer-workflow suzuki-shunsuke/go-release-workflow/.github/workflows/release.yaml
```

```Shell
aqua g -i slsa-framework/slsa-verifier
```

```Shell
version=v6.3.2
asset=github-comment_${version#v}_darwin_arm64.tar.gz
gh release download -R suzuki-shunsuke/github-comment "$version" -p "$asset" -p multiple.intoto.jsonl
slsa-verifier verify-artifact "$asset" \
  --provenance-path multiple.intoto.jsonl \
  --source-uri github.com/suzuki-shunsuke/github-comment \
  --source-tag "$version"
```

--------------------------------

### Example github-comment configuration file

Source: https://suzuki-shunsuke.github.io/github-comment/config

Illustrates a sample `github-comment` configuration, defining `hide` conditions, `post` templates for specific events (e.g., `tfmigrate-hcl-not-found`), and `exec` commands with their associated templates for different statuses. This showcases the structure and capabilities of the configuration.

```yaml
hide:
  default: |2
    Comment.HasMeta && Comment.Meta.SHA1 != Commit.SHA1 && ! (Comment.Meta.Program == "tfcmt" && Comment.Meta.Command == "apply")
post:
  tfmigrate-hcl-not-found:
    template: |2
      ## :x: {{if .Vars.tfaction_target}}{{.Vars.tfaction_target}}: {{end}}.tfmigrate.hcl isn't found

      {{template "link" .}}

      To run `tfmigrate plan`, `.tfmigrate.hcl` is required.
    template_for_too_long: |
      comment is too long
exec:
  tfmigrate-plan:
    - when: true
      template: |2
        ## {{template "status" .}} {{if .Vars.tfaction_target}}{{.Vars.tfaction_target}}: {{end}} tfmigrate plan

        {{template "link" .}}

        {{template "join_command" .}}

        {{template "hidden_combined_output" .}}
      template_for_too_long: |2
        ## {{template "status" .}} {{if .Vars.tfaction_target}}{{.Vars.tfaction_target}}: {{end}} tfmigrate plan

        {{template "link" .}}

        {{template "join_command" .}}

        Command output is omitted as it is too long.
```

--------------------------------

### Verify GitHub Comment Assets with Cosign and SHA256

Source: https://suzuki-shunsuke.github.io/github-comment/install

This script downloads specific assets (including checksums and signatures) for a given version of `github-comment` from GitHub Releases. It then uses Cosign to verify the blob's signature against a certificate and identity, followed by a SHA256 checksum validation to ensure the integrity and authenticity of the downloaded files.

```shell
version=v6.3.2
checksum_file="github-comment_${version#v}_checksums.txt"
asset=github-comment_${version#v}_darwin_arm64.tar.gz
gh release download "$version" \
  -R suzuki-shunsuke/github-comment \
  -p "$asset" \
  -p "$checksum_file" \
  -p "${checksum_file}.pem" \
  -p "${checksum_file}.sig"
cosign verify-blob \
  --signature "${checksum_file}.sig" \
  --certificate "${checksum_file}.pem" \
  --certificate-identity-regexp 'https://github\.com/suzuki-shunsuke/go-release-workflow/\.github/workflows/release\.yaml@.*' \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  "$checksum_file"
cat "$checksum_file" | sha256sum --ignore-missing -c -
```

--------------------------------

### Configure YAML Language Server for github-comment JSON Schema

Source: https://suzuki-shunsuke.github.io/github-comment/config

Specifies the JSON Schema for `github-comment` configuration files to enable input complementation and validation in editors with YAML Language Server support. Examples include pointing to the `main` branch schema for the latest version or a specific pinned version for stability.

```yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/suzuki-shunsuke/github-comment/main/json-schema/github-comment.json
```

```yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/suzuki-shunsuke/github-comment/v6.3.1/json-schema/github-comment.json
```

--------------------------------

### Using github-comment Hide Command with a Specific Template

Source: https://suzuki-shunsuke.github.io/github-comment/hide

This shell command demonstrates how to invoke the `github-comment hide` subcommand and apply a predefined hide condition template. By using the `--hide-key` or `-k` option, users can select a named configuration from their `github-comment` setup, such as 'hello', to control which comments are hidden.

```Shell
$ github-comment hide -k hello
```

--------------------------------

### Example of Metadata Injected into GitHub Comments

Source: https://suzuki-shunsuke.github.io/github-comment/hide

This HTML comment illustrates the structure of metadata that `github-comment` injects into pull request comments. This embedded data, including job details, SHA1, and variables, is crucial for the `hide` subcommand to identify and manage outdated comments programmatically.

```HTML
<!-- github-comment: {"JobID":"xxx","JobName":"plan","SHA1":"79acc0778da6660712a65fd41a48b72cb7ad16c0","TemplateKey":"default","Vars":{}} -->
```

--------------------------------

### github-comment CLI Tool Overview

Source: https://suzuki-shunsuke.github.io/github-comment/usage

Provides a comprehensive overview of the `github-comment` command-line interface, listing all available top-level commands, their purposes, and global options for controlling logging and displaying help/version information.

```Shell
$ github-comment --help
NAME:
   github-comment - post a comment to GitHub

USAGE:
   github-comment [global options] command [command options]

VERSION:
   6.3.2 (92bf17c5b20fb7a1246372b0cc9de4b850d50b4b)

COMMANDS:
   post     post a comment
   exec     execute a command and post the result as a comment
   init     scaffold a configuration file if it doesn't exist
   hide     hide issue or pull request comments
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --log-level value  log level [$GH_COMMENT_LOG_LEVEL]
   --help, -h         show help
   --version, -v      print the version


```

--------------------------------

### github-comment exec Command Reference

Source: https://suzuki-shunsuke.github.io/github-comment/usage

Explains the `exec` subcommand of `github-comment`, which executes a command and posts its output as a GitHub comment. It lists options for repository configuration, authentication, template usage, and output redirection, along with environment variable overrides.

```Shell
$ github-comment exec --help
NAME:
   github-comment exec - execute a command and post the result as a comment

USAGE:
   github-comment exec [command options]

OPTIONS:
   --org value                            GitHub organization name [$GH_COMMENT_REPO_ORG]
   --repo value                           GitHub repository name [$GH_COMMENT_REPO_NAME]
   --token value                          GitHub API token [$GITHUB_TOKEN, $GITHUB_ACCESS_TOKEN]
   --sha1 value                           commit sha1 [$GH_COMMENT_SHA1]
   --template value                       comment template
   --template-key value, -k value         comment template key (default: "default")
   --config value                         configuration file path [$GH_COMMENT_CONFIG]
   --pr value                             GitHub pull request number (default: 0) [$GH_COMMENT_PR_NUMBER]
   --out value [ --out value ]            output destination
   --var value [ --var value ]            template variable
   --var-file value [ --var-file value ]  template variable name and file path
   --dry-run                              output a comment to standard error output instead of posting to GitHub (default: false)
   --skip-no-token, -n                    works like dry-run if the GitHub Access Token isn't set (default: false) [$GH_COMMENT_SKIP_NO_TOKEN, $GITHUB_COMMENT_SKIP_NO_TOKEN]
   --silent, -s                           suppress the output of dry-run and skip-no-token (default: false)
   --help, -h                             show help


```

--------------------------------

### Define Reusable Go Template Components in YAML

Source: https://suzuki-shunsuke.github.io/github-comment/config

Illustrates how to define reusable Go template components within the `templates` section of the configuration. These named templates can then be referenced and included in other templates, such as those used by the `post` command, promoting modularity.

```YAML
templates:
  <template name>: <template content>
post:
  default:
    template: |
      {{template "<template name>" .}} ...
```

--------------------------------

### Output github-comment exec result to GitHub and a file

Source: https://suzuki-shunsuke.github.io/github-comment/output-file

This command executes `npm test` and directs the output of `github-comment` to both a GitHub comment and a specified file path, such as `$GITHUB_STEP_SUMMARY`. This allows for dual reporting of command results.

```Shell
github-comment exec -out github -out "file:$GITHUB_STEP_SUMMARY" -- npm test
```

--------------------------------

### exec Command Variables Reference

Source: https://suzuki-shunsuke.github.io/github-comment/config

Describes the special variables available within `when` and `template` contexts when using the `exec` command. These variables provide access to the command's standard output, error, combined output, command string, joined command string, and exit code.

```APIDOC
exec command variables:
  Stdout: The command's standard output.
  Stderr: The command's standard error output.
  CombinedOutput: Concatenation of Stdout and Stderr.
  Command: The string representation of the command, as per Go's `os/exec.Cmd.String` (https://golang.org/pkg/os/exec/#Cmd.String).
  JoinCommand: The command and its arguments joined by space characters.
  ExitCode: The integer exit code of the command.
```

--------------------------------

### Output github-comment exec result to a file

Source: https://suzuki-shunsuke.github.io/github-comment/output-file

This command executes `npm test` and redirects the output of `github-comment` to a specified file path, typically `$GITHUB_STEP_SUMMARY`, instead of posting it as a GitHub comment. This is useful for capturing command output in GitHub Actions.

```Shell
github-comment exec -out "file:$GITHUB_STEP_SUMMARY" -- npm test
```

--------------------------------

### github-comment Environment Variables Reference

Source: https://suzuki-shunsuke.github.io/github-comment/config

Details the environment variables that can be used to configure or provide context to `github-comment` operations. These variables allow for dynamic configuration and integration with CI/CD pipelines.

```APIDOC
GITHUB_TOKEN, GITHUB_ACCESS_TOKEN
  - Purpose: GitHub API authentication token.
GH_COMMENT_SKIP_NO_TOKEN, GITHUB_COMMENT_SKIP_NO_TOKEN
  - Purpose: Skip commenting if no token is available.
GITHUB_COMMENT_SKIP
  - Purpose: Skip commenting entirely.
GH_COMMENT_REPO_ORG
  - Purpose: Override the GitHub repository organization.
GH_COMMENT_REPO_NAME
  - Purpose: Override the GitHub repository name.
GH_COMMENT_SHA1
  - Purpose: Override the commit SHA1.
GH_COMMENT_CONFIG
  - Purpose: Specify the path to the configuration file.
GH_COMMENT_PR_NUMBER, CI_INFO_PR_NUMBER
  - Purpose: Specify the pull request number.
GH_COMMENT_LOG_LEVEL
  - Purpose: Set the logging level (e.g., debug, info, warn, error).
GH_COMMENT_VAR_*
  - Purpose: Custom variables passed to templates (e.g., GH_COMMENT_VAR_MYVAR=value).
```

--------------------------------

### Define `join_command` template for GitHub comments

Source: https://suzuki-shunsuke.github.io/github-comment/builtin-template

Defines a Go template named `join_command` that formats a shell command string (`.JoinCommand`) for display in GitHub comments. It intelligently wraps the command in `<pre><code>` HTML tags if the command string contains backticks, otherwise it uses standard Markdown triple backticks for code blocks, ensuring proper rendering.

```Go Template
{{template "join_command" .}}
```

```Go Template
<pre><code>$ {{.JoinCommand | AvoidHTMLEscape}}</pre></code>
```

```Go Template
```
$ {{.JoinCommand | AvoidHTMLEscape}}
```
```

--------------------------------

### Basic Usage of github-comment CLI for GitHub Comment Management

Source: https://suzuki-shunsuke.github.io/github-comment/index

This section demonstrates core functionalities of the `github-comment` command-line interface, including posting new comments, executing commands and commenting their results, and hiding old comments. It's designed to improve CI/CD user experience by integrating command outputs directly into GitHub pull requests.

```Shell
$ github-comment post -k test
```

```Shell
$ github-comment exec -- go test ./...
```

```Shell
$ github-comment hide
```

--------------------------------

### exec Command Template Evaluation Logic

Source: https://suzuki-shunsuke.github.io/github-comment/config

Explains how the `exec` command processes templates. Each template element includes `when` and `template` attributes, with `when` conditions evaluated by the `antonmedv/expr` engine. It also details the `dont_comment` attribute's effect on comment creation.

```APIDOC
exec command template evaluation:
  Each template element has attributes: `when`, `template`, and `dont_comment`.
  `when`:
    - Evaluated by the `antonmedv/expr` evaluation engine (https://github.com/antonmedv/expr).
    - The evaluation result must be a boolean.
    - If the evaluation result is `false`, the element is ignored.
    - The first matching element is used.
  `dont_comment`:
    - If set to `true`, the comment is not created.
  Behavior:
    - If no element matches the criteria, the comment is not created, and no error is raised.
```

--------------------------------

### Enable Google Cloud Build support for github-comment

Source: https://suzuki-shunsuke.github.io/github-comment/complement

To enable Google Cloud Build support for `github-comment` (version 4.4.0 and above), set the `GOOGLE_CLOUD_BUILD` environment variable to `true`. This signals `github-comment` to use Google Cloud Build's environment for complementing information, alongside other required environment variables like `COMMIT_SHA` and `_PR_NUMBER`.

```shell
GOOGLE_CLOUD_BUILD=true
```

--------------------------------

### Define and Use Variables in Go Templates via YAML

Source: https://suzuki-shunsuke.github.io/github-comment/config

Shows how to define custom variables in the `vars` section of the configuration file. These variables become accessible within Go templates using the `.Vars.<variable name>` syntax, allowing for dynamic content generation.

```YAML
vars:
  <variable name>: <variable value>
post:
  default:
    template: |
      {{.Vars.<variable name>}} ...
```

--------------------------------

### Pass template to github-comment post via standard input

Source: https://suzuki-shunsuke.github.io/github-comment/feature

Demonstrates how to provide a template to the `github-comment post` command using standard input (`-stdin-template`) instead of a file-based template. This allows for dynamic template generation.

```shell
$ echo hello | github-comment post -stdin-template
```

--------------------------------

### github-comment Template Engine and Functions

Source: https://suzuki-shunsuke.github.io/github-comment/config

Describes the templating capabilities within `github-comment`, powered by Go's `html/template` engine. It lists available functions, including standard Sprig functions (with specified exceptions) and custom functions like `AvoidHTMLEscape` for advanced rendering.

```APIDOC
Template Engine:
  - Engine: html/template (Go standard library)
  - Purpose: Renders fields like `template` and `template_for_too_long` in the configuration.

Available Template Functions:
  - Sprig Functions: All Sprig functions are available, EXCEPT:
    - expandenv, env, getHostByName (from OS/Network categories)
    - os category functions (e.g., `os.Getenv`)
    - network category functions (e.g., `net.LookupIP`)
  - Custom Functions:
    - AvoidHTMLEscape: Skips HTML escaping for the input.
      - Usage: {{.CombinedOutput | AvoidHTMLEscape}}
```

--------------------------------

### Variables available in github-comment post command templates

Source: https://suzuki-shunsuke.github.io/github-comment/config

Lists the predefined variables accessible within templates used by the `post` command in `github-comment` configuration. These variables provide essential context about the GitHub repository, pull request, commit, and custom input, enabling dynamic content generation.

```APIDOC
Variables for 'post' command templates:
  - Org (string): GitHub Organization name.
  - Repo (string): GitHub Repository name.
  - PRNumber (int): Pull request number.
  - SHA1 (string): Commit hash.
  - TemplateKey (string): The key of the currently rendered template.
  - Vars (map[string]interface{}): A map of variables passed via:
    - `-var` CLI option
    - `-var-file` CLI option
    - `vars` field in the configuration
    - Environment variables prefixed with `GH_COMMENT_VAR_`
```

--------------------------------

### github-comment post Command Reference

Source: https://suzuki-shunsuke.github.io/github-comment/usage

Details the `post` subcommand of `github-comment`, used for posting comments to GitHub. It outlines all available options for specifying repository details, authentication tokens, templates, variables, and dry-run behavior, including environment variable overrides.

```Shell
$ github-comment post --help
NAME:
   github-comment post - post a comment

USAGE:
   github-comment post [command options]

OPTIONS:
   --org value                            GitHub organization name [$GH_COMMENT_REPO_ORG]
   --repo value                           GitHub repository name [$GH_COMMENT_REPO_NAME]
   --token value                          GitHub API token [$GITHUB_TOKEN, $GITHUB_ACCESS_TOKEN]
   --sha1 value                           commit sha1 [$GH_COMMENT_SHA1]
   --template value                       comment template
   --template-key value, -k value         comment template key (default: "default")
   --config value                         configuration file path [$GH_COMMENT_CONFIG]
   --pr value                             GitHub pull request number (default: 0) [$GH_COMMENT_PR_NUMBER]
   --var value [ --var value ]            template variable
   --var-file value [ --var-file value ]  template variable name and file path
   --dry-run                              output a comment to standard error output instead of posting to GitHub (default: false)
   --skip-no-token, -n                    works like dry-run if the GitHub Access Token isn't set (default: false) [$GH_COMMENT_SKIP_NO_TOKEN, $GITHUB_COMMENT_SKIP_NO_TOKEN]
   --silent, -s                           suppress the output of dry-run and skip-no-token (default: false)
   --stdin-template                       read standard input as the template (default: false)
   --update-condition value, -u value     update the comment that matches with the condition
   --help, -h                             show help


```

--------------------------------

### Configure GitHub Enterprise Cloud API Endpoints

Source: https://suzuki-shunsuke.github.io/github-comment/github-enterprise

This snippet provides the standard configuration for `github-comment` when used with GitHub Enterprise Cloud, specifying the default API and GraphQL endpoints in the `github-comment.yaml` file.

```YAML
ghe_base_url: https://api.github.com
ghe_graphql_endpoint: https://api.github.com/graphql
```

--------------------------------

### Default `exec` template for GitHub comments

Source: https://suzuki-shunsuke.github.io/github-comment/builtin-template

This is the default Go template used by the `exec` command within `github-comment`. It conditionally renders other builtin templates (`status`, `link`, `join_command`, `hidden_combined_output`) when the `ExitCode` is not zero, providing a comprehensive output for failed command executions.

```Go Template
when: ExitCode != 0
template: |
  {{template "status" .}} {{template "link" .}}

  {{template "join_command" .}}

  {{template "hidden_combined_output" .}}

```

--------------------------------

### Pass Variables to github-comment via Command Line

Source: https://suzuki-shunsuke.github.io/github-comment/config

Demonstrates how to pass custom variables to the `github-comment post` command directly from the command line. The `-var` option allows specifying key-value pairs that can then be accessed within the templates.

```Shell
$ github-comment post -var name:foo
```

--------------------------------

### Define `link` template for CI service URLs in GitHub comments

Source: https://suzuki-shunsuke.github.io/github-comment/builtin-template

Defines a Go template named `link` that generates a URL to the current build, workflow, or job based on environment variables provided by various Continuous Integration (CI) services. It includes specific implementations for CircleCI, AWS CodeBuild, Drone, and GitHub Actions, allowing for dynamic link generation in GitHub comments.

```Go Template
{{template "link" .}}
```

```Go Template
[workflow](https://circleci.com/workflow-run/{{env "CIRCLE_WORKFLOW_ID" }}) [job]({{env "CIRCLE_BUILD_URL"}}) (job: {{env "CIRCLE_JOB"}})
```

```Go Template
[Build link]({{env "CODEBUILD_BUILD_URL"}})
```

```Go Template
[build]({{env "DRONE_BUILD_LINK"}}) [step]({{env "DRONE_BUILD_LINK"}}/{{env "DRONE_STAGE_NUMBER"}}/{{env "DRONE_STEP_NUMBER"}})
```

```Go Template
[Build link](https://github.com/{{env "GITHUB_REPOSITORY"}}/actions/runs/{{env "GITHUB_RUN_ID"}})
```

--------------------------------

### Validate github-comment configuration with JSON Schema using ajv-cli

Source: https://suzuki-shunsuke.github.io/github-comment/config

Demonstrates how to validate a `github-comment` configuration file (`github-comment.yaml`) against its JSON Schema using the `ajv-cli` tool. This ensures the configuration adheres to the defined structure and types.

```bash
ajv --spec=draft2020 -s json-schema/github-comment.json -d github-comment.yaml
```

--------------------------------

### Define `status` template for GitHub comments

Source: https://suzuki-shunsuke.github.io/github-comment/builtin-template

Defines a Go template named `status` that renders a checkmark emoji (✅) if the `ExitCode` is 0 (success) or a cross emoji (❌) otherwise (failure). This template is used to visually indicate the outcome of a command or process in GitHub comments.

```Go Template
{{template "status" .}}
```

```Go Template
:{{if eq .ExitCode 0}}white_check_mark{{else}}x{{end}}:
```

--------------------------------

### Configure repository owner and name in github-comment.yaml

Source: https://suzuki-shunsuke.github.io/github-comment/complement

For `github-comment` to correctly identify the repository context, specify the `org` (owner) and `repo` (repository name) under the `base` section of your `github-comment.yaml` configuration file. This configuration is essential for complementing information such as pull request numbers.

```yaml
base:
  org: suzuki-shunsuke
  repo: github-comment
```

--------------------------------

### Configure GitHub Enterprise Server API Endpoints

Source: https://suzuki-shunsuke.github.io/github-comment/github-enterprise

This snippet shows how to configure `github-comment` for GitHub Enterprise Server by setting `ghe_base_url` and `ghe_graphql_endpoint` in the `github-comment.yaml` configuration file. Users must replace `<your_enterprise_hostname>` with their actual server hostname.

```YAML
ghe_base_url: http(s)://<your_enterprise_hostname> # CHANGE
ghe_graphql_endpoint: http(s)://<your_enterprise_hostname>/api/graphql # CHANGE
```

--------------------------------

### Define `hidden_combined_output` template for GitHub comments

Source: https://suzuki-shunsuke.github.io/github-comment/builtin-template

Defines a Go template named `hidden_combined_output` that renders a combined output string (`.CombinedOutput`) within a collapsible HTML `<details>` block in GitHub comments. Similar to `join_command`, it uses `<pre><code>` or Markdown triple backticks based on whether the output contains backticks, ensuring the content is properly formatted and hidden by default.

```Go Template
{{template "hidden_combined_output" .}}
```

```Go Template
<details><pre><code>{{.CombinedOutput | AvoidHTMLEscape}}</code></pre></details>
```

```Go Template
<details>
```
{{.CombinedOutput | AvoidHTMLEscape}}
```
</details>
```

--------------------------------

### github-comment hide Command Reference

Source: https://suzuki-shunsuke.github.io/github-comment/usage

Provides detailed documentation for the `github-comment hide` command, which allows users to hide comments on GitHub issues or pull requests. It outlines the command's syntax, available options, their data types, and environment variable mappings for configuration.

```APIDOC
$ github-comment hide --help
NAME:
   github-comment hide - hide issue or pull request comments

USAGE:
   github-comment hide [command options]

OPTIONS:
   --org value                            GitHub organization name [$GH_COMMENT_REPO_ORG]
   --repo value                           GitHub repository name [$GH_COMMENT_REPO_NAME]
   --token value                          GitHub API token [$GITHUB_TOKEN, $GITHUB_ACCESS_TOKEN]
   --config value                         configuration file path [$GH_COMMENT_CONFIG]
   --condition value                      hide condition
   --hide-key value, -k value             hide condition key (default: "default")
   --pr value                             GitHub pull request number (default: 0) [$GH_COMMENT_PR_NUMBER]
   --sha1 value                           commit sha1
   --var value [ --var value ]            template variable
   --var-file value [ --var-file value ]  template variable name and file path
   --dry-run                              output a comment to standard error output instead of posting to GitHub (default: false)
   --skip-no-token, -n                    works like dry-run if the GitHub Access Token isn't set (default: false) [$GH_COMMENT_SKIP_NO_TOKEN, $GITHUB_COMMENT_SKIP_NO_TOKEN]
   --silent, -s                           suppress the output of dry-run and skip-no-token (default: false)
   --help, -h                             show help
```

--------------------------------

### Handle GitHub API too long comment errors with substitute templates

Source: https://suzuki-shunsuke.github.io/github-comment/feature

Illustrates the GitHub API validation error for comments exceeding the maximum length (65536 characters). It then shows how `github-comment` can automatically post a shorter, substitute comment defined by `template_for_too_long` when the original `template` content is too long, preventing command failure.

```json
{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "IssueComment",
      "code": "unprocessable",
      "field": "data",
      "message": "Body is too long (maximum is 65536 characters)"
    }
  ],
  "documentation_url": "https://docs.github.com/rest/reference/issues#create-an-issue-comment"
}
```

```yaml
post:
  hello:
    template: too long comment
    template_for_too_long: comment is too long
exec:
  hello:
    - when: ExitCode != 0
      template: |
        exit code: {{.ExitCode}}
        combined output: {{.CombinedOutput}}
      template_for_too_long: |
        comment is too long so the command output is omitted
        exit code: {{.ExitCode}}
```

--------------------------------

### Skip sending GitHub comments using an environment variable

Source: https://suzuki-shunsuke.github.io/github-comment/feature

Explains how to prevent `github-comment` from sending comments by setting the `GITHUB_COMMENT_SKIP` environment variable to `true`. This is particularly useful for local testing or in CI/CD environments where comments should not be posted under certain conditions.

```shell
$ export GITHUB_COMMENT_SKIP=true
$ github-comment post -template test # Do nothing
$ github-comment exec -- echo hello # a command is run but a comment isn't sent
hello
```

--------------------------------

### Applying an Inline Condition with github-comment Hide Command

Source: https://suzuki-shunsuke.github.io/github-comment/hide

This shell command illustrates how to specify an ad-hoc condition for hiding comments directly via the `-condition` option. The provided string is an `expr` expression that `github-comment` evaluates against comment properties, allowing for flexible, on-the-fly filtering of comments to hide.

```Shell
$ github-comment hide -condition 'Comment.Body contains "foo"'
```

--------------------------------

### Configuring Custom Hide Conditions for github-comment

Source: https://suzuki-shunsuke.github.io/github-comment/hide

This YAML configuration demonstrates how to define custom conditions for hiding comments within `github-comment`. It shows setting a default condition and a named condition (`hello`) using `expr` expressions, which evaluate comment metadata and commit information to determine if a comment should be hidden.

```YAML
hide:
  default: "true"
  hello: 'Comment.HasMeta && (Comment.Meta.SHA1 != Commit.SHA1 && Comment.Meta.Vars.target == "hello")'
```
Tokens:
Raw