gatekeep/docs/remote-uses.md

Remote uses: — limitations & workarounds

Gatekeep is a self-contained composite Action (action.yml at repo root + scripts/ + defaults/). Consumers should prefer:

uses: https://git.example.com/OWNER/gatekeep@v1
# Project example:
uses: https://git.potatolab.uk/layue13/gatekeep@main

No copy of Action sources into the consumer repo is required. Optional .github/gatekeep/ overrides still work via config-dir.

What must be true

Requirement	Notes
Runner can fetch the Action git repo	Network + credentials if the Action repo is private
Runner can reach OpenRouter	OPENROUTER_API_KEY secret
GITHUB_TOKEN permissions	pull-requests: write, checks: write (see sample workflow)
Org / repo Actions policy	External Actions allowed

GitHub.com-hosted consumers + Gitea-hosted Action

Honest status: GitHub Actions’ first-class uses: owner/repo@ref syntax is for github.com. Full URL uses: https://…@ref is documented for public Actions, but enterprise / org allowlists often restrict non-github.com Action sources. Behavior can also differ by plan and policy version.

If uses: https://git.potatolab.uk/layue13/gatekeep@main fails on github.com runners with an allowlist / “not permitted” / fetch error:

Workaround A — GitHub mirror (recommended)

1. Mirror layue13/gatekeep to a github.com repo you control (e.g. your-org/gatekeep).
2. Point consumers at:

   uses: your-org/gatekeep@main
   # or: uses: your-org/gatekeep@v1
   

3. Keep the Gitea repo as source of truth; sync tags on release.

Workaround B — Vendor checkout (still no Marketplace)

If remotes are fully blocked, checkout Gatekeep into the job and run the composite via local path:

- uses: actions/checkout@v4
  with:
    repository: layue13/gatekeep   # or mirror
    # For Gitea, use a custom remote + token:
    # (or actions/checkout with sparse / git mirror step)
    path: .gatekeep-action
    ref: main
- uses: ./.gatekeep-action
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    openrouter-api-key: ${{ secrets.OPENROUTER_API_KEY }}

For a pure Gitea URL when actions/checkout only speaks github.com, use an explicit git clone step with a deploy token, then uses: ./.gatekeep-action.

Workaround C — Copy-in (appendix)

Copy Action files into .github/actions/gatekeep (see README appendix). Same runtime; more drift risk.

Gitea / Forgejo Actions runners

If the consumer also runs on Gitea Actions (not GitHub-hosted), use that forge’s documented uses: / local action syntax. Paths remain github.action_path-relative so the same Action tree works once the runner can resolve it.

Secrets never travel with the Action

Remote fetch does not include consumer secrets. Always set OPENROUTER_API_KEY (and any forge token for private Action clones) on the consumer repo/org.