Webhooks & CI/CD Integration

Skipper integrates with your existing CI/CD pipeline. Your CI system (GitLab CI, GitHub Actions) builds and tests your code. Skipper handles the deployment.

How it works

Setting up webhooks

1. Enable the webhook

kip app webhook enable api --project yourr-name --environment test

  ✔  Webhook enabled for api

  Webhook URL:    https://console-api-46-225-91-12.kipper.run/api/v1/webhook/yourr-name-test/api
  Secret token:   a3f8b2c4d5e6f7890123456789abcdef...

  GitLab CI snippet (.gitlab-ci.yml):

    deploy:
      stage: deploy
      script:
        - |
          curl -s -X POST https://console-api-.../api/v1/webhook/yourr-name-test/api \
            -H "X-Skipper-Token: $SKIPPER_WEBHOOK_TOKEN" \
            -H "Content-Type: application/json" \
            -d '{"image": "'$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA'", "commit": "'$CI_COMMIT_SHORT_SHA'"}'

2. Add the token to your CI settings

• GitLab: Settings → CI/CD → Variables → Add SKIPPER_WEBHOOK_TOKEN
• GitHub: Settings → Secrets and variables → Actions → Add SKIPPER_WEBHOOK_TOKEN

3. Add the deploy step to your pipeline

GitLab CI (.gitlab-ci.yml):

deploy:
  stage: deploy
  script:
    - |
      curl -s -X POST $SKIPPER_WEBHOOK_URL \
        -H "X-Skipper-Token: $SKIPPER_WEBHOOK_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"image": "'$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA'", "commit": "'$CI_COMMIT_SHORT_SHA'"}'
  only:
    - main

GitHub Actions:

- name: Deploy to Skipper
  run: |
    curl -s -X POST ${{ secrets.SKIPPER_WEBHOOK_URL }} \
      -H "X-Skipper-Token: ${{ secrets.SKIPPER_WEBHOOK_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d '{"image": "ghcr.io/${{ github.repository }}:${{ github.sha }}", "commit": "${{ github.sha }}"}'

Webhook request format

POST /api/v1/webhook/{namespace}/{app}
Header: X-Skipper-Token: <token>
Content-Type: application/json

{
  "image": "registry.example.com/api:abc123f",
  "commit": "abc123f"
}

Field	Required	Description
image	Yes	Full image reference including tag
commit	No	Git commit SHA (shown in deploy history)

Deploy history

Every deployment, whether triggered by webhook, manual update, promotion, or rollback, is recorded.

kip app history api --project yourr-name --environment test

  #     IMAGE                                              COMMIT     TRIGGER      WHEN
  3     registry.example.com/api:abc123f                   abc123f    webhook      2 min ago (current)
  2     registry.example.com/api:def456a                   def456a    webhook      1 hour ago
  1     registry.example.com/api:ghi789b                   ghi789b    manual       3 hours ago

Deploy history is also visible in the web console under the Deploys tab in the app detail panel.

Rollback

If a deployment breaks something, rollback to a previous version:

# Rollback to the previous version
kip app rollback api --project yourr-name --environment test

# Rollback to a specific revision
kip app rollback api --revision 1 --project yourr-name --environment test

  ✔  Rolled back api to revision #2 (registry.example.com/api:def456a)

Rollback is also available from the web console. Each entry in the deploy history has a Rollback button.

Managing webhooks

# Check webhook status and token
kip app webhook status api --project yourr-name --environment test

# Regenerate the token (invalidates the old one)
kip app webhook enable api --project yourr-name --environment test

# Disable webhooks
kip app webhook disable api --project yourr-name --environment test

Security

• Each app has its own unique webhook token
• Tokens are stored as Kubernetes Secrets (encrypted at rest)
• The webhook endpoint verifies the token before making any changes
• GitHub HMAC signature verification (X-Hub-Signature-256) is also supported
• Webhook URLs are scoped to a specific namespace and app, so a token for one app cannot deploy another