How to migrate from GitHub to Forgejo
Move GitHub repositories to self-hosted Forgejo: import code, issues and pull requests, rebuild what stays behind, move CI to Forgejo Actions, switch remotes.
In short
- Forgejo’s GitHub migration brings the code, the wiki, LFS objects, issues and pull requests with their reviews, labels, milestones and releases, and issues keep their numbers.
- Actions secrets and variables, Discussions, Projects, branch protection, rulesets, webhooks, apps and Packages stay on GitHub and are rebuilt or replaced in Forgejo.
- Forgejo Actions reads only the first workflow directory it finds, .forgejo/workflows before .github/workflows, and is designed to be familiar to GitHub users rather than compatible.
- Each GitHub repository is archived as its batch moves: read-only for everyone and still readable, while the remote in every clone is pointed at Forgejo.
On this page (13)
Moving from GitHub to Forgejo is an import for the repositories and a rebuild for what surrounds them. Forgejo’s migration reads each repository through GitHub’s API and brings its history, issues, pull requests and releases with it. Secrets, branch protection, webhooks and apps stay on GitHub and are created again, and CI moves to Forgejo Actions, which reads the same workflow format without being a copy of GitHub Actions. This guide covers the order we run the move in, and the places it usually goes wrong.
Why teams move from GitHub to Forgejo
Three reasons come up again and again.
- Code and the secrets that deploy it. Source code, its history and the credentials CI uses to ship it are often the most sensitive things an engineering team holds. Forgejo keeps repositories on a disk and CI secrets in a database, on your premises or in a region you choose.
- CI next to what it builds. Forgejo Runner executes jobs on machines you control, inside the network where the databases, registries and servers they deploy to already are. CI costs the machines it runs on, not minutes.
- One edition, no seats. Forgejo is GPL-licensed and has no paid edition: every feature ships in the one release. GitHub’s paid plans are priced per user.
What you give up is real. GitHub is where outside contributors already have accounts, and its Marketplace holds apps and actions written for it. GitHub-hosted runners cover Linux, Windows and macOS without a machine of your own. Codespaces, Copilot inside GitHub, Dependabot and GitHub’s code and secret scanning have no counterpart in Forgejo, and someone has to run the forge, which is the part Pilae takes on.
Step 1: list what the migration does not carry
Forgejo’s migration reads a fixed set of things from GitHub. Everything else needs a decision before the first repository moves.
What the Forgejo GitHub migration brings across
Imported
- The Git history, with every branch and tag
- The wiki, as a Git repository of its own
- LFS objects, when the instance runs its LFS server
- Issues and pull requests with comments, reviews and reactions, under their GitHub numbers
- Labels, milestones and topics
- Releases, with their attached files
Stays behind
- Actions secrets, variables and environments
- Branch protection rules and rulesets
- Webhooks, deploy keys and installed apps
- Team access and collaborators
- Discussions, Projects and GitHub Pages
- Packages, Codespaces and Copilot
- Images pasted into issues and comments, which stay links to GitHub
For each repository you move, list:
- Secrets and variables, by name.
gh secret listshows a repository’s secret names; GitHub’s API returns a secret’s name and dates but never its value, so note where each value comes from: a vault, a cloud console, the system that issued it. - Branch protection and rulesets, with the required reviews and status checks each one enforces.
- Webhooks, deploy keys and apps, with what each one feeds and who owns it.
- Workflows: the
runs-onlabels they ask for, the actions theyuses:, and the events that start them. - Packages published to GitHub Packages, and every system that pulls them.
- References to github.com in the code:
.gitmodules, Go module paths, package manifests, container image names, deployment scripts and badges in READMEs.
Each line gets an owner and a target: rebuilt in Forgejo, replaced by another tool, or dropped.
Step 2: set up organisations, teams and sign-in
The migration creates repositories, not people or access. Build those first, so that each repository lands in an organisation whose teams already exist.
| GitHub | Forgejo |
|---|---|
| Organisation | Organisation |
| Enterprise with several organisations | Several organisations on one instance |
| Team with a repository role | Team with administrator access, or custom read or write access per unit |
| Team access to selected repositories | Team set to all repositories or to specific ones |
| Outside collaborator | Collaborator on the repository |
| Member account | Account created at first sign-in through your identity provider |
| SSH keys and personal access tokens | Added again by each person, under Settings |
| Deploy key | Deploy key, created again in the repository’s settings |
| Actions secrets and variables | Secrets and variables per repository, organisation or user, entered again |
Sign-in. Forgejo signs people in over OpenID Connect or LDAP and has no SAML support, so a directory that only speaks SAML goes through Keycloak as a broker. A site administrator opens Site administration, Authentication sources, Add authentication source, chooses OAuth2 with the OpenID Connect provider, and gives it the discovery URL of your Keycloak realm or Entra ID tenant. The same source names the claim that carries groups, maps groups to organisation teams, and can remove people from synchronised teams when they leave a group. With automatic registration on, each account is created at first sign-in. The directory does not reach SSH keys or access tokens, so offboarding also disables the account in Forgejo.
Authors of migrated issues. Issues, comments and reviews arrive under the GitHub username that wrote them. Forgejo ties them to an account only where that person has linked their GitHub login through an authentication source for GitHub named github; linking an account later re-attributes what was already imported. If authorship matters, add that source for the duration of the move and ask people to link their GitHub account from their Forgejo settings.
SSH keys. Each developer adds their public key under Settings, SSH / GPG keys. On a Pilae instance, Git over SSH answers on its own port on your private network.
Step 3: prove the workflows on a trial import
CI is the long part of the move, so it starts before the import, on a few representative repositories migrated as a trial, the way step 4 describes, while GitHub is still where people work.
Where Forgejo looks for workflows
Forgejo reads workflows from the first of three directories that exists in a commit: .forgejo/workflows, then .gitea/workflows, then .github/workflows. It reads only that one, even if it is empty. A migrated repository therefore runs its .github/workflows files as they are, and the moment a .forgejo/workflows directory appears, the GitHub files are ignored. When you adapt a repository’s workflows, move all of them into .forgejo/workflows in one change. Check that Actions is enabled in each repository, under Settings, Units, Overview.
Runners, labels and images
A job runs on a runner whose label matches its runs-on. A label names an environment, written as <label-name>:<label-type>://<default-image> in the runner’s configuration. ubuntu-latest means nothing to Forgejo until a runner declares a label of that name, and a job asking for a label no runner has is never picked up.
# Forgejo Runner config.yml (excerpt): the labels this runner answers to
runner:
labels:
- 'ubuntu-latest:docker://registry.acme.internal/ci/ubuntu-build'
- 'node:docker://registry.acme.internal/ci/node'
Forgejo’s runner configuration guide suggests mapping ubuntu-latest to a Node.js image to mimic GitHub’s runners, and warns that GitHub’s tools will not all be there. GitHub’s hosted Ubuntu image comes with a long list of preinstalled tools, Docker among them; a runner image carries what you put in it. Build an image with the tools your workflows install today, or add the setup steps to the workflows. Two cases need more than an image:
- Container builds. A job that runs
docker buildneeds a Docker daemon, and job containers get no Docker socket by default. Forgejo documents the options: a separate Docker-in-Docker daemon, or LXC containers that each run their own, while mounting the host’s socket provides no isolation. Its security guide also advises against privileged job containers, because whoever can change a workflow could then act as root on the runner. - macOS and Windows. Forgejo Runner is supported and tested on Linux only, so a job that needs macOS or Windows has no counterpart to GitHub’s hosted runners. List those jobs in step 1 and decide where they run.
How uses: resolves
A short name such as actions/checkout is fetched from the instance’s DEFAULT_ACTIONS_URL, which defaults to data.forgejo.org. That host mirrors a short list, among them checkout, cache, the artifact upload and download actions, and the Node.js, Go and Python setup actions, plus a few of Forgejo’s own such as forgejo-release. Any other action fails to resolve until you give it a full URL, such as https://github.com/owner/action, which the runner then fetches from GitHub at every run. The alternative is to mirror the actions you use into an actions organisation on your instance and point DEFAULT_ACTIONS_URL at it, so CI does not depend on a host outside your network.
What else differs
Forgejo’s comparison with GitHub Actions lists four known differences and says the list may be incomplete. With the events and caching, which its reference and runner configuration cover, these are the ones that break migrated workflows:
permissionsis ignored. The automatic token,FORGEJO_TOKENwithGITHUB_TOKENas an alias, can only act on its own repository and has write access to it, except on pull requests from forks.continue-on-erroris ignored on a job. On a step it works as on GitHub.- Some keys in the
githubcontext are missing. In Forgejo,githubis defined as the same as theforgejocontext. - OIDC tokens for cloud deployments are enabled with the
enable-openid-connectkey, notpermissions: id-token: write. - Events. Push, pull requests, issues and their comments, releases, schedules and manual dispatch are supported. GitHub events Forgejo does not map, such as
workflow_runandmerge_group, never fire. - Caching.
actions/cacheworks against the runner’s own cache server, which the runner’s configuration enables by default.
Actions that call GitHub’s API, to create a release or comment on a pull request, are the ones most likely to fail. Replace them with a Forgejo equivalent or a call to Forgejo’s API. Run every workflow of the trial repositories until it passes, then delete the trial repositories: a migration only creates a repository that does not exist yet.
Step 4: import the repositories in batches
Check two settings on the instance first. ALLOWED_DOMAINS in its [migrations] section, when it is set, must let it reach github.com, *.github.com and *.githubusercontent.com, where release files and LFS objects are served from. And Migrate LFS files only appears when the instance runs its own LFS server.
The token. Without a GitHub token, Forgejo migrates the Git data only: issues, pull requests, labels, milestones and releases need one. Forgejo’s form does not say which scopes. GitHub’s classic repo scope is the one that reads private repositories, and it also grants write access, so create the token on an account that can read every repository being moved, and revoke it when the move is over.
One repository. Choose New migration from the + menu, then GitHub, which reads github.com or GitHub Enterprise Server.
- Enter the repository address under Migrate / Clone from URL, and the token under Access token.
- Leave This repository will be a mirror unticked. A mirror pulls the Git data and the wiki on a schedule and brings none of the items below.
- Tick Migrate LFS files if the repository uses LFS.
- Under Migration items, tick Wiki, Issues, Pull requests, Labels, Milestones and Releases.
- Choose the organisation as owner, keep the repository name, set the visibility, and click Migrate repository. The migration runs in the background.
A batch. The same options go to the API, so a script works through a list of repositories:
# Migrate one GitHub repository into the acme organisation on Forgejo
curl -sS -X POST "https://git.acme.internal/api/v1/repos/migrate" \
-H "Authorization: token ${FORGEJO_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"service": "github",
"clone_addr": "https://github.com/acme/billing-api",
"auth_token": "'"${GITHUB_TOKEN}"'",
"repo_owner": "acme",
"repo_name": "billing-api",
"private": true,
"lfs": true,
"wiki": true, "issues": true, "pull_requests": true,
"labels": true, "milestones": true, "releases": true
}'
The rate limit sets the pace. Each issue, comment and review costs API requests, as does reading its reactions, and GitHub caps the requests a token can make each hour. When the allowance runs out, Forgejo waits for it to reset rather than failing, so the size of a repository’s issue history, not the size of its code, decides how long its import takes. Forgejo accepts several tokens separated by commas to spread the load, and warns on the same form that abusing this may break the provider’s policy and get accounts blocked. Plan batches around the limit instead.
Freeze each batch as it moves. Archive each repository on GitHub just before its import. An archived repository is read-only for everyone but still readable, so the import captures its final state and nobody pushes to a copy that is about to be retired. Rolling back is unarchiving it.
Issues and pull requests keep their numbers, so #123 in a commit message still points at the same item. Open pull requests from forks arrive with their head branches fetched into the repository, where the fork still exists. Images pasted into issues and comments are not copied: the text arrives as written, with its links to GitHub.
The same migration screen reads GitLab, gitlab.com included, and Bitbucket Data Center; a repository on bitbucket.org comes across through the plain Git option, code only.
Step 5: rebuild what stayed behind
Work through the list from step 1, repository by repository, before the batch’s developers switch.
| GitHub | Forgejo |
|---|---|
| Actions secrets | Secrets per repository, organisation or user, entered from where each value lives |
| Actions variables | Variables at the same three levels |
| Branch protection and rulesets | Branch protection rules per repository, by name pattern |
| Required status checks | Status check patterns on the protection rule, matched to what Forgejo Actions reports |
| Webhooks | Webhooks, recreated and tested against each receiver |
| Deploy keys | Deploy keys in each repository’s settings |
| GitHub Apps | A webhook, a bot account with a token, or the tool’s own Forgejo support |
| Dependabot | Renovate, which supports Forgejo as a platform |
| GitHub Packages | Forgejo’s package registry: images and packages pushed again, references updated |
| Projects | Project boards in Forgejo, for the boards still in use |
| Discussions | Readable in the archived repository; decisions worth keeping copied into wiki or issues |
| Codespaces | The dev container configuration stays in the repository for local tools |
Branch protection in Forgejo covers who may push, required approvals, whether stale approvals are dismissed, status checks that must pass, signed commits, blocking merges on requested changes, and protected file patterns. Rulesets that GitHub applies across an organisation become a rule in each repository.
Webhooks are created again in each repository, pointing at the same receivers with a new secret. Forgejo signs each delivery with the same X-Hub-Signature-256 header GitHub uses and sends an X-GitHub-Event header, so a receiver that checks signatures keeps working once it has that secret. The JSON body is Forgejo’s own, so a receiver written for GitHub’s payloads is tested before the GitHub webhook is removed.
Secrets stored in Forgejo cannot be displayed after they are saved, as on GitHub. Where nobody can find the value of a secret, issue a new one from the system it belongs to, which is also a good moment to rotate it.
Step 6: switch remotes and archive GitHub
When a batch has been imported and its workflows pass, its developers switch.
Switching one batch, with a way back
- Freeze: The batch’s GitHub repositories are archived, read-only for everyone.
- Import: Each repository is migrated into Forgejo, and its workflows run.
- Rebuild: Secrets, protection rules and webhooks are in place, and owners compare branches, tags, issues and releases.
- Switch: Developers point their clones at Forgejo, and deployments pull from it.
- Roll back if needed: The GitHub repository is unarchived and the Forgejo copy deleted.
Each developer points every clone at the new address. One clone is one command; a folder of clones is a short loop:
# One clone
git remote set-url origin ssh://git@git.acme.internal:2222/acme/billing-api.git
# Every clone under ~/src that still points at the acme organisation on GitHub
for dir in ~/src/*/; do
url=$(git -C "$dir" remote get-url origin 2>/dev/null) || continue
case "$url" in
git@github.com:acme/* | https://github.com/acme/*)
repo=${url#*github.com[/:]acme/}
git -C "$dir" remote set-url origin "ssh://git@git.acme.internal:2222/acme/${repo%.git}.git"
;;
esac
done
Then the references from step 1: .gitmodules entries followed by git submodule sync, module paths and package manifests, image names that pointed at GitHub’s registry, and every deployment or script that clones from github.com.
Archive what is left on GitHub from each repository’s Settings, under Danger Zone, Archive this repository. GitHub’s documentation describes an archived repository as read-only for all users: code, issues, pull requests and comments stay readable and cannot change. Old links keep resolving until you decide to delete the repositories; keep them at least as long as migrated issues show images hosted on GitHub. Once the last batch has moved, revoke the migration token and narrow ALLOWED_DOMAINS again.
Running Forgejo in production
A forge that every engineer pushes to needs more than the server process.
- PostgreSQL for users, issues, pull requests and permissions. Forgejo also supports MySQL, MariaDB and SQLite, and moving between databases later is not trivial, so production starts on PostgreSQL.
- Disk and a bucket. Git repositories live on a filesystem. LFS objects, packages, attachments and Actions logs and artifacts go to S3-compatible object storage.
- Runners on machines of their own. Forgejo’s documentation says plainly that a runner performs remote code execution, so runners are kept away from the server and from anything a job does not need.
- Backups taken together. The database, the repositories and the bucket are captured at the same point in time, with the secret key from the configuration: without it, a restore cannot decrypt what Forgejo encrypted.
- Upgrades with a way back. Forgejo refuses to start an older release on a database a newer one has migrated, so the rollback is the backup taken just before, and
forgejo doctor checkruns after each upgrade.
Pilae operates Forgejo this way, on PostgreSQL with repositories on local disk and the rest in a bucket, and with runners on machines of their own, jobs in unprivileged containers and actions fetched from mirrors on your instance. Backups are daily, encrypted and stored offsite in the country your contract names, and on Enterprise a restore test runs every month and is recorded in the console. The Pilae Agent tests each upgrade on a copy, waits for your approval, applies it in your window and checks it with forgejo doctor. Forgejo runs on your premises or on dedicated machines in Pilae Cloud, answering only on your private network.
Let Pilae run the move
Pilae runs GitHub to Forgejo migrations at a fixed price: the inventory of what stays behind, organisations, teams and sign-in, runners and a trial import that proves the workflows, the import in batches, the rebuild of secrets, protection and webhooks, and the switch of every batch. Then we operate Forgejo for you under a contract that, from the Business plan, includes a monthly availability commitment with service credits. See migration services for what the fixed price covers, or tell us about your GitHub organisation and we will scope it.
Questions
What does the Forgejo migration bring across from GitHub?
What stays behind on GitHub?
Will our GitHub Actions workflows run on Forgejo?
Should we mirror the repositories or migrate them?
Is Forgejo open source?
How long does a GitHub to Forgejo migration take?
Let us run the move for you
An inventory, a parallel run and a cutover plan, at a fixed price. Then we operate the app.
- Go deeperSaaS migrationA fixed-scope migration off Google Workspace, Microsoft 365, Zapier, Airtable and ChatGPT to open-source apps, with a parallel run and a cutover plan.
- CheckManaged operationsPatching, daily encrypted backups, monitoring and incident response for your open-source apps, under an SLA with an availability commitment of up to 99.9%.
