buildnote guardrails

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

Usage

buildnote guardrails <options>

Options

--timeout

Maximum timeout (in seconds) to wait for collection job to finish. If not set, the event collection will return immediately.

Values: int

---

--policy

Path to a policy file, whose guardrails and report blocks replace the ones in buildnote.json and whose paths are the directories the checks run in.

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 associated with the upload (e.g: 58e53b26ced5fffc72ba5427535e7b5867950b13

Values: value

---

--ref

Commit Ref associated with the upload (e.g:refs/heads/main)

Values: value

---

--only

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

Values: value

---

--fail-on

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

Values: (error|warning|never)

---

--dry-run

Print the verdicts without submitting any event. A dry run never fails the build.

---

-h, --help

Show this message and exit

---

Slack Reporter

Options for slack reporter.

---

--slack-enabled

Enable or disable slack reporter.

Example:

--slack-enabled true

This flag will replace report.slack.enabled value set in buildnote.json config file.

Values: [true|false]

---

--slack-condition

Slack webhook condition evaluated as expression.

Example for failing builds only:

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

You can also access environment variables and combine expressions.

Example of complex condition:

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

This option will replace report.slack.condition value set in buildnote.json config file.

Values: text

---

--slack-template

Path to template file used to format report.

Example:

--slack-template "template.json"

This option will replace report.slack.template value set in buildnote.json config file.

Values: value

---

--slack-url

Slack webhook notification url.

Example:

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

Urls are evaluated as expressions and can, for example, be sourced from environment variables.

Example with environment variable:

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

This option will replace report.slack.url value set in buildnote.json config file.

Values: text

---

--slack-title

Slack message title that replaces default one.

Example of fixed title:

--slack-title "Some title"

Title is evaluated as expressions so you can also access environment and context variables.

Example of complex title:

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

This option will replace report.slack.title value set in buildnote.json config file.

Values: text

---

--slack-title-url

Slack message title url that replaces default one.

Title url is evaluated as expressions and can be templated with environment and context variables.

Example with variable:

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

This option will replace report.slack.titleUrl value set in buildnote.json config file.

Values: text

---

Discord Reporter

Options for discord reporter.

---

--discord-enabled

Enable or disable discord reporter.

Example:

--discord-enabled true

This flag will replace report.discord.enabled value set in buildnote.json config file.

Values: [true|false]

---

--discord-condition

Discord webhook condition evaluated as expression.

Example for failing builds only:

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

You can also access environment variables and combine expressions.

Example of complex condition:

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

This option will replace report.discord.condition value set in buildnote.json config file.

Values: text

---

--discord-template

Path to template file used to format report.

Example:

--discord-template "template.json"

This option will replace report.discord.template value set in buildnote.json config file.

Values: value

---

--discord-url

Discord webhook notification url.

Example:

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

Urls are evaluated as expressions and can, for example, be sourced from environment variables.

Example with environment variable:

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

This option will replace report.discord.url value set in buildnote.json config file.

Values: text

---

--discord-title

Discord message title that replaces default one.

Example of fixed title:

--discord-title "Some title"

Title is evaluated as expressions so you can also access environment and context variables.

Example of complex title:

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

This option will replace report.discord.title value set in buildnote.json config file.

Values: text

---

--discord-title-url

Discord message title url that replaces default one.

Title url is evaluated as expressions and can be templated with environment and context variables.

Example with variable:

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

This option will replace report.discord.titleUrl value set in buildnote.json config file.

Values: text

---

GitHub Reporter

Options for GitHub reporter.

---

--github-enabled

Enable or disable GitHub reporter.

Example:

--github-enabled true

This flag will replace report.github.enabled value set in buildnote.json config file.

Values: [true|false]

---

--github-condition

GitHub report condition evaluated as expression.

Example for failing builds only:

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

You can also access environment variables and combine expressions.

Example of complex condition:

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

This option will replace report.github.condition value set in buildnote.json config file.

Values: text

---

--github-template

Path to template file used to format report.

Example:

--github-template "template.json"

This option will replace report.github.template value set in buildnote.json config file.

Values: value

---

--github-token

GitHub token.

Example:

--github-token "gha_..."

Token is evaluated as expressions and can, for example, be sourced from environment variables.

Example with environment variable:

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

If you would like to use default GitHub Action token (secrets.GITHUB_TOKEN) adjusting the workflow job permissions is required.

Those permissions vary by repository type:

Public repositories:

permissions:
  checks: write
  pull-requests: write

Private repositories:

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

NOTE

When using --github-comment-enabled false the issue comment is disabled and the pull-requests: write permission is not required.

This option will replace report.github.token value set in buildnote.json config file.

Values: text

---

--github-comment-enabled

Enable or disable GitHub comment on PRs.

Example:

--github-comment-enabled true

This flag will replace report.github.commentEnabled value set in buildnote.json config file.

Values: [true|false]

---

--github-comment-updates

Enable or disable GitHub comment updates.

If true it updates existing comment on issues, otherwise set to false it will create a new issue comment each time.

Example:

--github-comment-updates true

This flag will replace report.github.commentUpdates value set in buildnote.json config file.

Values: [true|false]

---

--github-comment-title

GitHub issue comment title that replaces default one.

IMPORTANT

GitHub comments will be updated based on comment title. This may cause previous comments to be overridden if multiple reports are collected in different stages of the build.

Example of fixed title:

--github-comment-title "Some title"

Title is evaluated as expressions so you can also access environment and context variables.

Example of complex title:

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

This option will replace report.github.commentTitle value set in buildnote.json config file.

Values: text

---

--github-comment-title-url

GitHub issue comment title url that replaces default one.

Title url is evaluated as expressions and can be templated with environment and context variables.

Example with variable:

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

This option will replace report.github.commentTitleUrl value set in buildnote.json config file.

Values: text

---

Html Reporter

Options for html reporter.

---

--html-enabled

Enable or disable html reporter.

Example:

--html-enabled true

This flag will replace report.html.enabled value set in buildnote.json config file.

Values: [true|false]

---

--html-condition

Html reporter condition evaluated as expression.

Example for failing builds only:

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

You can also access environment variables and combine expressions.

Example of complex condition:

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

This option will replace report.html.condition value set in buildnote.json config file.

Values: text

---

--html-template

Path to template file used to format report.

Example:

--html-template "template.json"

This option will replace report.html.template value set in buildnote.json config file.

Values: value

---

--html-output-file

Html reporter output file.

Example for fixed output file:

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

You can also access environment variables and combine expressions.

Example of complex output file:

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

This option will replace report.html.outputFile value set in buildnote.json config file.

Values: text

---