Manually Triggering GitHub Actions Workflows Using Postman

In a previous post, I talked about how you can manually trigger a GitHub Actions workflow from the command line using curl.

In this post, we’re going to quickly walk through how to trigger the same events using Postman.

Refresher on manually triggering GitHub Actions workflows

Let’s quickly refresh our memories. A GitHub Actions workflow can be manually triggered by sending a repository_dispatch event. Our GitHub Actions workflows can then be configured to run in response to those webhook events.

To manually trigger a repository_dispatch event, we need to interact with the following GitHub api endpoint:

POST /repos/:owner/:repo/dispatches

Using my sample repository name (GitHubActionsAutomationSandbox), along with my GitHub username (n8ebel), we can build the full path for the endpoint we’ll be interacting with:

https://api.github.com/repos/n8ebel/GitHubActionsAutomationSandbox/dispatches

For a full, detailed, walkthrough of triggering a repository_dispatch event, see my previous post.

Triggering GitHub Actions Workflows Using Postman

Now, let’s focus on how to trigger a GitHub Actions workflow using Postman.

Create a new request

To start, we’ll open Postman and create a new POST request using the full url we built in the previous section.

You’ll notice we’ve selected POST from the request type dropdown, and we pasted our full url into the request url input box:

https://api.github.com/repos/n8ebel/GitHubActionsAutomationSandbox/dispatches

Add the custom media-type header

Next, we need to add the required custom media-type as an Accept header:

application/vnd.github.everest-preview+json

Add an authorization header

To send the repository_dispatch event to our repository, we need to authorize the request.

To properly authorize our request, you’ll need to ensure you have a personal access token with :repo access rights for the repository you’re working with.

When you have that required token, we can add an Authorization header to our request using that token and the following format:

token <your-token-here>

Defining the request body

Our request is required to include the event_type property. If it does not, our request will fail.

To define the event_type, we will include the following raw JSON string as our POST body.

{
   "event_type": "do-something"
 }

Triggering our workflow

Now, we’re ready to make our request.

If you press the Send button, you should see the following status:

Status: 204 No Content

If you receive the 204 status, and your event_type is correct, your GitHub Actions workflow should be run.

Sending additional data to a GitHub Actions Workflow using Postman

As discussed in the previous post, the repository_dispatch event allows us to add additional data. This data must be in the form of a client_payload JSON object.

Let’s imagine we want to send the following client_payload data with our event:

{
  "client_payload": {
    "text": "a title"
  }
}

To do this with Postman, we will update the body of our request as follows:

Now, when the repository_dispatch event is received, will will have access to the client_payload.text property.

Things to remember

  • If you define the types property on the repository_dispatch section in your workflow .yml file, then the event_type you send with your request must match one of the specified types or the workflow will not run.
  • If you don’t specify any types for the repository_dispatch trigger, then your workflow will run any time a repository_dispatch event is sent, regardless of the defined event_type.

Conclusion

In this post we’ve walked through how to use Postman to send repository_dispatch events to our GitHub repositories to manually trigger a GitHub Actions workflow.

If you’d prefer not to user curl to send these events, or you want to save the Postman request and share with your team, Postman is a great tool for making these requests and triggering your GitHub Actions workflows.

Explore how to make use of triggered workflows for building Android projects.


I love to meet/talk/discuss and help where I can. If you want to chat or ask a question feel free to reach out via Twitter, YouTube, and LinkedIn.

Check Out My YouTube Channel



Categories: DevOps, Software Development

Tags: , ,

Leave a Reply