Mirror Notice Action

This is an action that can apply a notice about a repository being a mirror on a README.

The reason to exist is that a push mirror will receive a force push from the canonical source, erasing whatever divergence existed in the mirror. By running this action on push, the canonical source's push will trigger this workflow and append a new notice to the README, keeping the mirror history to n+1 commits at all times, the latest commit always being the mirror notice.

The action itself implements a guard to run on a specific remote hostname, so it should support GitHub, Gitea and Forgejo, the latter two only as long as their runners remain compatible with GitHub Actions.

How it works

The action performs two steps, one updates the README with the notice within the runner, the second commits all changes to the README. The reason for an optional commit is, the action operates on the runner's clone, the calling action can perform additional changes on that copy before and/or after. The option is there to give the option to disable what is expected behavior.

No changes will take place on the forge if the runner does not commit the changes, so disabling the commit step means the calling action is taking responsibility for pushing those changes itself.

1. Apply notice checks $GITHUB_SERVER_URL and never runs if it matches the canonical-url, that prevents the canonical source from being marked as a mirror. On real mirrors, it renders a notice, taken from either notice.md in this repository or a custom template in the calling repo, and prepends it to the README. An HTML-comment is inserted before and after to ensure that re-runs don't duplicate the notice.
2. Commit (optional, on by default) commits and pushes the change back to the mirror, using the identity you supply. If you do it yourself, ensure the resulting commit does not retrigger the action.

Both steps never alter the repo beyond the README file that they're pointed at directly.

Example

name: mirror-notice

on:
  push:
    branches: [ main ]
  # Fallback manual trigger
  workflow_dispatch:

permissions:
  # Important else the workflow token is read only, 
  # Forgejo ignores this and requires a trusted integration
  contents: write

jobs:
  notice:
    # Make sure the label exists if using self-hosted Gitea/Forgejo runners
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        # Pinning to main pulls the latest action, check git tags for snapshots 
      - uses: ieris19/mirror-notice@main
        with:
          # Where the canonical repo lives
          canonical-url: https://git.ierislabs.dev
          # Only mandatory if commit is not `false`
          committer-email: actions@example.com

Inputs

Input	Required	Default	Description
canonical-url	yes	—	Base URL of the canonical forge, e.g. https://git.ierislabs.dev. Used to detect (and skip) the canonical host.
template	no	bundled notice.md	Path to a custom notice template.
readme	no	README.md	README file to modify. Must already exist.
commit	no	true	Commit and push the change. Set false to only render the notice into the file and let something else (e.g. a PR-creation action) handle committing.
commit-message	no	docs: mirror notice	Commit message.
committer-name	no	actions[bot]	Name for the commit author.
committer-email	no	—	Email for the commit author. Required unless commit is false — the action refuses to commit with no identity set.

Notice template

notice.md supports three placeholders, substituted at render time:

Placeholder	Value
{{CANONICAL_URL}}	canonical-url, normalized (no trailing slash).
{{CANONICAL_HOST}}	Just the host portion of canonical-url.
{{REPOSITORY}}	owner/repo of the current repository.

Assumptions

Trigger this on whatever event pushes commits to the mirror. The action assumes the canonical host shares user/repo with the mirror.

The same workflow file can be copied verbatim into the canonical repo, it will simply skip itself there.

The script injects a comment pair around the notice, the "start" comment serves as an idempotency marker, the action looks for it in the README to decide whether the notice has already been applied.

Notes

• Only runs the Commit step on an actual branch push (GITHUB_REF starting with refs/heads/) — refuses to run on tag pushes, pull-request refs, or anything else that isn't a real branch, to avoid pushing to the wrong place.