Move your GitHub Actions workflows to Githome

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.
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.
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).
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.
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.
• 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.
• Reusable workflows, as long as they live on the same Githome instance and the calling job has no matrix. See Reusable workflows.
• Workflows in .github/workflows/. Githome also reads .githome/workflows/, for workflows that should only run on Githome.

#Runners and runner sizes

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.

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.

macOS, Windows, Arm and GPU jobs run on a self-hosted runner: 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.

#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. 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.
• 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.
• 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.

#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.

#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 and Migrating from ghcr.io.

#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).

#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.
• Set required reviewers and wait timers again under Settings → Environments, with Githome people. They don't come across. See 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. 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.

#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.