Custom Automated Changes

When working with automated changes made by the Gitar bot, custom automated changes may be necessary. For example,

• Running lint auto-fixes
• Executing code generation
• Updating test snapshot files
• Running internal tools

Gitar recommends these in a separate CI pipeline. We call this Gitar Duet, where your custom tools run alongside Gitar’s automated changes.

Why set up custom CI pipeline?

Gitar runs deterministic code refactors to ensure consistent and predictable changes across codebases. Gitar also applies standard auto-formatters to automated PRs, maintaining consistent code formatting. However, Gitar intentionally does not run linters or custom code generation tools that could potentially alter the behavior of codebases in other ways.

This separation of concerns ensures that Gitar’s refactoring remains reliable, allowing codebases to maintain their quality standards, customizations, and security requirements.

Example GitHub action setup

This guide will help you set up a GitHub Action to run these types of custom tools on pull requests (PRs) created by the Gitar bot.

1. In your repository, create a new file: .github/workflows/gitar-duet.yml
2. Copy the following YAML content into the file and customize it to include your specific commands:

name: Gitar Duet

on:
  push:
    branches:
      - 'gitar_*'

jobs:
  gitar-duet:
    if: github.event.head_commit.author.name == 'Gitar'
    runs-on: ubuntu-latest
    name: Gitar Duet
    permissions:
      pull-requests: read # Required to identify the Gitar cleanup pull request
      contents: write # Required to update with Gitar Duet changes

    steps:
      - uses: actions/checkout@v4

      - name: Set up your environment
        # Add steps to set up your specific environment (e.g., installing dependencies)

      - name: Run custom lint fixer
        # Add your custom lint fixer command here
        # Example: npm run lint:fix

      - name: Run custom code generation
        # Add your custom code generation command here
        # Example: make codegen

      # Use the Gitar Duet action to commit and push changes back to the PR branch
      - name: Run Gitar Duet Action
        uses: gitarcode/gitar-duet-action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

Requirements

To ensure Gitar Duet functions correctly, it’s important to configure the GITHUB_TOKEN with the contents:write and pull-requests:read permission to update the PR branch with custom changes. You can find an overview of the permissions for the GITHUB_TOKEN in the GitHub documentation.

How it works

1. The action is triggered on pushes by Gitar bot.
2. It checks if the last commit is by Gitar.
3. If true, it runs custom lint fixer and code generation tools.
4. Any changes are committed and pushed back to the PR branch.
5. Modify the template to include your specific commands.

Summary

By following this guide, you can automatically apply your own quality checks and fixes to PRs created by the Gitar bot, ensuring that automated code changes meet your specific standards while benefiting from Gitar’s powerful refactoring capabilities. This approach also maintains the security and integrity of your codebase by keeping sensitive operations within your controlled environment.