Commit or Rewrite Action

A smart GitHub Action that creates new commits or rewrites existing ones based on commit IDs. Perfect for automated commits that should update in-place rather than creating new commits every time.

🎯 Key Feature: Smart Rewriting

This action intelligently decides whether to create a new commit or rewrite an existing one:

• First run: Creates a new commit with your specified ID
• Subsequent runs with same ID: If HEAD commit has the same ID, it rewrites that commit
• Different ID or no matching ID: Creates a new commit

This prevents commit spam from automated tasks while maintaining a clean git history!

How It Works

1. Each commit includes a git trailer: X-Commit-Rewrite-ID: <your-id>
2. When the action runs, it checks if HEAD has this exact trailer
3. If HEAD has matching ID → Rewrites that commit (amends)
4. If HEAD has different/no ID → Creates a new commit

Important: The rewrite ONLY happens when the HEAD commit has the matching ID. If there are other commits on top, a new commit will be created.

Technical Implementation

Unlike git commit --amend, this action uses the GitHub API to create commits. When rewriting:

1. It resets the branch to the parent commit using the API
2. Creates a new commit with updated content
3. The result looks exactly like an amended commit

This approach allows for signed commits without requiring GPG keys and works seamlessly in GitHub Actions environments.

✨ Automatic Commit Signing

All commits are created via GitHub API, which provides automatic signing:

• GITHUB_TOKEN (default): Signed by GitHub Actions bot
• GitHub App tokens: Signed by your GitHub App
• Fine-grained PATs: Signed by the token owner

No GPG key configuration required - commits appear as "Verified" automatically!

Usage

Basic Usage

- name: Update generated files
  uses: actionutils/commit-or-rewrite@v1
  with:
    commit_message: 'chore: update generated files'
    id: 'generated-files-update'
    # Branch is auto-detected if not specified

Running this multiple times will keep rewriting the same commit as long as it's the HEAD commit.

Specific Files

- name: Update changelog
  uses: actionutils/commit-or-rewrite@v1
  with:
    commit_message: 'docs: update changelog'
    id: 'changelog-auto-update'
    files: |
      CHANGELOG.md
      docs/releases.md

With Custom Branch

- name: Update on specific branch
  uses: actionutils/commit-or-rewrite@v1
  with:
    commit_message: 'chore: automated update'
    id: 'auto-update'
    branch: 'automation-branch'
    github_token: ${{ secrets.GITHUB_APP_TOKEN }}

Inputs

Input	Description	Required	Default
commit_message	Commit message (can be multiline)	Yes	-
id	Unique identifier for rewriting	Yes	-
branch	Target branch (auto-detects if not specified)	No	'' (auto-detect)
files	Files to commit (newline-separated). If empty, commits all changes	No	'' (all changes)
github_token	GitHub token for API operations	No	${{ github.token }}

Real-World Examples

Automated Dependency Updates

name: Update Dependencies
on:
  schedule:
    - cron: '0 0 * * MON'  # Every Monday
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2  # Need HEAD and its parent for rewriting

      - name: Update npm dependencies
        run: |
          npx npm-check-updates -u
          npm install

      - name: Commit updates
        uses: actionutils/commit-or-rewrite@v1
        with:
          commit_message: 'chore: weekly dependency update'
          id: 'npm-deps-weekly'
          files: |
            package.json
            package-lock.json

Running this workflow multiple times in the same week will rewrite the same commit instead of creating multiple "weekly update" commits.

Generated Documentation

name: Generate Docs
on:
  push:
    branches: [main]
    paths: ['src/**']

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - name: Generate API docs
        run: npm run generate-docs

      - name: Update docs
        uses: actionutils/commit-or-rewrite@v1
        with:
          commit_message: 'docs: auto-generated API documentation'
          id: 'api-docs-auto'
          files: 'docs/api/'

Build Artifacts

- name: Build and commit dist
  run: npm run build

- name: Commit built files
  uses: actionutils/commit-or-rewrite@v1
  with:
    commit_message: 'build: update dist files'
    id: 'build-dist'
    files: 'dist/'

Permissions

This action requires contents: write permission to create and modify commits.

permissions:
  contents: write

When using custom tokens (GitHub Apps or Fine-grained PATs), ensure they have contents: write permission.

Future Features

We're considering adding support for fixup / squash commits for later squashing.

License

MIT