Publishing to GitHub
The big picture: your workflow stays on GitLab. A one-way push mirror copies every protected branch and tag to a GitHub repository, so the project shows up where people actually search.
Why it matters: new public projects are found on GitHub: search, topics, stars, the trending page. If you want users or contributors, a GitLab-only repo is hard to stumble on. Mirroring buys that exposure without moving issues, MRs, or CI.
How it works:
- GitLab pushes to GitHub on every change. Nothing flows back.
- The GitHub repo is labeled a read-only mirror, with issues and PRs pointed at GitLab.
- This is about being found. Running Blueprint’s CI on GitHub Actions is a separate question, tracked in issue macrodream/blueprint#46.
Set up the mirror
Section titled “Set up the mirror”- Create an empty GitHub repository. No README, no license file; the mirror supplies them.
- Create a fine-grained GitHub token scoped to that one repository, with Contents: read and write. Set an expiry and put the date in your calendar.
- In GitLab: Settings → Repository → Mirroring repositories. Enter
https://github.com/<owner>/<repo>.git, choose Push, enter your GitHub username, and paste the token as the password. GitLab’s mirroring docs list the token types it supports; if a fine-grained token is rejected, use a classic token withreposcope. - Tick “Mirror only protected branches” so feature branches and WIP never leave
GitLab. Make sure
mainand your release tags are protected. - Check the first sync (the Update now button, then the mirror’s status line). A failed mirror shows an error there; it won’t fail your pipeline.
Before the first push, sweep for things you can’t take back. A public mirror
exposes the whole history of every protected branch, not just the latest commit.
Search it for secrets, internal hostnames, private issue links, and code that belongs to
a paid edition. Run gitleaks over the full history, not just the working tree.
Decide first: mirror, or GitLab only?
Section titled “Decide first: mirror, or GitLab only?”The choice decides what stays in .github/:
| Choice | Issue and PR templates under .github/ |
.github/dependabot.yml |
|---|---|---|
| GitLab only (no mirror) | Not needed | Delete it (the file says so); use renovate.json |
| Public push mirror | Add them, pointing at GitLab (below) | Delete it: Dependabot opens PRs on GitHub, where you have turned PRs off |
Blueprint ships .github/dependabot.yml only. If you do not mirror, delete the whole
.github/ directory. /kickoff asks this question in Round 3 (the forge question offers
“GitLab, also mirrored to GitHub”, GitLab projects only) and does the rest: on “yes” it adds
the banner below to the README and writes the redirect templates under .github/, on “no”
it deletes .github/. You still set up the push mirror and turn off GitHub Issues and pull
requests yourself.
Do not mirror a private repository. A push mirror copies every protected branch and tag, full history included, to a second host with its own access controls. Private code stays on GitLab.
Say it’s a mirror
Section titled “Say it’s a mirror”Contributors will open issues and PRs on GitHub unless told not to. Do three things.
1. Add the canonical-source banner to the README
Section titled “1. Add the canonical-source banner to the README”TruePPM puts this at the top of its README (TruePPM is the worked example for this whole guide). Copy it and replace the placeholders:
> **Canonical source: gitlab.com/<group>/<project>**: issues and merge requests are> handled there. The GitHub repository is a read-only mirror for discovery; it does not> accept issues or pull requests.2. Turn off GitHub Issues and pull requests
Section titled “2. Turn off GitHub Issues and pull requests”In the GitHub repository’s Settings → General → Features, untick Issues and Pull requests (and Projects and Wiki if you do not use them). If you leave pull requests enabled, the PR template below is the fallback that redirects them.
3. Add redirect templates under .github/
Section titled “3. Add redirect templates under .github/”.github/ISSUE_TEMPLATE/config.yml replaces the issue chooser with a link to GitLab.
blank_issues_enabled, and contact_links with name, url and about, are the keys
GitHub’s issue-template configuration reads. Keep this file even with Issues turned off:
it covers the case where someone turns them back on.
blank_issues_enabled: falsecontact_links: - name: Report a bug or request a feature on GitLab url: https://gitlab.com/<group>/<project>/-/issues/new about: This GitHub repository is a read-only mirror. Issues are handled on GitLab. - name: Report a security vulnerability url: https://gitlab.com/<group>/<project>/-/blob/main/SECURITY.md about: Do not open a public issue for a vulnerability. Follow the private process..github/PULL_REQUEST_TEMPLATE.md greets anyone who opens a PR anyway:
**This GitHub repository is a read-only mirror. Pull requests are not reviewed here.**
Please open a merge request on GitLab instead:https://gitlab.com/<group>/<project>/-/merge_requests/new
See CONTRIBUTING.md for how to set up and what gets reviewed. This PR will be closed.Keep CI on GitLab only: GitHub Actions workflows would run against a mirror nobody merges into.
Distribute releases from GitHub
Section titled “Distribute releases from GitHub”The mirror carries tags, so a release can also appear where people look. These are options, not requirements:
- GitHub Releases. Create a release for each tag so the repository’s Releases sidebar is populated. Create it from GitLab CI on tag pipelines only, with a token stored as a masked, protected CI/CD variable. Never create releases from branch pipelines.
- GHCR images. Push container images to
ghcr.io/<owner>/<repo>from the same tag pipeline, with the storedGHCR_TOKENvariable. Whether to use GHCR, the GitLab registry, or both is covered in Choosing a registry.
A sketch of the Releases job, in the style of the other jobs in .gitlab-ci.yml. It is
untested: check the stage, image, variable names and the gh install step against your
own pipeline before relying on it.
github-release: stage: deploy image: alpine:3.23 # pin by digest like the other jobs rules: - if: $CI_COMMIT_TAG script: - apk add --no-cache github-cli - > GH_TOKEN="$GITHUB_RELEASE_TOKEN" gh release create "$CI_COMMIT_TAG" --repo "<owner>/<repo>" --title "$CI_COMMIT_TAG" --notes-file "docs/releases/$CI_COMMIT_TAG.md"Write a maintainer runbook
Section titled “Write a maintainer runbook”The mirror fails quietly: the token expires, the sync stops, and the GitHub copy goes
stale with nobody told. Put a short runbook in docs/maintainers/github-mirror.md.
TruePPM keeps one. A starting outline:
# GitHub mirror runbook
## What this isOne-way push mirror: GitLab (canonical) to github.com/<owner>/<repo>. Nothing flows back.
## Setup- GitLab: Settings > Repository > Mirroring repositories (Push, protected branches only)- GitHub: fine-grained token, this repository only, Contents: read and write- Protected on GitLab: main and release tags
## GitHub repository settings- Issues, Projects, Wiki: off- Description, topics and the "Canonical source" README banner are set
## Token rotation- Token owner: <role, not a person>- Expiry date: <date>; rotate two weeks before- Rotate: create the new token, paste it into the mirror's password field, run "Update now", confirm the status line, then revoke the old token
## When the mirror fails1. Open the mirror's status line in GitLab and read the error2. Expired or revoked token: rotate as above3. Rejected push or diverged history: someone pushed to GitHub directly. Do not force-push main; ask in the maintainers channel4. After a fix, "Update now" and confirm the latest tag appears on GitHub
## ReleasesTags and the GitHub Release come from the tag pipeline; do not create them by hand.GitHub-side polish
Section titled “GitHub-side polish”- A one-line description and topics, since GitHub search ranks on them
- A social preview image
- The license detected correctly (GitHub shows it in the sidebar)
- A short, honest README: what it is, who it’s for, how to run it in under five minutes
Public-project readiness checklist
Section titled “Public-project readiness checklist”A visitor decides in about a minute whether a project looks maintained and safe to depend on. These are the files and signals they look for. TruePPM has every one in its repository root.
| Item | Why | Blueprint provides |
|---|---|---|
LICENSE (and NOTICE if you bundle third-party code) |
Without one, nobody can legally use it | LICENSE |
README stating what it is and how to start |
The first thing read | README.md (describes Blueprint; replace it with yours) |
CONTRIBUTING |
Says how to help and what gets reviewed | CONTRIBUTING.md |
SECURITY.md |
A private route for vulnerability reports | /kickoff writes one for public projects; otherwise add one |
CODE_OF_CONDUCT |
Signals a safe place to contribute | Not provided; add one |
GOVERNANCE (if there’s a team or an open-core split) |
Who decides, and what stays closed | Not provided — see Open core and editions |
| Issue and PR templates | Keep reports useful | GitLab templates in .gitlab/; add .github/ ones that point back to GitLab (templates above) |
| Badges: license, quality gate, pipeline | Quick trust signals | Not provided |
Bottom line: keep working on GitLab, mirror to GitHub so people can find you, and make the mirror look like a project someone would trust before you press the button.