Terrateam Webhook Proxy

Warning

Unsupported software. This action is provided as is, without support. It may change or be withdrawn at any time. Issues and pull requests may not get a response.

A GitHub Action that forwards the event that triggered a workflow to a Terrateam server as a signed GitHub webhook. Use it when GitHub cannot deliver webhooks to your Terrateam server directly.

The action reads the event payload that GitHub gives the workflow, converts it to the webhook that Terrateam decodes, signs it with your webhook secret (X-Hub-Signature-256) and POSTs it to <terrateam-url>/api/github/v1/events.

Usage

name: Terrateam Webhook Proxy

on:
  pull_request_target:
    types: [opened, synchronize, reopened, ready_for_review, closed, edited]
  issue_comment:
    types: [created]
  push:

permissions: {}

jobs:
  forward:
    runs-on: ubuntu-latest
    steps:
      - uses: stategraph/action-webhook-proxy@v1.0.0
        with:
          terrateam-url: https://terrateam.example.com
          webhook-secret: ${{ secrets.TERRATEAM_WEBHOOK_SECRET }}
          installation-id: ${{ vars.TERRATEAM_INSTALLATION_ID }}

Inputs

Input	Required	Default	Description
terrateam-url	no	https://app.terrateam.io	Base URL of the Terrateam server.
webhook-secret	yes		Secret used to sign the webhook. Must equal the server's GITHUB_WEBHOOK_SECRET.
installation-id	yes		ID of the Terrateam GitHub App installation for this repository.

Events

Workflow event	Sent as
pull_request	pull_request
pull_request_target	pull_request
issue_comment	issue_comment
push	push

For any other event, the action writes a notice and does nothing. Terrateam defines no webhook for the pull_request activity types enqueued, dequeued and demilestoned, so the action writes a notice for them too.

Use pull_request_target instead of pull_request if pull requests come from forks: GitHub does not give secrets to pull_request workflows from forks. pull_request_target is safe here because the action does not check out or run code from the pull request.

How the webhook is built

GitHub documents the workflow's event payload as identical to the webhook payload of the event. The action converts it, event by event, to the webhook that Terrateam decodes, which holds only the members Terrateam reads:

Webhook	Members sent
every event	repository (id, name, default_branch, owner.login, owner.type), sender (login, type), installation (from the installation-id input)
pull_request	action, number, pull_request.number; for edited, changes.base
issue_comment	action, comment.id, comment.body, issue.number, issue.pull_request
push	ref, after

If the event payload does not have a member that the webhook requires, the step fails and names the member, for example $.pull_request.number: missing. The action does not invent values.

Requirements

• A Linux or macOS runner with python3 (3.9 or later) on the PATH. The action uses only the Python standard library and does not use Docker or Node.
• The action does not install its own crypto library. Signing (hmac) and TLS (ssl) use the OpenSSL that the runner's Python is linked to, so the host's crypto policy applies. On a FIPS host, use a webhook secret of at least 14 bytes (112 bits), the minimum HMAC key length for FIPS-approved use; a FIPS provider can refuse a shorter key.
• TLS uses the host's trust store. To trust a private CA, add it to the host trust store or set SSL_CERT_FILE in the step environment.

Releases and pinning

Releases are cut from main and tagged vX.Y.Z. A tag freezes everything the action runs, so a tag is what you should pin to.

Pin	Behaviour	Dependabot
stategraph/action-webhook-proxy@v1.0.0	Frozen at one release. Recommended.	Pull requests for v1.0.1, v1.1.0, and so on.
stategraph/action-webhook-proxy@<commit sha> # v1.0.0	Frozen at one commit.	Pull requests that advance the SHA and update the comment.

There is no moving major tag. Pin to a release and let Dependabot raise the pull request. Pin to a commit that a release tag points at: for a SHA that carries no tag, Dependabot advances the pin to the head of the branch rather than to a release.

X changes only on a deliberate, announced break. Y increases when a release adds functionality. Z increases for fixes and internal changes. Prereleases are tagged v1.1.0-rc.1 and are marked as prereleases. See the Releases page for the changelog.

Cutting a release

Run the release workflow from the Actions tab. It always releases the head of main:

• release_kind: patch, minor or major bumps the highest stable tag; specific uses semver_tag exactly (required for the first release).
• dry_run: computes the version and publishes nothing.

The workflow tags the commit and creates a GitHub Release with generated notes. It writes nothing into the tree.

Development

$ PYTHONPATH=src python3 -m unittest discover -s tests -v
$ pip install mypy==1.20.2 && mypy

src/terrat_webhook_types.pyi is generated from Terrateam's webhook schema. Do not edit it by hand. src/convert.py builds each webhook from these types, so mypy fails when the schema changes and a conversion does not follow it.