abinnovision/github-workflow-dispatch-proxy repository overview

⁠github-workflow-dispatch-proxy

Proxy for GitHub Actions' workflow_dispatch event to allow authenticated access. This can be used to call a workflow dispatch from a GitHub Actions workflow.

It's based on the OIDC Connect implementation⁠ of GitHub Actions and uses the provided ID token to authenticate the request.

⁠Installation

The proxy is distributed as a Docker image⁠:

docker run -d \
  --name github-workflow-dispatch-proxy \
  -p 8080:8080 \
  ghcr.io/abinnovision/github-workflow-dispatch-proxy:latest

⁠Configuration

The proxy is configured via environment variables. The following environment variables are supported:

⁠Policies

Policies are used to determine whether a request is allowed or not. The implementation is based on the Open Policy Agent (OPA)⁠.

⁠Built-in Policies

⁠allow_all

This policy allows all requests.

⁠allow_org_wide

This policy allows all requests from within the configured organization. It requires the organization configuration to be set on the APP_POLICY_CONFIG environment variable.

⁠Custom Policies

Custom policies can be used by setting the APP_POLICY environment variable to custom and providing the path to the policy file via APP_POLICY_PATH. The policy file must be a valid WebAssembly file built with Open Policy Agent (OPA)⁠.

To get started, you can use the OPA Playground⁠ to write your policy using Rego. Also, see the source code of the built-in policies for examples⁠.

This script⁠ can be used to build the policy file. It can be place in the folder with many .rego files and it will build a .wasm file in the same folder for each .rego file.

⁠Input schema for policies

The input schema for the policy is defined as follows:

{
	// Can be empty if not provided.
	config: {
		key: "value",
	},
	target: {
		owner: "owner",
		repository: "repository",
		ref: "ref",
		workflow: "workflow",
		// Can be empty if none are required.
		inputs: {
			key: "value",
		},
	},
	caller: {
		owner: "owner",
		repository: "repository",
		ref: "ref",
		workflow: "workflow",
	},
}

⁠Usage with GitHub Actions

The main idea of this proxy is to allow GitHub Actions to call a workflow dispatch from a workflow by using policy evaluation. That's why the proxy should easily be integrated into a GitHub Actions workflow.

⁠Example without an additional action

The proxy can easily be used by using curl. First, you'd need to fetch the ID token from the GitHub Actions API. Then, you can use curl to send the workflow dispatch request to the proxy.

jobs:
  dispatch-workflow:
    name: Dispatch workflow
    runs-on: ubuntu-latest
    steps:
      - name: Dispatch workflow
        run: |
          ID_TOKEN_RESPONSE=$(curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=github-workflow-dispatch-proxy")
          ID_TOKEN=$(echo $ID_TOKEN_RESPONSE | jq -r ".value")

          curl --header "Content-Type: application/json" \
          --request POST \
          --header "Authorization: Bearer $ID_TOKEN" \
          --data '{"target":{"owner":"abinnovision","repo":"github-workflow-dispatch-proxy","ref":"master","workflow":"test.yaml"},"inputs":{}}' \
          https://<endpoint>/dispatch

⁠Example with abinnovision/actions/run-workflow-dispatch

This example uses the abinnovision/actions@run-workflow-dispatch⁠ action to run the workflow dispatch.

jobs:
  dispatch-workflow:
    name: Dispatch workflow
    runs-on: ubuntu-latest
    steps:
      - name: Dispatch workflow
        uses: abinnovision/actions@run-workflow-dispatch-v1
        with:
          proxy: https://<endpoint> # The base URL of the proxy without a trailing slash.
          target: owner/repo # or just repo
          workflow: update.yaml # The workflow to dispatch.
          workflow-ref: master # Optional, defaults to "master".
          # Optional inputs for the workflow. Must be a valid JSON string.
          workflow-inputs: |
            {"key": "value"}

⁠Development

This project is based on a Node.js stack with TypeScript. It uses Yarn as the package manager. Also, asdf⁠ is used to manage the Node.js version.