buildnote guardrails

Runs the guardrails configured in buildnote.json, or the ones declared in a policy file

Usage

buildnote guardrails <options>

Options

--timeout

Maximum time, in seconds, to wait for the collection job to finish. If you don't set it, the command returns immediately without waiting.

Values: int

--policy

Path to a policy file. Its guardrails and report blocks replace the ones in buildnote.json, and the checks run in the directories listed under its paths.

Values: value

--org

Organisation identifier

Values: value

--project

Project identifier

Values: value

--module

Module identifier

Values: value

--build

Build identifier

Values: value

--sha

Commit SHA for the upload, such as 58e53b26ced5fffc72ba5427535e7b5867950b13

Values: value

--ref

Commit ref for the upload, such as refs/heads/main

Values: value

--only

Runs only the guardrail with this id. Repeat the option to run several.

Values: value

--fail-on

Severity that fails the build: error (the default), warning or never. Overrides guardrails.failOn in buildnote.json or in the policy.

Values: (error|warning|never)

--dry-run

Prints the results without submitting any events. A dry run never fails the build.

-h, --help

Show this message and exit

Slack Reporter

Options for the Slack reporter.

--slack-enabled

Turns the Slack reporter on or off.

Example:

shell

--slack-enabled true

This flag overrides the report.slack.enabled value in the buildnote.json config file.

Values: [true|false]

--slack-condition

Expression that decides whether the Slack webhook is sent.

Example that reports failing builds only:

shell

--slack-condition "{{failed}}"

You can also use environment variables and combine expressions.

Example that combines several conditions:

shell

--slack-condition "{{failed || successful || env.USER == 'some-user'}}"

This option overrides the report.slack.condition value in the buildnote.json config file.

Values: text

--slack-template

Path to a template file that formats the report.

Example:

shell

--slack-template "template.json"

This option overrides the report.slack.template value in the buildnote.json config file.

Values: value

--slack-url

Slack webhook URL that notifications are sent to.

Example:

shell

--slack-url "https://hooks.slack.com/services/..."

The URL is evaluated as an expression, so you can read it from an environment variable, for example.

Example with an environment variable:

shell

--slack-url "{{env.SLACK_WEBHOOK_URL}}"

This option overrides the report.slack.url value in the buildnote.json config file.

Values: text

--slack-title

Title of the Slack message, replacing the default title.

Example with a fixed title:

shell

--slack-title "Some title"

The title is evaluated as an expression, so you can also use environment and context variables.

Example that builds the title from variables:

shell

--slack-title "E2E test {{status}} - {{env.GITHUB_WORKFLOW}} - {{env.GITHUB_RUN_ID}} (attempt: {{env.GITHUB_RUN_ATTEMPT}})"

This option overrides the report.slack.title value in the buildnote.json config file.

Values: text

--slack-title-url

Link for the Slack message title, replacing the default link.

The link is evaluated as an expression, so you can build it from environment and context variables.

Example with a variable:

shell

--slack-title-url "https://www.example.com/status/{{status}}"

This option overrides the report.slack.titleUrl value in the buildnote.json config file.

Values: text

Discord Reporter

Options for the Discord reporter.

--discord-enabled

Turns the Discord reporter on or off.

Example:

shell

--discord-enabled true

This flag overrides the report.discord.enabled value in the buildnote.json config file.

Values: [true|false]

--discord-condition

Expression that decides whether the Discord webhook is sent.

Example that reports failing builds only:

shell

--discord-condition "{{failed}}"

You can also use environment variables and combine expressions.

Example that combines several conditions:

shell

--discord-condition "{{failed || successful || env.USER == 'some-user'}}"

This option overrides the report.discord.condition value in the buildnote.json config file.

Values: text

--discord-template

Path to a template file that formats the report.

Example:

shell

--discord-template "template.json"

This option overrides the report.discord.template value in the buildnote.json config file.

Values: value

--discord-url

Discord webhook URL that notifications are sent to.

Example:

shell

--discord-url "https://discord.com/api/webhooks/..."

The URL is evaluated as an expression, so you can read it from an environment variable, for example.

Example with an environment variable:

shell

--discord-url "{{env.DISCORD_WEBHOOK_URL}}"

This option overrides the report.discord.url value in the buildnote.json config file.

Values: text

--discord-title

Title of the Discord message, replacing the default title.

Example with a fixed title:

shell

--discord-title "Some title"

The title is evaluated as an expression, so you can also use environment and context variables.

Example that builds the title from variables:

shell

--discord-title "E2E test {{status}} - {{env.GITHUB_WORKFLOW}} - {{env.GITHUB_RUN_ID}} (attempt: {{env.GITHUB_RUN_ATTEMPT}})"

This option overrides the report.discord.title value in the buildnote.json config file.

Values: text

--discord-title-url

Link for the Discord message title, replacing the default link.

The link is evaluated as an expression, so you can build it from environment and context variables.

Example with a variable:

shell

--discord-title-url "https://www.example.com/status/{{status}}"

This option overrides the report.discord.titleUrl value in the buildnote.json config file.

Values: text

GitHub Reporter

Options for the GitHub reporter.

--github-enabled

Turns the GitHub reporter on or off.

Example:

shell

--github-enabled true

This flag overrides the report.github.enabled value in the buildnote.json config file.

Values: [true|false]

--github-condition

Expression that decides whether the GitHub report runs.

