atlassian-webhooks

PHP webhook handling code for webhooks from Atlassian tools.

Documentation

bitbucket.php

Deals with webhooks from BitBucket. Webhooks are validated via the defined secret in the webhook configuration. An example JSON configuration is provided in sample_config/bitbucket.json. It has a hierarchical structure with global settings and the project keys as top-level keys. For each project, a repository and ref-id for which the webhook should be executed are given, i.e. in a pseudo-example:

{
  "global_setting": "value",
  "PROJKEY": {
    "project_specific_setting": "value",
    "reponame": {
      "repo_specific_setting": "value",
      "refs/heads/master": {
        "ref_id_specific_setting": "value"
      }
    }
}

Not all configuration knobs can be set on all levels, and some are optional.
If a knob is set on multiple levels, the deepest setting is used. This allows to define defaults on global level and override them on deeper levels.

The following configuration knobs exist:

• alert_mail (String, optional)
  Can be set to a list of mail addresses, mailed only in case of error.
  If set to an empty string, no alerts are sent.
  Possible levels in configuration file: Global, Project, Repository, Ref-Id.
  Example value: Admin A <[email protected]>, Admin B <[email protected]>

• notice_mail (String, optional)
  Can be set to a list of mail addresses, mailed only in case of success.
  If set to an empty string, no notices are sent.
  Possible levels in configuration file: Global, Project, Repository, Ref-Id.
  Example value: Expert A <[email protected]>, Admin A <[email protected]>

• description (String, optional, on project level or below)
  The provided description will be echoed during webhook execution.
  This provides a comment / naming functionality.
  If set to an empty string (implicit default), the description is not added to the output.
  Possible levels in configuration file: Project, Repository, Ref-Id.
  Example value: Syncing code, configuration stored in /etc/synccode.conf

• continue_on_error (Boolean, required on Global level)
  If set to true, abort when the first command fails. Otherwise, continues execution.

• background (Boolean, required on Global level)
  If set to true, informative output is returned and the connection to Bitbucket is closed gracefully.
  Execution continues in the background, and mail notices / alerts will be sent as configured.
  Note that if set to false, while the full output will be returned to Bitbucket, Bitbucket may mark webhooks as "failed" after given time limits have passed, configurable via:

  • plugin.webhooks.socket.timeout (default 20 s)
  • plugin.com.atlassian.stash.plugin.hook.connectionTimeout (default 10 s) Possible levels in configuration file: Global, Project, Repository, Ref-Id.

• from_mail (String, required on Global level)
  Mail address to use in the From header.
  Can be set to a name and mail address.
  Note this is internally prefixed with the hostname in square brackets.
  Possible levels in configuration file: Global, Project, Repository, Ref-Id.
  Example value: Webhook script <[email protected]>

• reply_to_mail (String, required on Global level)
  Mail address to use in the Reply-to header.
  Usually a support address.
  Possible levels in configuration file: Global, Project, Repository, Ref-Id.
  Example value: [email protected]

• secret (String, required on Repository level)
  Secret configured in Bitbucket, used in HMAC validation of the JSON webhook.
  Example value: s0m3Th1n6_v3rY_$ecr3T

• commands (Array of strings, required on Ref-id level)
  The actual commands to execute. These are executed via PHP exec, i.e. using a shell, after appending 2>&1 to catch all output into a single buffer. The exit codes are checked and reported for each command, and continue_on_error decides whether execution is aborted when one command in the array fails. Example value: [ "echo Hello", "ssh somehost.example.com doSomething" ]

Common use cases

Common use cases will involve triggering other webhooks, or executing commands on other machines via ssh. Note that for the latter use case, you should consider basic safety measures, i.e. firewalling, login only with SSH keys, limit the commands which can be executed on the host which is accessed etc.

Limitations

The code currently handles repo:refs_changed event keys only (i.e. pushes) and only looks at the first change. It tests that this was an UPDATE and that the refId matches the configured ID. Otherwise, the code exits with an error.

Disclaimer

This code is not affiliated with Atlassian in any way.