Get Started

OctoGuide checks that contributor activity on your GitHub repository aligns with common expectations of smoothly-running projects. It will automatically post friendly comments when contributors take actions you don’t want them to.

Installation

Once added as a GitHub Actions workflow, OctoGuide will automatically post comments advising users if their contribution activity violates any common best practices. OctoGuide can scan comment, discussion, issue, and pull request events.

Add the following .github/workflows/octoguide.yml file to get started:

jobs:
  octoguide:
    if: ${{ !endsWith(github.actor, '[bot]') }}
    runs-on: ubuntu-latest
    steps:
      - uses: JoshuaKGoldberg/octoguide@0.15.0
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

name: OctoGuide

on:
  discussion:
    types: [created, edited]
  discussion_comment:
    types: [created, deleted, edited]
  issue_comment:
    types: [created, deleted, edited]
  issues:
    types: [edited, opened]
  pull_request_review_comment:
    types: [created, deleted, edited]
  pull_request_target:
    types: [edited, opened]

permissions:
  discussions: write
  issues: write
  pull-requests: write

Once you’ve created that .yml file, congrats! OctoGuide should be enabled on your repository. 👏

To test it out, try adding a comment with just the text “+1” on an existing issue. OctoGuide should post a response within 10-15 seconds.

Configuration

`config`

OctoGuide by default enables a recommended set of rules. You can extend it to use a strict superset by adding config: strict to the action’s with:

jobs:
  octoguide:
    if: ${{ !endsWith(github.actor, '[bot]') }}
    runs-on: ubuntu-latest
    steps:
      - uses: JoshuaKGoldberg/octoguide@0.15.0
        with:
          config: strict
          github-token: ${{ secrets.GITHUB_TOKEN }}

The strict config includes all rules from recommended plus more rules that enforce more opinionated practices.

See Preset Configs for more information on preset configs and their rules.

`github-token`

OctoGuide requires a github-token for the action to be able to post comments. GitHub’s provided ${{ secrets.GITHUB_TOKEN }} allows it to post as the general github-actions[bot].

If you’d like the action to post as a different user, you can provide a token with permissions to comment on your repository. For public repositories that’s the following permissions:

repo > public_repo
read:discussion

`comment-header`

You can customize the header message that OctoGuide adds to its comments by providing a comment-header input as a string.

Example:

jobs:
  octoguide:
    if: ${{ !endsWith(github.actor, '[bot]') }}
    runs-on: ubuntu-latest
    steps:
      - uses: JoshuaKGoldberg/octoguide@0.15.0
        with:
          comment-header: "Hey! You! Listen! This is a bot message from Octoguide! 🐙"
          github-token: ${{ secrets.GITHUB_TOKEN }}

If no custom header is provided, OctoGuide by default has no header message.

`comment-footer`

You can customize the footer message that OctoGuide adds to its comments by providing a comment-footer input as a string.

Example:

jobs:
  octoguide:
    if: ${{ !endsWith(github.actor, '[bot]') }}
    runs-on: ubuntu-latest
    steps:
      - uses: JoshuaKGoldberg/octoguide@v0
        with:
          comment-footer: "🗺️ This message was posted automatically by [OctoGuide](https://octo.guide): a bot for GitHub repository best practices."
          github-token: ${{ secrets.GITHUB_TOKEN }}

If no custom footer is provided, OctoGuide uses its default message.

Enabling and Disabling Individual Rules

You can enable or disable specific rules by providing inputs with the rule names set to "true" or "false". This allows you to customize which rules are active beyond the preset configs.

Examples:

To disable a rule that’s normally enabled in your chosen config:

jobs:
  octoguide:
    if: ${{ !endsWith(github.actor, '[bot]') }}
    runs-on: ubuntu-latest
    steps:
      - uses: JoshuaKGoldberg/octoguide@0.15.0
        with:
          comment-meaningful: "false"
          github-token: ${{ secrets.GITHUB_TOKEN }}

To enable a rule that’s not included in your chosen config:

jobs:
  octoguide:
    if: ${{ !endsWith(github.actor, '[bot]') }}
    runs-on: ubuntu-latest
    steps:
      - uses: JoshuaKGoldberg/octoguide@0.15.0
        with:
          config: recommended
          github-token: ${{ secrets.GITHUB_TOKEN }}
          pr-title-conventional: "true"

To use only specific rules without any preset config:

jobs:
  octoguide:
    if: ${{ !endsWith(github.actor, '[bot]') }}
    runs-on: ubuntu-latest
    steps:
      - uses: JoshuaKGoldberg/octoguide@0.15.0
        with:
          comment-meaningful: "true"
          config: none
          github-token: ${{ secrets.GITHUB_TOKEN }}
          pr-linked-issue: "true"
          text-image-alt-text: "true"

Rule names use kebab-case and correspond to the rule names shown in the Rules documentation. When a rule is explicitly set via input, it takes precedence over the preset config settings.