README.md

Octokit Request Action

A GitHub Action to send arbitrary requests to GitHub's REST API

Usage

Minimal example

name: Log latest release
on:
  push:
    branches:
      - main

jobs:
  logLatestRelease:
    runs-on: ubuntu-latest
    steps:
      - uses: octokit/[email protected]
        id: get_latest_release
        with:
          route: GET /repos/{owner}/{repo}/releases/latest
          owner: octokit
          repo: request-action
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - run: "echo latest release: '${{ steps.get_latest_release.outputs.data }}'"

More complex examples involving POST, setting custom media types, and parsing output data

name: Check run
on:
  push:
    branches:
      - main

jobs:
  create-file:
    runs-on: ubuntu-latest
    steps:
      # Create check run
      - uses: octokit/[email protected]
        id: create_check_run
        with:
          route: POST /repos/{owner}/{repo}/check-runs
          owner: octokit
          repo: request-action
          name: "Test check run"
          head_sha: ${{ github.sha }}
          output: | # The | is significant!
            title: Test check run title
            summary: A summary of the test check run
            images:
              - alt: Test image
                image_url: https://octodex.github.com/images/jetpacktocat.png
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      # Download file
      - uses: octokit/[email protected]
        id: download_file
        with:
          route: GET /repos/OWNER/REPO/contents/README.md
          owner: octokit
          repo: request-action
          mediaType: | # The | is significant!
            format: raw
         env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      # Update check run to completed, successful status
      - uses: octokit/[email protected]
        id: update_check_run
        with:
          route: PATCH /repos/{owner}/{repo}/check-runs/{check_run_id}
          owner: octokit
          repo: request-action
          check_run_id: ${{ fromJson(steps.create_check_run.outputs.data).id }}
          conclusion: "success"
          status: "completed"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Handle errors

name: Log latest release
on:
  push:
    branches:
      - main

jobs:
  handleError:
    runs-on: ubuntu-latest
    steps:
      - uses: octokit/[email protected]
        id: get_release
        with:
          route: GET /repos/{owner}/{repo}/releases/v0.9.9
          owner: octokit
          repo: request-action
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - run: "echo Release found: '${{ steps.get_release.outputs.data }}'"
      - run: "echo Release could not be found. Request failed with status '${{ steps.get_release.outputs.status }}'"
        if: ${{ failure() }}

Inputs

To use request body parameters, simply pass in an input matching the parameter name. See previous examples.

Due to how request parameters are processed, it may be necessary in some cases to first encode the value as either JSON or a block scalar:

env:
  REQUEST_BODY: |
    Multi-line string with *special* characters:
    - "'`
with:
  # As JSON
  body: ${{ toJSON(env.REQUEST_BODY) }}

  # As block scalar
  body: |
    |
    ${{ env.REQUEST_BODY }}

Debugging

To see additional debug logs, create a secret with the name: ACTIONS_STEP_DEBUG and value true.

How it works

octokit/request-action is using @octokit/request internally with the addition that requests are automatically authenticated using the GITHUB_TOKEN environment variable. It is required to prevent rate limiting, as all anonymous requests from the same origin count against the same low rate.

The actions sets data output to the response data. The action also sets the headers (again, to a JSON string) and status output properties.

To access deep values of outputs.data and outputs.headers, check out the fromJson function.

Warnings

The GitHub Actions runners are currently showing warnings when using this action that look like:

##[warning]Unexpected input 'repository', valid inputs are ['route', 'mediaType']

The reason for this warning is because the repository key is not listed as a possible value in actions.yml. This warning will appear for any key used under the with except route and mediaType. Due to the flexible nature of the required inputs depending on the route, not all of the possible parameters can be listed in actions.yml, so you will see this warning under normal usage of the action. As long as you see a 200 response code at the bottom of the output, everything should have worked properly and you can ignore the warnings. The response code will appear at the bottom of the output from the action and looks like:

< 200 451ms

See Issue #26 for more information.

License

MIT