3 config

Configuration

This guide will walk you through the configuration process for the github-discord-webhook package.

Configuration Files

The package uses several configuration files located in the config/ directory:

1. payloads.php
2. webhooks.php
3. messages.php
4. allowed.php

Webhooks Configuration

The webhooks.php file is where you define your webhook settings. Here's an example structure:

return [
    'webhook-name' => [
        'url' => 'https://discord.com/api/webhooks/...',
        'secret' => 'your-github-secret-key',
        'repos' => [ 'username/repository-name' ],
    ]
];

• webhook-name: This is the name you'll use in the GitHub webhook URL.
• url: The Discord webhook URL.
• secret: Your GitHub secret key.
• repos: An array of repositories to listen to. Leave empty to listen to all repositories.

Payload Configuration

The payloads.php file defines the classes used to handle different GitHub event payloads:

return [
    'push'    => [
        'commit' => \tei187\GitDisWebhook\Payloads\Push\Commit::class,
        // Add other push events here
    ],
    // Add other GitHub events here
];

Messages Configuration

The messages.php file defines the classes used to format messages for different GitHub events:

return [
    'push' => [
        'commit' => \tei187\GitDisWebhook\Messages\Push\Commit::class,
        // Add other push events here
    ],
    // Add other GitHub events here
];

Allowed Events Configuration

The allowed.php file is used to configure which GitHub events and actions should be processed and sent to the Discord webhook. Here's an example structure:

return [
    'push' => [
        'tag' => [
            'created' => false,
            'deleted' => false,
        ],
        'branch' => [
            'created' => true,
            'deleted' => false,
        ],
        'commit' => true,
    ],
    'ping' => true,
    'fork' => true,
    'release' => [
        'published' => true,
        'released' => false,
        'created' => false,
        'deleted' => false,
    ],
    // ...
];

• The keys represent the event types (e.g., 'push', 'pull_request').
• The values are either boolean (true/false) or nested arrays for more specific actions.
• Set an event or action to true to allow it to be processed and sent to Discord.
• Set an event or action to false to prevent it from being processed and sent to Discord.

This configuration allows you to fine-tune which events and actions trigger notifications in your Discord channel, overriding dependency on GitHub repository settings alone.

If an event is not defined within this config file, or if the path from PayloadAbstract object cannot be found here or in its profile's overrides, the call will not be processed further. It is mainly a safe guard measure to not process additional events, even though the repository settings are making calls for.

IMPORTANT: Following same structure requirement

The key concept of organization within this package revolves around "event paths" which have to be mirrored whenever an identifying path is required. So, for example, if we are using a push event, with tag subject, and deleted action, all of the objects and configs have to point to the same array structure, which in this case will be ['push']['tag']['deleted']. This requirement will span around webhook overrides, payloads, messages and allowed states configuration files, as well as objects extending PayloadAbstract classes (properties event, subject, tag).

Setting Up

1. Copy the configuration files from config/.php.example to config/.php.
2. Edit config/webhooks.php to add your Discord webhook URL and GitHub secret.
3. Customize the payloads.php and messages.php files if you need to handle additional events or change the formatting.

GitHub Webhook Setup

1. Go to your GitHub repository settings.
2. Navigate to Webhooks > Add webhook.
3. Set the Payload URL to http://your-domain.com/webhook/[webhook-name].
4. Choose application/json as the content type.
5. Enter your secret key (must match the one in webhooks.php).
6. Select which events you want to trigger the webhook (if not set, only push events notifications will be sent).

After completing these steps, your github-discord-webhook should be fully configured and ready to use!