Skip to main content

GitHub Integration

Automatically sync packages when you push to GitHub.

Setup Webhook​

1. Get Webhook URL​

Your webhook URL is:

https://packages.example.com/api/webhooks/github

2. Create Webhook in GitHub​

  1. Go to your repository Settings > Webhooks
  2. Click Add webhook
  3. Configure:
    • Payload URL: Your webhook URL
    • Content type: application/json
    • Secret: Generate a secure secret
    • Events: Select "Just the push event" or specific events

3. Configure Cargoman​

Set the webhook secret:

GITHUB_WEBHOOK_SECRET=your-webhook-secret

Supported Events​

EventAction
pushSync affected packages
create (tag)Add new version
delete (tag)Remove version

Organization Webhooks​

For multiple repositories, use organization-level webhooks:

  1. Go to Organization Settings > Webhooks
  2. Add webhook with the same configuration
  3. All repositories will trigger syncs

GitHub App​

For easier setup, use the GitHub App integration instead of manual webhooks. The GitHub App:

  • Automatically configures webhooks
  • Provides repository selection UI
  • Handles authentication securely
  • Offers higher API rate limits (5,000/hour per installation)
  • Auto-refreshes tokens (no manual management)

See the GitHub App guide for setup instructions.

Troubleshooting​

Webhook Not Triggering​

Check webhook delivery logs in GitHub:

  1. Go to Settings > Webhooks
  2. Click your webhook
  3. View Recent Deliveries

Authentication Failed​

Ensure your webhook secret matches:

# In Cargoman
GITHUB_WEBHOOK_SECRET=abc123

# In GitHub webhook settings
Secret: abc123

Package Not Syncing​

Verify:

  1. Repository URL matches in Cargoman
  2. Tag format is valid (e.g., v1.0.0)
  3. composer.json exists in repository root

Private Repositories​

For private repositories, configure Git authentication:

# Using personal access token
GIT_AUTH_TOKEN=ghp_xxxx

Or use the GitHub App for automatic credential management (recommended).

Example Workflow​

# .github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate composer.json
        run: composer validate

      # Webhook automatically syncs on tag push
      # No additional steps needed!

Next Steps​