app/flatpages/help/release_webhooks.md

   1 title: Creating Releases using Webhooks
   2
   3 ## What does this mean?
   4
   5 A webhook is a notification from one service to another. Put simply, a webhook
   6 is used to notify ContentDB that the git repository has changed.
   7
   8 ContentDB offers the ability to automatically create releases using webhooks
   9 from either Github or Gitlab. If you're not using either of those services,
  10 you can also use the [API](../api) to create releases.
  11
  12 The process is as follows:
  13
  14 1. The user creates an API Token and a webhook to use it. This can be done automatically
  15    for Github.
  16 2. The user pushes a commit to the git host (Gitlab or Github).
  17 3. The git host posts a webhook notification to ContentDB, using the API token assigned to it.
  18 4. ContentDB checks the API token and issues a new release.
  19
  20 ## Setting up
  21
  22 ### GitHub (automatic)
  23
  24 1. Go to your package's page.
  25 2. Make sure that the repository URL is set to a Github repository.
  26    Only github.com is supported.
  27 3. Go to "Releases" > "+", and click "Setup webhook" at the top of the create release
  28    page.
  29    If you do not see this, either the repository isn't using Github or you do
  30    not have permission to use webhook releases (ie: you're not a Trusted Member).
  31 4. Grant ContentDB the ability to manage Webhooks.
  32 5. Set the event to either "New tag or Github Release" (highly recommended) or "Push".
  33
  34    N.B.: GitHub uses tags to power GitHub Releases, meaning that creating a webhook
  35    on "New tag" will sync GitHub and ContentDB releases.
  36
  37 ### GitHub (manual)
  38
  39 1. Create a ContentDB API Token at [Profile > API Tokens: Manage](/user/tokens/).
  40 2. Copy the access token that was generated.
  41 3. Go to the GitLab repository's settings > Webhooks > Add Webhook.
  42 4. Set the payload URL to `https://content.minetest.net/github/webhook/`
  43 5. Set the content type to JSON.
  44 6. Set the secret to the access token that you copied.
  45 7. Set the events
  46   * If you want a rolling release, choose "just the push event".
  47   * Or if you want a stable release cycle based on tags,
  48     choose "Let me select" > Branch or tag creation.
  49 8. Create.
  50
  51 ### GitLab (manual)
  52
  53 1. Create a ContentDB API Token at [Profile > API Tokens: Manage](/user/tokens/).
  54 2. Copy the access token that was generated.
  55 3. Go to the GitLab repository's settings > Webhooks.
  56 4. Set the URL to `https://content.minetest.net/gitlab/webhook/`
  57 6. Set the secret token to the ContentDB access token that you copied.
  58 7. Set the events
  59     * If you want a rolling release, choose "Push events".
  60     * Or if you want a stable release cycle based on tags,
  61       choose "Tag push events".
  62 8. Add webhook.
  63
  64 ## Configuring
  65
  66 See the [Package Configuration and Releases Guide](/help/package_config/) for
  67 documentation on configuring the release creation.
  68 You can set the min/max Minetest version from the Git repository, and also
  69 configure what files are included.