httpie.action

Human-friendly interactions with third-party web services through GitHub Actions :zap:

A general purpose HTTP client for GitHub Actions, wrapping the HTTPie CLI to enable human-friendly interactions with third-party web services that expose an API over HTTP in your development workflow.

Why not just use webhooks?

Great question! Webhooks will likely just work in the vast majority of cases :sparkles:

In certain situations though, this may be a better solution, as it provides more fine-grained control over the HTTP request that gets sent, for example you can:

1. Form an entirely custom payload
2. Use a variety of different authentication methods
3. Use a variety of different request methods (GET, POST, PATCH, etc.)
4. Send a variety of different MIME types
5. Follow any redirects
6. Act on the HTTP response
7. Basically, leverage all of the features of HTTPie :sparkles:

Super simple example

To POST some JSON data, {"hello": "world"}, to https://httpbin.org/anything on every push to the repo:

workflow "Call external API" {
  on = "push"
  resolves = ["Call httpbin"]
}

action "Call httpbin" {
  uses = "swinton/httpie.action@master"
  args = ["POST", "httpbin.org/anything", "hello=world"]
}

More examples

Using output in a downstream action

In this more advanced, but somewhat contrived, example we'll open an issue in the current repository, and then comment and close that issue in subsequent actions.

Note, this is made possible since the response body is preserved in a file, $HOME/$GITHUB_ACTION.response.body (along with response headers, in $HOME/$GITHUB_ACTION.response.headers, and the entire response, in $HOME/$GITHUB_ACTION.response). The response can then be parsed in downstream actions using jq, a command-line JSON processor, which is pre-baked into the container.

action "Issue" {
  uses = "swinton/httpie.action@master"
  args = ["--auth-type=jwt", "--auth=$GITHUB_TOKEN", "POST", "api.github.com/repos/$GITHUB_REPOSITORY/issues", "title=Hello\\ world"]
  secrets = ["GITHUB_TOKEN"]
}

action "Comment on issue" {
  needs = ["Issue"]
  uses = "swinton/httpie.action@master"
  args = ["--auth-type=jwt", "--auth=$GITHUB_TOKEN", "POST", "`jq .comments_url /github/home/Issue.response.body --raw-output`", "body=Thanks\\ for\\ playing\\ :v:"]
  secrets = ["GITHUB_TOKEN"]
}

action "Close issue" {
  needs = ["Issue"]
  uses = "swinton/httpie.action@master"
  args = ["--auth-type=jwt", "--auth=$GITHUB_TOKEN", "PATCH", "`jq .url /github/home/Issue.response.body --raw-output`", "state=closed"]
  secrets = ["GITHUB_TOKEN"]
}

Trigger another workflow

In this example, we'll trigger a separate workflow, via the repository's dispatches endpoint.

Note, $PAT refers to a personal access token, created separately, and stored as a secret.

action "Trigger workflow" {
  uses = "swinton/httpie.action@master"
  args = ["--auth-type=jwt", "--auth=$PAT", "POST", "api.github.com/repos/$GITHUB_REPOSITORY/dispatches", "Accept:application/vnd.github.everest-preview+json", "event_type=demo"]
  secrets = ["PAT"]
}

Presets

Some HTTPie presets are applied by default by the included config.json, that make sense in the context of GitHub Actions, namely:

1. --check-status: Causes a workflow to exit if the HTTP status is one of 3xx, 4xx, or 5xx
2. --ignore-stdin: Disables HTTPie's default behaviour of automatically reading STDIN, typically not desirable during non-interactive invocations
3. --default-scheme=https: Assumes https:// is the default prefix for URLs, so you can just say (for example) api.github.com/zen as opposed to https://api.github.com/zen
4. --print=hb: Prints both response headers and response body in the output

Plugins

A few authentication plugins are included:

1. httpie-api-auth: Provides support for the ApiAuth authentication scheme
2. httpie-aws-auth: Provides support AWS authentication
3. httpie-hmac-auth: Provides support for HMAC authentication
4. httpie-jwt-auth: Provides support for JSON Web Tokens

More info

Usage docs for HTTPie are here.