Gameheim

Send your Git pushes to Gameheim: the commit feed and tasks from commits

For the LEAD of a Git project in Gameheim. One webhook on the repository, set up in a few minutes, and every push reaches the project's Commits page, from any machine or tool. The guide covers each hosting, the GitLab signing token, tasks updated from commit messages and what to check when a push does not arrive.

By Gianmarco Virzì, co-founder and lead developer of Virsion · Updated · 6 min read

Pushes made outside Gameheim are invisible to the project

People push from their IDE, from the command line, from build machines. A tool that only sees the pushes it made itself misses most of the history of the project, and the tasks a commit was meant to close stay open until someone remembers to close them by hand.

Every Git hosting can call another service when a push arrives: that call is a webhook. Setting one up by hand means choosing the events, keeping a secret on both sides and checking now and then that the deliveries still arrive.

How the webhook brings your commits to Gameheim

Your hosting calls Gameheim at every push, with a secret that only the hosting and Gameheim know. Each commit then appears on the project's Commits page with its message, author, branch and changed files, and you can filter by branch, author, folder or text.

Each person sees the commits once Gameheim knows they can read the repository: through their own Git token on a public hosting, or through their Gameheim agent and the clone it works in. Someone who cannot read the repository does not see its commits in Gameheim either.

Received for each commitNever received
Commit id, message, author, date and branchThe content of any file
The paths of the changed files and how each one changedYour Git password or token

How to connect your Git repository to Gameheim

Before you start
  • LEAD or ADMIN role in the Gameheim project.
  • A Gameheim project that works on Git, with its remote set.
  • The rights to add a webhook on the repository: for example admin of the repository on GitHub, Maintainer on GitLab, project administrator on Azure DevOps.
  1. Create the webhook secret

    Edit the project and follow Git webhook: send the pushes to the changelist feed. Choose your hosting and click Create the webhook secret. Copy the Payload URL and the Secret right away: the secret is shown only this once.

  2. Add the webhook on your hosting

    • GitHub: Settings → Webhooks → Add webhook, paste the URL and the secret, select Just the push event.
    • GitLab: Settings → Webhooks → Add new webhook, paste the URL, put the secret in Secret token, select Push events, and Merge request events if the project uses protected paths.
    • Bitbucket Cloud: Repository settings → Webhooks → Add webhook, paste the URL and the secret, trigger Repository push. Bitbucket does not send the files of each commit: the Gameheim agents fill them in.
    • Azure DevOps: Project settings → Service hooks → Web Hooks, event Code pushed, paste the URL, and in HTTP headers write X-Gameheim-Token: followed by the secret.
    • Gitea: Settings → Webhooks → Add webhook → Gitea, paste the URL and the secret, content type application/json, trigger Push events.
    • Your own Git server: click Download gameheim-post-receive.py, put the file as hooks/post-receive in the bare repository (Python 3), make it executable and run the two commands the page shows in the repository.
  3. GitLab: add the signing token

    Recommended on GitLab 19.0 or later. Edit the webhook in GitLab, select Generate signing token, copy it (GitLab shows it once) and paste it under GitLab signing token in Gameheim. From then on Gameheim accepts only deliveries signed by GitLab. Keep the secret token in GitLab until the first signed delivery arrives.

  4. Check the first delivery

    Push a commit. The webhook page shows Last delivery with its time, and the commit appears on the project's Commits page.

  5. Optional: update tasks from commit messages

    Under Tasks from the pushed commits, turn on The pushed commits update tasks, bugs and decisions and list the branches allowed, one per line: main allows that branch, release/* every branch under it. A commit with #KEY done, #KEY progress:NN or #KEY in its message then updates the task, recorded under the person who pushed. A task changed after the push arrived is left alone.

    Note:Gameheim acts on its own only when the account that pushed is a hosting account it verified for exactly one person, and only after the hosting confirms the push to that person's token. Otherwise the commit shows the change with an Apply button, and whoever clicks it is recorded as its author. Bitbucket Cloud and your own Git server cannot confirm who pushed: there every change is applied with Apply.

Keep the webhook secret safe

Anyone who knows the secret can send pushes in the project's name, so treat it like a password: keep it only on the hosting. Replace the secret creates a new one and changes the URL too, and the old ones stop working at once: set the new URL and secret on the hosting right after. The page shows when the secret was created and by whom.

When someone who knows the secret no longer has access to the project, the page says so and the LEAD and the ADMIN get a notice. Replace the secret and set the new one on the hosting.

Troubleshooting: a push does not reach Gameheim

What you seeWhat to do
No delivery yet. after a pushOpen the webhook's delivery log on the hosting and check the URL and the secret. On Azure DevOps check the header name, X-Gameheim-Token.
Waiting for the Git hosting to confirm the pushNormal for a few minutes: Gameheim asks the hosting again for up to 30 minutes. The token of the person who pushed must be able to read the repository's activity.
Not applied: the Git hosting did not confirm who pushed this commitThe hosting did not confirm the push to that person's token. Anyone allowed to change the task can still click Apply.
A person sees no commitsTheir Git token is not verified yet, or their Gameheim agent has not yet confirmed that they can read the repository.
A notice says the webhook was not receivedAn agent found a commit the webhook did not deliver. Check the webhook on the hosting: it may be disabled, or its secret replaced.

Frequently asked questions

Does a push wait for Gameheim?

No. The hosting calls Gameheim after the push is done, so nobody waits for it.

Does Gameheim receive the content of our files?

No. It receives what the hosting sends for a push: commit ids, messages, authors, branches and the paths of the changed files. Never the content of a file.

Which hostings confirm who pushed a commit?

GitHub, GitLab and Azure DevOps. Bitbucket Cloud does not, so changes to tasks from its commits are applied with Apply.

What if the webhook stops working?

Gameheim agents fetch the repository and add the commits the webhook did not deliver within ten minutes, and the LEAD and the ADMIN get a notice so they can fix the webhook.