Private Packages

Appearance

GitHub ​

Recipe for managing packages hosted in a GitHub repository. Supports both public and private repositories. New releases are created automatically via webhook when a release is published on GitHub, and can also be fetched on demand via the package update command.

Configuration ​

Repository ​

  • Label: Repository
  • Required: Yes
  • Type: Text
  • Placeholder: owner/repo
  • Helper Text: The GitHub repository slug, e.g. acme/my-plugin

GitHub Token (fine-grained PAT) ​

  • Label: GitHub Token (fine-grained PAT)
  • Required: Only for private repositories
  • Type: Secret
  • Helper Text: Required for private repositories. See How to obtain a GitHub token below.

Webhook Secret ​

  • Label: Webhook Secret
  • Required: Yes
  • Type: Secret
  • Helper Text: The secret you set when creating the webhook in GitHub repository settings. See How to set up the webhook below.

How to obtain a GitHub token ​

A fine-grained personal access token (PAT) is required to download release assets from private repositories. Public repositories do not need a token.

  1. Go to GitHub and sign in
  2. Click your avatar in the top-right corner → Settings
  3. In the left sidebar, scroll down and click Developer settings
  4. Click Personal access tokens → Fine-grained tokens
  5. Click Generate new token
  6. Give the token a descriptive name (e.g. Private Packages – my-plugin)
  7. Set an expiration date
  8. Under Repository access, select Only select repositories and choose the repository
  9. Under Permissions → Repository permissions, scroll down to Contents and set it to Read-only
  10. Click Generate token and copy the token immediately — it is only shown once

Paste the token into the GitHub Token field when configuring the package.

How to set up the webhook ​

Each repository needs its own webhook so GitHub can notify Private Packages when a new release is published.

  1. Go to your repository on GitHub
  2. Click Settings → Webhooks → Add webhook
  3. Set the Payload URL to your workspace-specific webhook URL. You can find this in the package settings in Private Packages.
  4. Set Content type to application/json
  5. Copy the Webhook Secret from the package settings in Private Packages and paste it into the Secret field
  6. Under Which events would you like to trigger this webhook?, choose Let me select individual events, uncheck Pushes, and check Releases
  7. Make sure Active is checked
  8. Click Add webhook

How it works ​

When a new release is published on GitHub (i.e. a tag is created and marked as a release), GitHub sends a webhook event to Private Packages. The signature of the payload is verified against the webhook secret stored for that package. If the signature matches, a new release is automatically created and made available through Composer.

Releases can also be fetched by using the update button, which calls the GitHub Releases API directly to check for the latest version.

Tags vs Releases

Pushing a tag alone is not enough. You need to publish a Release in GitHub (Releases → Draft a new release → select your tag → Publish release). This is what triggers the webhook and what the GitHub API exposes.

Tag format

Both v1.2.3 and 1.2.3 tag formats are supported. The v prefix is stripped automatically when determining the version number.

Release assets

You do not need to attach a .zip file to the release. If one is present, it will be used. Otherwise Private Packages falls back to GitHub's source code archive automatically, using your token if the repository is private.

Notes ​

  • Public repositories do not require a GitHub token
  • Each repository should have its own webhook and webhook secret
  • The webhook secret is verified using HMAC-SHA256, matching GitHub's X-Hub-Signature-256 header
  • Releases are created automatically both when GitHub sends a webhook event and when the package update command runs