[Feedback tracking] Webhook forwarding in the GitHub CLI

[timrogers]

When you're building a webhooks integration, it's super helpful to be able to run your code in your local environment, so you can test and iterate quickly without time-consuming deploys.

We're running a public beta of a new feature for the GitHub CLI - webhook forwarding. Webhook forwarding makes it easier than ever to test your integration locally without having to worry about port forwarding.

You can register your interest in joining the beta program here.

This discussion is the best place for participants in the beta program to share their feedback and questions with the GitHub team. We appreciate your support and ideas!

[RobbyAmbrose]

add me

[hutch3232]

This new tool is amazing. I'm a complete novice to this sort of thing and I managed to get it working. Thanks for creating this!

Are there plans to make this extension installable in "locked down" environments where developers are unable to install directly from GitHub? For example, I currently installed the GitHub CLI via Conda. For now I had to do the testing on my personal computer.

[HarrierPanels]

When you're building a webhooks integration, it's super helpful to be able to run your code in your local environment, so you can test and iterate quickly without time-consuming deploys.

We're running a public beta of a new feature for the GitHub CLI - webhook forwarding. Webhook forwarding makes it easier than ever to test your integration locally without having to worry about port forwarding.

You can register your interest in joining the beta program here.

This discussion is the best place for participants in the beta program to share their feedback and questions with the GitHub team. We appreciate your support and ideas!

Ansible tasks setting up webhook forwarding using the GitHub CLI Beta feature for a Jenkins Docker container running on an AWS EC2 (Amazon Linux 2) instance provisioned by Terraform:

      - name: Add GH Repo
        ansible.builtin.shell: |
          yum-config-manager --add-repo \
             https://cli.github.com/packages/rpm/gh-cli.repo

      - name: Install GH
        ansible.builtin.yum:
          name:
            - gh
          state: latest
          update_cache: yes

      - name: Create GH Token file
        ansible.builtin.copy:
          dest: "{{ dest_token }}"
          content: 'ghp_YOUR_TOKEN'
          owner: ec2-user
          group: ec2-user
          mode: '600'

      - name: GH CLI Auth
        become_user: ec2-user
        ansible.builtin.shell:
          gh auth login --with-token <~/.ssh/token
        register: auth
        async: 10
        poll: 2

      - name: Debug GH Auth
        ansible.builtin.debug:
          var: auth 
         
      - name: Install cli/gh-webhook
        become_user: ec2-user
        ansible.builtin.shell:
          gh extension install cli/gh-webhook
        register: install_ghwh
        async: 10
        poll: 2

      - name: Debug GH Webhook Install
        ansible.builtin.debug:
          var: install_ghwh

      - name: Set GitHub Webhook
        become_user: ec2-user
        ansible.builtin.shell: |
          gh webhook forward --repo YOUR_USER/YOUR_REPO \ 
            --events=push --url="http://localhost:8080/github-webhook/"
          echo 'Webhook set!'
        async: 45
        poll: 0
 
      - name: Test Git push at localhost 
        become_user: your_linux_user
        ansible.builtin.shell: |
          cd $HOME/path/to/YOUR_REPO
          touch Ansible-$(date +%T)
          git remote remove origin
          git remote add origin https://[email protected]/YOUR_USER/YOUR_REPO.git
          git add . && git commit -m "Pushed by Ansible" && git push --all origin
        register: git
        delegate_to: localhost

Happy Webhook forwarding! :)

[dhirschfeld]

Is there any documentation of the underlying api that cli/gh-webhook uses?

It appears that it's connecting to wss://webhook-forwarder.github.com but I can't find any documentation on that endpoint?

[zhangyoufu]

Here's the undocumented API for cli/gh-webhook at the time of writing.

% GITHUB_REPOSITORY=octocat/hello-worId

# register the CLI webhook (at most one for each user)
% gh api "repos/${GITHUB_REPOSITORY}/hooks" --method POST --field name=cli --field 'config[content_type]=json' --field 'events[]=*'
{
  "type": "Repository",
  "id": 123456789,
  "name": "cli",
  "active": true,
  "events": [
    "*"
  ],
  "config": {
    "content_type": "json",
    "insecure_ssl": "0",
    "url": "https://webhook-forwarder.github.com/hook"
  },
  "updated_at": "2023-08-30T00:00:00Z",
  "created_at": "2023-08-30T00:00:00Z",
  "url": "https://api.github.com/repos/octocat/hello-worId/hooks/987654321",
  "test_url": "https://api.github.com/repos/octocat/hello-worId/hooks/987654321/test",
  "ping_url": "https://api.github.com/repos/octocat/hello-worId/hooks/987654321/pings",
  "deliveries_url": "https://api.github.com/repos/octocat/hello-worId/hooks/987654321/deliveries",
  "last_response": {
    "code": null,
    "status": "unused",
    "message": null
  },
  "ws_url": "wss://webhook-forwarder.github.com/forward?hook_id=987654321"
}

# consume event stream
# server expects JSON response for each event, like {"Status":200,"Header":{...},"Body":"BASE64-ENCODED-BODY"}
% websocat 'wss://webhook-forwarder.github.com/forward?hook_id=987654321' --header 'Authorization: YOUR_AUTH_TOKEN_HERE'
{"Header":{...},"Body":"BASE64-ENCODED-JSON-PAYLOAD","DeliveryID":"...","RequestID":"..."}
...

Note: When connecting to the WebSocket server, Authorization header value should be bare token, do not prepend Bearer prefix.

PS: I tried to use GITHUB_TOKEN from GitHub Actions, does not work.

[dhirschfeld]

Here's the undocumented API for cli/gh-webhook at the time of writing.

Thanks @zhangyoufu - that's very useful!

I have opened an issue on the repository itself to hopefully get more traction on official documentation: cli/gh-webhook#19