#Incoming Webhooks

Incoming webhooks allow you to trigger pipelines directly via HTTP POST requests, without requiring Git events.

#Overview

Incoming webhooks provide a way to:

• Trigger pipelines from external systems
• Integrate with CI/CD tools that don't use Git
• Trigger pipelines manually or via API calls
• Support custom payloads and parameters

#Configure Incoming Webhook

1. Enable in Repository CR: Add incoming webhook configuration to your Repository CR:

   apiVersion: pipelinesascode.tekton.dev/v1alpha1
   kind: Repository
   metadata:
     name: my-repo
     namespace: project-pipelines
   spec:
     url: "https://gitlab.com/user/repo"
     git_provider:
       type: gitlab
       url: "https://gitlab.com"
       secret:
         name: gitlab-secret
         key: token
       webhook_secret:
         name: webhook-secret
         key: secret
     # Incoming webhook configuration
     incoming:
     - type: webhook-url
       secret:
         name: incoming-webhook-secret
         key: secret

2. Create incoming webhook secret:

   kubectl create secret generic incoming-webhook-secret \
     --from-literal=secret=your-incoming-webhook-secret \
     -n project-pipelines

3. Get incoming webhook URL:

The incoming webhook endpoint is:

http://<pac-controller-url>/incoming

URL Parameters (optional, can also be passed via headers):

• repository: Repository CR name
• namespace: Namespace where Repository CR is located
• secret: Incoming webhook secret value

Example with query parameters:

http://pac.example.com/incoming?repository=my-repo&namespace=project-pipelines&secret=your-secret

Example with headers (recommended for security):

http://pac.example.com/incoming

With headers: X-Repository, X-Namespace, X-Secret

#Trigger Pipeline via Incoming Webhook

Send a POST request to the incoming webhook endpoint:

curl -X POST \
  http://pac.example.com/incoming \
  -H "Content-Type: application/json" \
  -H "X-Repository: my-repo" \
  -H "X-Namespace: project-pipelines" \
  -H "X-Secret: your-incoming-webhook-secret" \
  -d '{
"ref": "refs/heads/main",
"sha": "abc123def456...",
"repository": {
  "url": "https://gitlab.com/user/repo"
}
  }'

#Incoming Webhook Payload

The incoming webhook accepts a JSON payload with the following structure:

{
  "ref": "refs/heads/main",
  "sha": "commit-sha",
  "repository": {
    "url": "https://gitlab.com/user/repo",
    "name": "repo-name",
    "full_name": "user/repo"
  },
  "sender": {
    "login": "username"
  },
  "head_commit": {
    "message": "Commit message",
    "author": {
      "name": "Author Name",
      "email": "author@example.com"
    }
  }
}

#Custom Parameters

You can pass custom parameters in the webhook payload:

{
  "ref": "refs/heads/main",
  "sha": "abc123...",
  "repository": {
    "url": "https://gitlab.com/user/repo"
  },
  "params": {
    "environment": "production",
    "deploy": "true"
  }
}

These parameters are available in your pipeline as $(params.environment) and $(params.deploy).

#Security Considerations

1. Use secrets: Always use webhook secrets to validate requests
2. HTTPS: Use HTTPS for webhook endpoints in production
3. Network policies: Restrict access to incoming webhook endpoints
4. Rate limiting: Implement rate limiting to prevent abuse
5. Validate payloads: Validate incoming payloads before processing

#Troubleshooting Incoming Webhooks

1. Check webhook URL: Verify the URL is correct and accessible

2. Verify secret: Ensure the secret matches in both request and Repository CR

3. Check PAC logs:

   kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep incoming  # Replace <pac-namespace> with your actual namespace (default: tekton-pipelines)

4. Verify Repository CR: Ensure incoming webhook is configured correctly

5. Test with curl: Use curl to test the webhook endpoint

#Best Practices

#1. PipelineRun Management

• Set cleanup limits: Use max-keep-runs to prevent accumulation
• Monitor resources: Watch for resource usage from PipelineRuns
• Archive important runs: Export important PipelineRuns before cleanup

#2. Monitoring

• Use labels: Label PipelineRuns for easier filtering
• Set up alerts: Configure alerts for failed PipelineRuns
• Regular reviews: Periodically review PipelineRun status and logs

#3. Incoming Webhooks

• Secure endpoints: Always use HTTPS and secrets
• Validate payloads: Validate incoming webhook payloads
• Document usage: Document webhook endpoints and payload formats
• Test thoroughly: Test webhook triggers before production use

#Troubleshooting

#PipelineRun Not Created

1. Check webhook: Verify webhook is configured and receiving events
2. Review Repository CR: Ensure Repository CR is correctly configured
3. Check PAC logs: Review PAC controller logs for errors
4. Verify pipeline file: Ensure pipeline definition file exists in repository

#PipelineRun Not Running

1. Check status: Review PipelineRun status and conditions
2. Review logs: Check PipelineRun and TaskRun logs
3. Verify resources: Ensure sufficient cluster resources
4. Check permissions: Verify ServiceAccount has required permissions

#Status Not Reported

1. Verify Git provider token: Ensure token has required scopes
2. Check PAC Watcher: Verify PAC Watcher is running
3. Review logs: Check PAC Watcher logs for errors
4. Test connectivity: Ensure PAC can reach Git provider API

#Next Steps

• Trigger Pipelines - Learn about different trigger methods
• Maintain Pipeline Code - Pipeline definition guide
• Configure Repository - Repository setup
• Common Issues - Troubleshooting guide