# Move CI from GitHub to GitCafe

Keep workflows in `.github/workflows`; don't move them or rewrite their YAML.
GitCafe runs them with the official GitHub Actions runner and labels their
results **GitCafe Actions** in the CI tab.

## Prepare the repository

1. Open **Settings → CI → Migration readiness**. Check each workflow's blockers
   and warnings before enabling it.
2. Copy [secrets and variables](https://git.cafe/docs/ci/secrets-and-variables.md). Secret values cannot
   be read back from GitHub; retrieve them from their original source and use
   `cafe ci secret set NAME`. Copy variables with `cafe ci variable set NAME`.
3. Register [self-hosted runners](https://git.cafe/docs/ci/self-hosted-runners.md). A GitCafe registration
   can run beside a separate GitHub registration on the same machine. Or use
   GitCafe-hosted Linux labels: `ubuntu-latest`, `ubuntu-24.04`, `ubuntu-22.04`.
4. Enable Actions in **Settings → CI** and push a change on GitCafe or dispatch
   a workflow with `cafe ci dispatch ci.yml --ref main`.

`GITHUB_TOKEN` is a GitCafe token, not a GitHub token. Steps that call github.com
with `gh`, `actions/github-script`, or pushes to github.com need an explicit
GitHub credential secret; configure the step's token and endpoint explicitly.

Keep workflows for fork pull requests, `schedule`, `issue_comment`, `release`,
cross-repository reusable workflows, and workflows that require cache on GitHub
for now. See [unsupported features](https://git.cafe/docs/ci/actions.md#what-works-differently) and
[supported workflow syntax](https://git.cafe/docs/ci/workflow-syntax.md).

## Moving CI while synced

[GitHub sync](https://git.cafe/docs/integrations/github-sync.md) does not transfer CI execution or
results:

- **One-way (pull):** pushes and pull requests made on GitHub do not start
  workflows on GitCafe yet. Only changes made on GitCafe run workflows here.
- **Two-way:** a push made on GitCafe runs workflows here and again on GitHub
  after it syncs. Changes arriving from GitHub still do not start workflows here.

To move a whole workflow, disable it on GitHub with
`gh workflow disable <file>` or the repository's Actions settings, and let
GitCafe run it. Make changes on GitCafe: disabling GitHub's workflow does not
make inbound sync trigger GitCafe runs.

To move one job, guard it on GitCafe:

```yaml
if: github.server_url != 'https://github.com'
```

Keep GitHub-only jobs guarded with the opposite condition:

```yaml
if: github.server_url == 'https://github.com'
```

A skipped GitHub job counts as passing for GitHub required checks. Update GitHub
branch protection to stop requiring checks GitHub no longer runs. GitCafe
results are not posted to GitHub yet; until then, gate merges on the side that
runs the job, using [GitCafe rulesets](https://git.cafe/docs/repositories/repository-rulesets.md)
for jobs moved here.