# Move your GitHub Actions workflows to Githome

> Run your existing .github/workflows files on Githome: what runs unchanged, runner labels and sizes, secrets, caches, Docker, OIDC, environments, and what to change.

Source: https://git.pkgforge.dev/docs/guides/move-github-actions-workflows

> **Note:** The forge CI of git.pkgforge.dev is dormant: githome reads and validates workflow files, but starts no run, so a workflow does not run there now. This guide says what holds for the files, and what a deployment with the CI on would run.

Most GitHub Actions workflow files are accepted by Githome without changes: Githome reads `.github/workflows/*.yml`, supports the same triggers, expressions, matrices, `needs`, caches, artifacts, secrets, OIDC and Docker, and downloads marketplace actions from GitHub as they are. On a deployment with the CI on, jobs with `runs-on: ubuntu-latest` run on hosted Ubuntu 24.04 runners. What you change is usually small: set your secret values again (GitHub never reveals them), move Windows, macOS and Arm jobs to self-hosted runners, and give `GITHUB_TOKEN` the `permissions:` it needs.

## Steps

1. **Bring the repository over.** On git.pkgforge.dev the server-side import from GitHub (**Settings → Imports → Import from GitHub**, or `githome migrate github acme/website --to acme/website`) needs the import container, which is not running, so it stops at its Git step; bring the code over with the local import (`githome migrate github acme/website --local`) or a plain Git push. Where the server-side import runs, the importer copies the history (workflow files included), issues, pull requests, branch protection, Actions variables, environments and the names of your secrets. The import starts no workflow runs; with the CI on, your first push does. See [Migrate from GitHub](https://git.pkgforge.dev/docs/migrate-from-github).
2. **Set your secret values.** The import lists every secret name, but never a value. A person who is a repository admin enters each one: **Set secret values** on the import's page, `githome secret set NPM_TOKEN -R acme/website`, or the REST API. Do this before your first push, because that push starts the workflows. See [Set secret values](https://git.pkgforge.dev/docs/migrate-from-github#set-secret-values).
3. **Check the workflow files.** Run `githome workflow validate .github/workflows/ci.yml` on each file. Errors fail the file; warnings name keys that are accepted but ignored.
4. **Fix `runs-on` where needed.** `ubuntu-*` labels run on hosted runners. Windows, macOS and Arm jobs need a self-hosted runner (see [Runners and runner sizes](#runners-and-runner-sizes)).
5. **Add `permissions:` where a job writes.** In repositories created on Githome, imported ones included, the job token can only read code and packages by default. A job that comments, labels, pushes, tags or publishes needs a `permissions:` block, for example `contents: write` or `pull-requests: write`, or an admin sets the repository default to write. See [Workflow permissions](https://git.pkgforge.dev/docs/actions/workflow-permissions).
6. **Push a commit and watch the first runs** on the **Actions** tab, or with `githome run list` and `githome run watch <run-id>` (on a deployment with the CI on; on git.pkgforge.dev no run starts now). Fix what fails using the sections below.

## What runs unchanged

- **Triggers:** `push`, `pull_request`, `pull_request_target`, `merge_group`, `workflow_dispatch`, `schedule`, `workflow_run`, `release`, `repository_dispatch` and `workflow_call`. See [Events that trigger workflows](https://git.pkgforge.dev/docs/actions/events).
- **Workflow syntax:** expressions and contexts, matrices with `include` and `exclude`, `needs`, job outputs, `if` conditions, `concurrency`, job summaries, environment files and workflow commands. See [Workflow syntax](https://git.pkgforge.dev/docs/actions/workflow-syntax).
- **Reusable workflows**, as long as they live on the same Githome instance and the calling job has no matrix. See [Reusable workflows](https://git.pkgforge.dev/docs/actions/reusable-workflows).
- **Workflows in `.github/workflows/`.** Githome also reads `.githome/workflows/`, for workflows that should only run on Githome.

## Runners and runner sizes

| `runs-on` | On Githome |
| --- | --- |
| `ubuntu-latest`, `ubuntu-24.04`, `ubuntu-22.04`, any other `ubuntu-*` label, `linux`, `x64` | A hosted Ubuntu 24.04 x64 container, fresh for each job |
| `githome-tiny`, `githome-small`, `githome-medium`, `githome-large` | A hosted runner of that size |
| `windows-*`, `macos-*` | Fails: there are no Windows or macOS hosted runners |
| `ubuntu-24.04-arm` and other Arm labels | Runs on the same x64 image; there are no hosted Arm runners |
| `[self-hosted, ...]` | A machine you connect with `githome runner`, matched on every label |

A job without a size label gets the **large** size (4 vCPU, 12 GiB of memory, 20 GB of disk), unless its own earlier runs show that a smaller size serves it just as well. Add a label such as `runs-on: [ubuntu-latest, githome-small]` to pin a size. See [Runner sizes](https://git.pkgforge.dev/docs/actions/runners#runner-sizes).

The hosted image is smaller than GitHub's. It has Git, Git LFS, curl, jq, build-essential, Python 3.12, Node.js 26 with npm, pnpm and yarn, Docker and `gh`. Go, Java, Ruby, Rust, .NET, PowerShell, browsers and cloud CLIs aren't preinstalled: install them with a setup action or `apt-get`. The apt package lists are removed, so run `apt-get update` before `apt-get install`. See [The Ubuntu 24.04 image](https://git.pkgforge.dev/docs/actions/runners#the-ubuntu-2404-image).

**macOS, Windows, Arm and GPU jobs** run on a [self-hosted runner](https://git.pkgforge.dev/docs/actions/runners#self-hosted-runners): a repository admin creates a registration token, and you start `githome runner` on your machine with labels such as `--labels macos,arm64`. Jobs with `runs-on: [self-hosted, macos, arm64]` then go to it. On Windows, the documented route is to run the runner inside WSL 2. See [macOS, Windows and GPU machines](https://git.pkgforge.dev/docs/actions/runners#macos-windows-and-gpu-machines).

## Marketplace actions

Any `uses: owner/repo@ref` is downloaded from GitHub when the step runs, so marketplace actions keep working. JavaScript actions (they run on the runner's own Node.js, 26 on a hosted runner), composite actions and Docker container actions are all supported.

- `actions/checkout`, `actions/setup-node`, `actions/setup-python`, `actions/setup-go`, `actions/cache`, `actions/upload-artifact` and `actions/download-artifact` are built into the runner for speed, for the version ranges listed in [Built-in actions](https://git.pkgforge.dev/docs/actions/compatibility#built-in-actions). For other versions or inputs, the real action runs.
- `actions/github-script` works with the REST API (`github.rest.*`); `github.graphql` doesn't, because the job token can't use Githome's GraphQL API yet.
- Actions in **private GitHub repositories** can't be downloaded on hosted runners. Move them into a Githome repository and use them as local actions. See [Actions stored on Githome](https://git.pkgforge.dev/docs/actions/compatibility#actions-stored-on-githome).
- `uses: acme/my-action@v1` always means the repository on GitHub, not on Githome.

## Secrets and variables

- **Values come from people.** The importer copies repository variables with their values, and only the **names** of repository, environment and organization secrets. A repository admin who is a person sets each secret's value. Agents can't set secrets or variables anywhere.
- **Where to set them:** repository secrets on **Settings → Secrets and variables** or with `githome secret set`; organization secrets with `githome secret set NAME --org acme`; environment secrets with the REST API.
- **Pull request runs get secrets.** Every pull request comes from a branch of the same repository (there are no forks), so `pull_request` runs receive the repository's secrets. Runs of code an agent wrote don't, unless an admin allows it. See [Which runs receive secrets](https://git.pkgforge.dev/docs/actions/secrets-and-variables#which-runs-receive-secrets).
- **Tools that encrypt secrets first** (GitHub's sealed-box `encrypted_value`) don't work: send the plain `value` over HTTPS; it's encrypted at rest.

See [Secrets and variables](https://git.pkgforge.dev/docs/actions/secrets-and-variables).

## Caches and artifacts

`actions/cache`, `actions/upload-artifact` and `actions/download-artifact` work as on GitHub, and the built-in versions share their storage and formats with the official actions. Caches are scoped per ref with the same fallbacks to the base branch and the default branch, each repository keeps up to 10 GB of caches, and artifacts are kept for up to 90 days. The `cache` input of the setup actions works too. See [Caching and artifacts](https://git.pkgforge.dev/docs/actions/caching-and-artifacts).

## Docker

Job containers, service containers, Docker container actions, `docker build`, `docker run` and `docker compose` work on hosted runners, and so do `docker/setup-buildx-action`, `docker/login-action` and `docker/build-push-action`. The Docker daemon starts on first use, and Docker Hub images are pulled through the `mirror.gcr.io` mirror. If you publish images to `ghcr.io`, push them to the registry at `git.pkgforge.dev` instead, signed in with the job's `GITHUB_TOKEN` and `packages: write`. See [Docker in workflows](https://git.pkgforge.dev/docs/actions/docker) and [Migrating from ghcr.io](https://git.pkgforge.dev/docs/packages/container-registry#migrating-from-ghcrio).

## OIDC

OIDC works with `permissions: id-token: write`, with `https://git.pkgforge.dev` as the issuer. In your cloud provider's trust policy, change the issuer host from `token.actions.githubusercontent.com` to `git.pkgforge.dev`, and keep your `sub` patterns unless they rely on a customized subject template. See [OpenID Connect (OIDC)](https://git.pkgforge.dev/docs/actions/oidc#differences-from-github).

## Environments

The importer creates your environments with their deployment branch policies and variables, and lists their secret names. Then:

- Set environment secrets with the REST API, as a repository admin who is a person. See [Environments and their secrets](https://git.pkgforge.dev/docs/migrate-from-github#environments-and-their-secrets).
- Set required reviewers and wait timers again under **Settings → Environments**, with Githome people. They don't come across. See [Required reviewers and wait timers](https://git.pkgforge.dev/docs/actions/environments#required-reviewers-and-wait-timers).
- Pull request runs never get environment secrets. Keep production credentials in an environment limited to protected branches.

## What doesn't work

The full list, with error messages, is in [Compatibility with GitHub Actions](https://git.pkgforge.dev/docs/actions/compatibility). The differences you're most likely to meet:

- No hosted Windows, macOS or Arm runners, no larger runners above 4 vCPU and no runner groups (`group` is ignored).
- Events other than the ten listed above (`issues`, `issue_comment`, `pull_request_review` and the rest) parse but never start a run.
- A matrix on a job that calls a reusable workflow isn't supported yet.
- `github.graphql` in `actions/github-script` fails.
- Problem matchers aren't supported, and annotations show in the job log only.
- The `cmd` shell isn't supported, and hosted runners have no PowerShell.
- Hard-coded `github.com` and `api.github.com` URLs point at GitHub: use `${{ github.server_url }}` and `${{ github.api_url }}`.

## Checklist

1. Import the repository (or push it) and read the import's warnings.
2. Set every secret value listed by the import, including environment and organization secrets.
3. Run `githome workflow validate` on every workflow file.
4. Replace `windows-*`, `macos-*` and Arm labels with `[self-hosted, ...]` labels and start a runner, or move the job to Linux. Check `matrix.os` values used in `runs-on`.
5. Add `apt-get update` before `apt-get install`, and install tools the hosted image doesn't have.
6. Add `permissions:` to jobs that write with `GITHUB_TOKEN`.
7. Move actions from private GitHub repositories into Githome and use them as local actions.
8. Replace `ghcr.io` with your instance's host (`git.pkgforge.dev` here), and hard-coded GitHub URLs with `github.server_url` and `github.api_url`.
9. Update OIDC trust policies to the `https://git.pkgforge.dev` issuer.
10. Set environment secrets, required reviewers and wait timers.
11. Check the required check names under **Settings → Branch protection** (they're `<workflow name> / <job name>`, such as `CI / test`).
12. Push and watch the first runs.

## Frequently asked questions

### Do my GitHub Actions workflows run unchanged on Githome?

Most do. Githome reads `.github/workflows/` and supports the same syntax, triggers, expressions, matrices, caches, artifacts, secrets, OIDC and Docker. Jobs that need Windows, macOS or Arm, actions from private GitHub repositories, or `github.graphql` need changes. See [Compatibility with GitHub Actions](https://git.pkgforge.dev/docs/actions/compatibility).

### Does Githome copy my GitHub secrets?

It copies their names, never their values: GitHub doesn't reveal secret values, and the importer doesn't try. A repository admin who is a person sets each value on Githome, from the import's **Set secret values** page, the CLI or the API.

### Can I run macOS or Windows jobs on Githome?

Not on hosted runners: they are Linux only. Run them on your own machine with a self-hosted runner (`githome runner`) and `runs-on: [self-hosted, ...]` labels.

### Do marketplace actions work on Githome?

Yes. Githome downloads `uses: owner/repo@ref` actions from GitHub when the step runs. JavaScript, composite and Docker container actions are supported. Actions in private GitHub repositories can't be downloaded on hosted runners.