Example that reports failing builds only:

shell

--github-condition "{{failed}}"

You can also use environment variables and combine expressions.

Example that combines several conditions:

shell

--github-condition "{{failed || successful || env.USER == 'some-user'}}"

This option overrides the report.github.condition value in the buildnote.json config file.

Values: text

--github-template

Path to a template file that formats the report.

Example:

shell

--github-template "template.json"

This option overrides the report.github.template value in the buildnote.json config file.

Values: value

--github-token

GitHub token the reporter uses.

Example:

shell

--github-token "gha_..."

The token is evaluated as an expression, so you can read it from an environment variable, for example.

Example with an environment variable:

shell

--github-token "{{env.GITHUB_TOKEN}}"

To use the default GitHub Actions token (secrets.GITHUB_TOKEN), you need to adjust the workflow job permissions.

The permissions you need depend on the repository type:

Public repositories:

yaml

permissions:
  checks: write
  pull-requests: write

Private repositories:

yaml

permissions:
  contents: read
  issues: read
  checks: write
  pull-requests: write

NOTE

If you pass --github-comment-enabled false, the issue comment is turned off and you don't need the pull-requests: write permission.

This option overrides the report.github.token value in the buildnote.json config file.

Values: text

--github-comment-enabled

Turns the GitHub comment on pull requests on or off.

Example:

shell

--github-comment-enabled true

This flag overrides the report.github.commentEnabled value in the buildnote.json config file.

Values: [true|false]

--github-comment-updates

Turns updates to the existing GitHub comment on or off.

With true, the reporter updates its existing comment on the issue. With false, it adds a new issue comment each time.

Example:

shell

--github-comment-updates true

This flag overrides the report.github.commentUpdates value in the buildnote.json config file.

Values: [true|false]

--github-comment-title

Title of the GitHub issue comment, replacing the default title.

IMPORTANT

The reporter finds the comment to update by its title. If you report from several stages of the build with the same title, a later report can overwrite the comment from an earlier one.

Example with a fixed title:

shell

--github-comment-title "Some title"

The title is evaluated as an expression, so you can also use environment and context variables.

Example that builds the title from variables:

shell

--github-comment-title "E2E test {{status}} - {{env.GITHUB_WORKFLOW}} - {{env.GITHUB_RUN_ID}} (attempt: {{env.GITHUB_RUN_ATTEMPT}})"

This option overrides the report.github.commentTitle value in the buildnote.json config file.

Values: text

--github-comment-title-url

Link for the GitHub issue comment title, replacing the default link.

The link is evaluated as an expression, so you can build it from environment and context variables.

Example with a variable:

shell

--github-comment-title-url "https://www.example.com/status/{{status}}"

This option overrides the report.github.commentTitleUrl value in the buildnote.json config file.

Values: text

Html Reporter

Options for the Html reporter.

--html-enabled

Turns the Html reporter on or off.

Example:

shell

--html-enabled true

This flag overrides the report.html.enabled value in the buildnote.json config file.

Values: [true|false]

--html-condition

Expression that decides whether the Html reporter runs.

Example that reports failing builds only:

shell

--html-condition "{{failed}}"

You can also use environment variables and combine expressions.

Example that combines several conditions:

shell

--html-condition "{{failed || successful || env.USER == 'some-user'}}"

This option overrides the report.html.condition value in the buildnote.json config file.

Values: text

--html-template

Path to a template file that formats the report.

Example:

shell

--html-template "template.json"

This option overrides the report.html.template value in the buildnote.json config file.

Values: value

--html-output-file

File the Html reporter writes to.

Example with a fixed output file:

shell

--html-output-file "test-report.html"

You can also use environment variables and combine expressions.

Example that builds the file name from an expression:

shell

--html-output-file "{{env.USER}}/test-report.html"

This option overrides the report.html.outputFile value in the buildnote.json config file.

Values: text

buildnote guardrails ​

Usage ​

Options ​

--timeout ​

--policy ​

--org ​

--project ​

--module ​

--build ​

--sha ​

--ref ​

--only ​

--fail-on ​

--dry-run ​

-h, --help ​

Slack Reporter ​

--slack-enabled ​

--slack-condition ​

--slack-template ​

--slack-url ​

--slack-title ​

--slack-title-url ​

Discord Reporter ​

--discord-enabled ​

--discord-condition ​

--discord-template ​

--discord-url ​

--discord-title ​

--discord-title-url ​

GitHub Reporter ​

--github-enabled ​

--github-condition ​

--github-template ​

--github-token ​

--github-comment-enabled ​

--github-comment-updates ​

--github-comment-title ​

--github-comment-title-url ​

Html Reporter ​

--html-enabled ​

--html-condition ​

--html-template ​

--html-output-file ​

buildnote guardrails

Usage

Options

--timeout

--policy

--org

--project

--module

--build

--sha

--ref

--only

--fail-on

--dry-run

-h, --help

Slack Reporter

--slack-enabled

--slack-condition

--slack-template

--slack-url

--slack-title

--slack-title-url

Discord Reporter

--discord-enabled

--discord-condition

--discord-template

--discord-url

--discord-title

--discord-title-url

GitHub Reporter

--github-enabled

--github-condition

--github-template

--github-token

--github-comment-enabled

--github-comment-updates

--github-comment-title

--github-comment-title-url

Html Reporter

--html-enabled

--html-condition

--html-template

--html-output-file