# Remote `uses:` — limitations & workarounds

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

```yaml
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:
   ```yaml
   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:

```yaml
- 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.