[#exec-webhook-github]
= GitHub Webhooks

OliveTin includes built-in templates for GitHub webhooks that simplify configuration. Instead of manually configuring header matching and argument extraction, you can use a template that handles all the common settings for you.

== Supported GitHub Templates

OliveTin supports the following GitHub webhook templates:

* `github-push` - Triggered on push events
* `github-pr` or `github-pull-request` - Triggered on pull request events
* `github-release` - Triggered on release events
* `github-workflow` - Triggered on workflow run events

== Setting Up GitHub Webhooks

=== 1. Configure the Webhook in GitHub

1. Go to your GitHub repository → **Settings** → **Webhooks** → **Add webhook**
2. Set the **Payload URL** to `http://your-olivetin-server:1337/webhooks`
3. Set **Content type** to `application/json`
4. Enter a **Secret** (you'll use this in your OliveTin config)
5. Choose which events to trigger the webhook:
   - Select **Just the push event** for push triggers
   - Or select **Let me select individual events** for more control
6. Click **Add webhook**

=== 2. Configure OliveTin

Use the `template` property to apply GitHub-specific settings:

[source,yaml]
.`config.yaml`
----
actions:
  - title: Deploy on Push
    shell: |
      echo "Deploying commit {{ git_commit }} to {{ git_branch }}"
      /opt/scripts/deploy.sh "{{ git_branch }}"
    arguments:
      - name: git_commit
        type: ascii
      - name: git_branch
        type: ascii
    execOnWebhook:
      - template: github-push
        secret: your-github-webhook-secret
----

== GitHub Push Template

The `github-push` template is designed for push events. It automatically:

* Sets authentication to HMAC-SHA256 with the `X-Hub-Signature-256` header
* Matches the `X-GitHub-Event: push` header
* Extracts common push event data

=== Extracted Arguments

The following arguments are automatically extracted and available in your action:

[cols="1,2,2"]
|===
|Argument Name |Description |JSONPath

|`git_repository`
|Full repository name (owner/repo)
|`$.repository.full_name`

|`git_ref`
|Full git reference (e.g., refs/heads/main)
|`$.ref`

|`git_commit`
|The HEAD commit SHA
|`$.head_commit.id`

|`git_branch`
|The branch reference
|`$.ref`

|`git_message`
|The commit message
|`$.head_commit.message`

|`git_author`
|The commit author's name
|`$.head_commit.author.name`
|===

=== Example: Deploy on Push to Main

[source,yaml]
----
actions:
  - title: Deploy to Production
    shell: |
      if [ "{{ git_ref }}" = "refs/heads/main" ]; then
        echo "Deploying {{ git_commit }} by {{ git_author }}"
        /opt/scripts/deploy.sh production
      else
        echo "Ignoring push to non-main branch"
      fi
    arguments:
      - name: git_ref
        type: ascii
      - name: git_commit
        type: ascii
      - name: git_author
        type: ascii
    execOnWebhook:
      - template: github-push
        secret: your-secret
----

=== Example: Filter by Branch

To only trigger on specific branches, add a `matchPath` condition:

[source,yaml]
----
actions:
  - title: Deploy Staging
    shell: /opt/scripts/deploy.sh staging
    execOnWebhook:
      - template: github-push
        secret: your-secret
        matchPath: '$.ref="refs/heads/develop"'
----

== GitHub Pull Request Template

The `github-pr` (or `github-pull-request`) template handles pull request events.

=== Extracted Arguments

[cols="1,2,2"]
|===
|Argument Name |Description |JSONPath

|`pr_number`
|Pull request number
|`$.number`

|`pr_title`
|Pull request title
|`$.pull_request.title`

|`pr_author`
|PR author's username
|`$.pull_request.user.login`

|`pr_action`
|Event action (opened, closed, synchronize, etc.)
|`$.action`

|`git_repository`
|Full repository name
|`$.repository.full_name`

|`pr_state`
|PR state (open, closed)
|`$.pull_request.state`

|`pr_head_sha`
|HEAD commit SHA of the PR branch
|`$.pull_request.head.sha`
|===

=== Example: Run Tests on PR

[source,yaml]
----
actions:
  - title: Run PR Tests
    shell: |
      echo "Running tests for PR #{{ pr_number }}: {{ pr_title }}"
      echo "Action: {{ pr_action }}, Author: {{ pr_author }}"
      /opt/scripts/run-tests.sh "{{ pr_head_sha }}"
    arguments:
      - name: pr_number
        type: ascii
      - name: pr_title
        type: ascii
      - name: pr_action
        type: ascii
      - name: pr_author
        type: ascii
      - name: pr_head_sha
        type: ascii
    execOnWebhook:
      - template: github-pr
        secret: your-secret
----

=== Example: Only on PR Open or Synchronize

[source,yaml]
----
actions:
  - title: CI Build
    shell: /opt/scripts/ci-build.sh "{{ pr_head_sha }}"
    arguments:
      - name: pr_head_sha
        type: ascii
    execOnWebhook:
      - template: github-pr
        secret: your-secret
        matchPath: '$.action="opened"'
      - template: github-pr
        secret: your-secret
        matchPath: '$.action="synchronize"'
----

== GitHub Release Template

The `github-release` template handles release events.

=== Extracted Arguments

[cols="1,2,2"]
|===
|Argument Name |Description |JSONPath

|`release_action`
|Release action (published, created, etc.)
|`$.action`

|`release_tag`
|Release tag name
|`$.release.tag_name`

|`release_name`
|Release name/title
|`$.release.name`

|`git_repository`
|Full repository name
|`$.repository.full_name`

|`release_author`
|Release author's username
|`$.release.author.login`
|===

=== Example: Deploy on Release

[source,yaml]
----
actions:
  - title: Deploy Release
    shell: |
      echo "Deploying release {{ release_tag }}: {{ release_name }}"
      /opt/scripts/deploy-release.sh "{{ release_tag }}"
    arguments:
      - name: release_tag
        type: ascii
      - name: release_name
        type: ascii
    execOnWebhook:
      - template: github-release
        secret: your-secret
        matchPath: '$.action="published"'
----

== GitHub Workflow Template

The `github-workflow` template handles workflow run events, useful for triggering actions when GitHub Actions workflows complete.

=== Extracted Arguments

[cols="1,2,2"]
|===
|Argument Name |Description |JSONPath

|`workflow_name`
|Name of the workflow
|`$.workflow_run.name`

|`workflow_status`
|Workflow status
|`$.workflow_run.status`

|`workflow_conclusion`
|Workflow conclusion (success, failure, etc.)
|`$.workflow_run.conclusion`

|`git_repository`
|Full repository name
|`$.repository.full_name`

|`git_commit`
|HEAD commit SHA
|`$.workflow_run.head_sha`

|`git_branch`
|Branch that triggered the workflow
|`$.workflow_run.head_branch`
|===

=== Example: Deploy After CI Success

[source,yaml]
----
actions:
  - title: Deploy After CI
    shell: |
      echo "CI workflow '{{ workflow_name }}' completed with {{ workflow_conclusion }}"
      if [ "{{ workflow_conclusion }}" = "success" ]; then
        /opt/scripts/deploy.sh "{{ git_branch }}" "{{ git_commit }}"
      fi
    arguments:
      - name: workflow_name
        type: ascii
      - name: workflow_conclusion
        type: ascii
      - name: git_branch
        type: ascii
      - name: git_commit
        type: ascii
    execOnWebhook:
      - template: github-workflow
        secret: your-secret
        matchPath: '$.action="completed"'
----

== Customizing Templates

Templates provide default values, but you can override or extend them:

[source,yaml]
----
actions:
  - title: Custom Push Handler
    shell: echo "Push from {{ custom_field }}"
    arguments:
      - name: custom_field
        type: ascii
      - name: git_commit
        type: ascii
    execOnWebhook:
      - template: github-push
        secret: your-secret
        # Add additional extractions
        extract:
          custom_field: "$.sender.login"
        # Add additional match criteria
        matchPath: '$.repository.private=false'
----

Custom `extract` values are merged with template defaults, so you can add extra fields without losing the standard ones.

== Security Considerations

1. **Always use a secret** - Without a secret, anyone can trigger your webhooks
2. **Use HTTPS** - When exposing OliveTin to the internet, use a reverse proxy with TLS
3. **Limit webhook events** - Only subscribe to the events you actually need in GitHub
4. **Validate in your scripts** - Add additional validation in your shell scripts for sensitive operations

== Troubleshooting

=== Webhook Not Triggering

1. Check the OliveTin logs with `logLevel: DEBUG` for webhook processing details
2. Verify the webhook is being received (check GitHub webhook delivery history)
3. Ensure the secret matches exactly between GitHub and OliveTin config
4. Verify the `template` name is spelled correctly

=== Signature Verification Failed

1. Ensure the secret in OliveTin matches the one configured in GitHub
2. Check that you're using the correct template (GitHub uses HMAC-SHA256 by default)
3. Make sure the webhook Content-Type is set to `application/json`

=== Arguments Not Extracted

1. Verify the argument names match exactly (case-sensitive)
2. Check that arguments are defined in the action's `arguments` list
3. Use `logLevel: DEBUG` to see extracted values in the logs

== See Also

* xref:action_execution/onwebhook.adoc[Webhooks Overview] - General webhook configuration
* xref:solutions/on-git-push/index.adoc[GitOps Solution] - Alternative approach using Git hooks
* https://docs.github.com/en/webhooks[GitHub Webhooks Documentation^] - Official GitHub webhook documentation