Protected paths in Perforce and Git
For the lead, producer or build engineer who wants a release branch, a demo build or a milestone folder to change only with a yes from the right people. The guide covers the rules, the three ways Gameheim checks them, who can approve, and how a request is approved from the browser or the phone.
Why a release folder needs an approval before every change
Near a milestone, a demo or a certification build, one late submit on the wrong folder can cost a day of builds and testing. Most studios handle it with a message in the team chat: "nobody touches Release until Friday". It works until someone is in another time zone, did not read the chat, or a script submits on its own.
Perforce and the Git hostings can protect a path or a branch, and they do it well. What they cannot know is the production calendar: which folder matters this week, around which milestone, and who on the team is the right person to say yes.
How protected paths work in Gameheim
A rule names the paths (Perforce paths or streams, or Git branches and folders), when it applies and how many approvals it needs. Flag lets every change through and marks it in the feed; Block holds it until enough people approve. The window can be always, the days around a milestone of the project, or two dates, in the studio's time zone.
| Where your project lives | Who checks the change | What it needs |
|---|---|---|
| Perforce | Gameheim extension on the Perforce server | The Gameheim extension 1.3.0 or later on the server, and agent 1.4.0 or later for whoever asks for approvals |
| Perforce with P4 Code Review | Helix Code Review: the review is discussed in Code Review, the submit is still checked by the extension | Everything above, plus Code Review over https, linked from the wizard in the project's protected paths |
| Git on GitHub | Git hosting: GitHub or GitLab, with the Gameheim GitHub App | The App installed on the repository's account, and the check "Gameheim: protected paths" required in the branch rule |
| Git on GitLab.com | Git hosting: GitHub or GitLab, with a service account of the studio | GitLab Premium or Ultimate, and a required approval rule named "Gameheim" |
Set up protected paths on a project
- The permission to manage protected paths (
protected_paths:manage) on the project; a LEAD has it. - Perforce: the Gameheim extension installed on the server (see Install the Gameheim Perforce extension).
- Git: the repository's address set in the project, and the commit webhook in place (see Send your Git pushes to Gameheim).
Open the project's protected paths and choose who checks the changes
In the project, open Protected paths and pick an option under Who checks the submits. On a Perforce project: Gameheim extension on the Perforce server, or Helix Code Review if the studio reviews in P4 Code Review. On a Git project: Git hosting: GitHub or GitLab.
Note:Until the engine is connected, the page says what is missing (an extension too old, a hosting not linked yet) and no rule is applied.Connect the engine
- P4 Code Review: run the wizard on the same page, as a Perforce super user who can both approve and submit without approval on the project. It links Code Review to the extension's service user with a ticket that never reaches Gameheim, and configures the branches of your Block rules. Code Review must be reached over https; a self-signed certificate is fine.
- GitHub: click Connect GitHub, then Install the Gameheim App on GitHub on the account that owns the repository (skip it if it is already there), then Authorize and link. Only an admin of the repository on GitHub can link it. In the repository settings, add "Gameheim: protected paths" to the required status checks of the branch rule, with the Gameheim App as its source.
- GitLab: create a service account, put it alone in a dedicated group with the Reporter role in the project, and create a required approval rule named exactly "Gameheim" whose approver is that group. Paste the account's token (scope api) under Service account token and click Save and verify. Then Check GitLab shows, branch by branch, whether GitLab enforces the rule and which Owners could approve outside Gameheim.
Important:On GitHub, without the required check the status shows on the pull request but does not stop the merge, and Gameheim records the merge as without approval. On GitLab, turn on "Prevent editing approval rules in merge requests" and "Remove all approvals when commits are added to the source branch" in the project's merge request settings, and "Merge request events" on the project's webhook.Create a rule
Click Add a rule and fill in the protected paths, one per line: Perforce paths like
//Ocean/Release/...or streams, or on Git the target branches (likemainorrelease/1.0) and the folders of the repository. Excluded paths stay free inside a protected one.- What happens to a submit without approval: Flag to mark it, Block to hold it.
- When: Always, Before a milestone (days before its date and extra days after), or Between two dates.
- Approvals needed (one to five), how long an approval lasts, and when to remind the approvers and the lead.
- Exemptions for build machines and bots, under Always pass: Perforce users or groups, or hosting logins on Git. Their changes pass and are marked in the feed.
Note:On Git, the exempt logins are checked with GitHub or GitLab when you save: a login that does not exist is refused, and the rule shows the account each login stands for. Link the repository first. If the project's repository changes, save the rule again to check its logins.Give the approvers their permission
In the project's roles, give
protected_paths:approveto the people who say yes.protected_paths:bypasslets someone change a protected path without asking; it applies only through an identity the server or the hosting confirmed and that nobody else shares, and every use of it is in the audit log.Ask for an approval
On Perforce, the author opens the pending changelist in P4 Workspace and clicks Request approval: Gameheim shelves it from the author's agent and creates the request. On Git, the author simply opens a pull request into a protected branch: Gameheim reads its files from the hosting and opens the request when they fall under a Block rule.
Approve or reject
Approvers open the request from the notification, look at the files and click Approve or Reject with a reason. One rejection stops the request. If the content changed after the page was opened, Gameheim asks to look again before approving.
Who can approve a pull request
On Git, Gameheim keeps out of the approvers everyone who wrote code on the pull request: the authors of its commits, and everyone who pushed to its branch as GitHub or GitLab records the push. A commit pushed with someone else's name as author does not let the pusher approve it, and a merge into the branch counts as a push by whoever merged. An approval given before Gameheim knew stops counting.
When Gameheim cannot tell for sure who pushed, the request needs one approval more than its rule asks, and the request page says why. This happens with a pull or merge request from a fork, with a push by an account not linked to Gameheim (bots included), and with a branch older than the history Gameheim reads from the hosting.
Bypass and exemptions on Git
A pull request passes by bypass or exemption only if its author and the authors of all its commits have it, and only when every commit is signed and verified by GitHub or GitLab, with the same author and committer. Commits made in the hosting's web interface, including "Update branch", do not count for a person. Otherwise the pull request asks for approval like any other, and the check and the request say why.
What Gameheim records when a change lands
| Mark in the feed | Meaning |
|---|---|
| Approved | The content that landed is the one the approvers said yes to. |
| Without approval | The change landed on a protected path without a valid approval: under a Flag rule, or on Git a merge or a direct push the hosting let through. Approvers and managers are notified. |
| Exempt | An exempt user, group or bot made the change. |
| Bypass | Someone with protected_paths:bypass made the change. |
| Check failed | On Perforce, the check on the server could not run and let the submit through. The audit log keeps the reason. |
A direct push on a protected Git branch is recorded once the hosting confirms that the commit has no pull request, usually within a few minutes.
Bitbucket, Azure DevOps and hostings of the studio
On these hostings Gameheim cannot hold a merge: rules record what goes in without approval and notify, but do not block. The protected paths page says so and links the repository: protect the branch on the hosting itself.
Frequently asked questions
Do approvers see the content of the files?
No. They see the list of files of the changelist or pull request, not their content.
Can a rule protect a folder only around a milestone?
Yes. Choose Before a milestone, the days before its date and the extra days after. When the milestone moves, the window moves with it, after a confirmation that shows the effect on each rule.
What happens to an approval after new changes?
It no longer counts. On Perforce the author asks again after changing the changelist; on Git new commits on the pull request make it wait for approvals again.
Why does a pull request ask for one more approval than the rule?
Because Gameheim cannot tell for sure who pushed code to it: it comes from a fork, someone pushed with an account not linked to Gameheim, or the branch is older than the history Gameheim reads. The request page says which.
Does GitLab need a paid plan?
Block rules on GitLab need approval rules, which GitLab offers on Premium and Ultimate. On other plans only Flag rules are possible.
Can a build machine keep submitting to a protected path?
Yes. Add its Perforce user or group, or its hosting login on Git, under Always pass in the rule. Its changes pass and are marked as exempt in the feed. On Git its commits must be signed and verified by the hosting.
