How to trigger repository_dispatch event for non-default branch?

[phil-opp]

The Github Actions documentation mentions the repository_dispatch event in the External Events section. The table in this sections says that the GITHUB_REF points to the “Branch that received dispatch”. My question now is: How can I specify the branch when sending the repository_dispatch event? The API documentation does not mention any branch related input argument.

Thanks!

[AndreaGriffiths11]

Hi @phil-opp,

Thank you for being here! I wish I had better news for you, the repository_dispatch only triggers on the master branch, and it is not possible to specify a branch. We have received several pieces of feedback about this limitation and have an internal issue tracking a feature request, to which I’ve added your feedback. 

[scanaaron]

We would love it if we could trigger on: schedule: jobs on branches other than our main branch. Thanks!

[dersimn]

https://github.com/marketplace/actions/workflow-dispatch

[phil-opp]

Thanks for clarifying! Perhaps the documentation at https://help.github.com/en/actions/automating-your-workflow-with-github-actions/events-that-trigger-workflows#external-events-repository_dispatch should be updated to reflect this (the GITHUB_REF column says “Branch that received dispatch” instead of “default branch”).

[Mayureshgithub]

I ain't getting proper answer. Could please give one example.

[0xGuybrush]

Also, when the documentation links “Webhook Event Payload: repository_dispatch” through to the repositorydispatchevent type on the v3 version of the documentation, it makes it seem like I can use the payload body there, but trying to use branch gives:

{
  "message": "Invalid request.\n\n\"branch\" is not a permitted key.",
  "documentation_url": "https://developer.github.com/v3"
}

Both are a bit confusing, would be good to update if only default branch is possible.

[gdi-automates]

I get the same issue

[mimoo]

My problem with the repository dispatch is that it needs a token with repo permission. Isn’t it possible to severely limit the scope of the token in order to avoid consequences if it gets compromised?

[phil-opp]

This seems like a different problem, so it’s probably better to create a new topic for it.

[tombrus]

Since we need this a lot…

two questions:

• any news on this since last November?
• could I mimic the branch by passing it’s name in the client_payload and switching to that branch in my action script? (will this build be registered by github as a build on  master or on the requested branch?)
• is there any other webhook I could (mis)-use to signal a rebuild on a certain branch?

Our situation is as follows:

• repository “lib” contains our library and publishes a package
• repository “app” uses the published package to make our app
• we use synchronous branches on both repositories
• regularly we push to both repos at the same time after bumping the version number of the package (in lib) and its use (in app).
• because they both start building at the same time the app will not find the new version of the lib and it fails.
• we would like the lib to re-trigger the app as soon as a new lib-package is published, which means the second build of app would find the indicated version of the lib and will succeed
• currently we have to manually baby-sit the app-build to start after lib was published
• if lib could directly trigger a build of app on whatever branch it is publishing we would automate this.

This is a simplified explaination, in reality we now have 4 repos that inter-depend and that number will probably grow. This will make the baby-sitting very time-consuming.

[missedone]

is there any update on this issue? it makes the repository_dispatch useless if only triggered on master (or default) branch

[Evilweed]

@AndreaGriffiths11 Any update on this?

This is available in GitLab and allows creating powerful workflows and easy iteration on them (as you don’t have to commit temp workflows to master while developing on feature branch)

[francisfuzz]

Clarification: which branch a repository dispatch is triggered for 📝

phil-opp:

Perhaps the documentation at https://help.github.com/en/actions/automating-your-workflow-with-github-actions/events-that-trigger-workflows#external-events-repository_dispatch should be updated to reflect this (the GITHUB_REF column says “Branch that received dispatch” instead of “default branch”).

another-dave:

Also, when the documentation links “Webhook Event Payload: repository_dispatch” through to the repositorydispatchevent type on the v3 version of the documentation, it makes it seem like I can use the payload body there

That’s great feedback. Our team recently updated the documentation to include a note below the repository_dispatch documentation:

Note: This event will only trigger a workflow run if the workflow file is on the master or default branch.

---

Workaround: specifying a branch using the repository dispatch event 👷‍♂️

tombrus:

• could I mimic the branch by passing it’s name in the client_payload and switching to that branch in my action script? (will this build be registered by github as a build on master or on the requested branch?)

Here’s an example repository that showcases using the repository dispatch event and actions/checkout@v2 specifying a branch in the client_payload field:

  <a href="https://github.com/actions-packages-examples/branch-builds" target="_blank" rel="noopener">GitHub</a>

GitHub - actions-packages-examples/branch-builds: Example for demonstrating...

Example for demonstrating branch builds using the repository dispatch event and actions/checkout@v2. - GitHub - actions-packages-examples/branch-builds: Example for demonstrating branch builds usin...

In the workflow file, it’s possible to leverage that input to checkout a specific branch (like what’s defined on these lines of the workflow file).

However, the Actions tab will associate the workflow run triggered by a repository dispatch to the default branch (in this case, master) rather than the specified branch as evidenced in this query.

---

Update: the latest news on the repository dispatch feature 📰

tombrus:

• any news on this since last November?

missedone:

is there any update on this issue?

👋 Hello! Neither @AndreaGriffiths11 or I are able to speak to upcoming product updates. However, any new ships are either published in the form of a changelog entry or an article in The GitHub Blog.

Today, the best place to share requests for new or updated features is through our official product feedback form. Our product team working on Actions monitors that channels and considers each entry, but they may not be able to respond to every submission.

[phil-opp]

Thanks for your reply!

Unfortunately, the workaround you mentioned has a big drawback: It runs the workflow file specified on the default branch, not the workflow file of the checked out branch. So this only really works if the two branches have the same build/test instructions.

Some examples where this doesn’t work:

• If we have a docs branch with a workflow file that converts some markdown documentation to HTML. Using your workaround, GitHub Actions would try to run the normal build instructions of the default branch (e.g. compile some code) on the markdown sources, which of course doesn’t work.
  • To prevent this issue, you could copy the markdown build instructions into the workflow file of the default branch. However, now you have to manually keep the two workflow files in sync when the markdown build instructions change at some point (and you need to remember to do it). This also means that any change to the markdown build instructions has to be coordinated across multiple branches, which will make things much more complicated.
• Even with branches that have similar build instructions, it is very easy to get things wrong with that workaround. For example, consider some build instructions that use the current branch name for conditionally skipping checks. Another risk is that you probably won’t notice if there were slight differences in the two workflow files, which might result in inconsistent build results depending on how the build was triggered. It could even lead to corrupted release artifacts if the workaround is used to trigger a release of a different branch with slightly different build instructions.

So this workaround only works in the very specific case where both branches have exactly the same build instructions and use no advanced features such as skipping steps based on the current branch name.

To solve this problem for more use case, we need some way to trigger a workflow run on a different branch using the workflow file of that branch. I’ll send a feature request for that through the form you linked and I encourage others to do so too.

[Nitive]

A new workflow_dispatch event can be used to trigger workflow for non-default branch.
https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch

[jamesmortensen]

This answer gave me an idea.

Since workflow_dispatch does allow triggering workflows on different branches, could you use Puppeteer in to go to github.com/org/repo/actions/workflow/test.yml, find the workflow, locate the workflow dispatch button with:

document.querySelector("#repo-content-pjax-container > split-page-layout > div > div > div.PageLayout-region.PageLayout-content > div > div > div.Box.Box--responsive.mt-3 > div.flash.flash-full > details > summary").click()

and then expand the drop down with this:

document.querySelector("#repo-content-pjax-container > split-page-layout > div > div > div.PageLayout-region.PageLayout-content > div > div > div.Box.Box--responsive.mt-3 > div.flash.flash-full > details > div > div > div > form:nth-child(1) > div.branch-selection.mb-2 > details > summary > span.css-truncate-target").click()

select the branch with this:

BRANCH_NAME='your-branch-here';
var iter = document.evaluate("//button/span[contains(., '"+BRANCH_NAME+"')]", document, null, XPathResult.ANY_TYPE, null );
var elem = iter.iterateNext();
elem.click();

And then finally click the "Run Workflow" button:

document.querySelector("#repo-content-pjax-container > split-page-layout > div > div > div.PageLayout-region.PageLayout-content > div > div > div.Box.Box--responsive.mt-3 > div.flash.flash-full > details > div > div > div > form:nth-child(2) > button").click();

The tricky part might be logging into GitHub from within the workflow. It could be done with a bot user which has no two-factor auth enabled and would rely on GitHub not putting up any "are you a robot" blockers.

[francisfuzz]

@nitive - Ah, thanks for mentioning that! Our team also published a changelog entry for this feature that might be worth checking out as well. ✌️

[crazy-matt]

Evilweed:

This is available in GitLab and allows creating powerful workflows and easy iteration on them (as you don’t have to commit temp workflows to master while developing on feature branch)

That’s in a simple single sentence exactly why a ci/cd tool would need this capability… Please Github…

francisfuzz:

In the workflow file, it’s possible to leverage that input to checkout a specific branch (like what’s defined on these lines of the workflow file).

But this alternative could make it. It would make sense then for Github to display the checkout ref on the Actions tab to give more insight about what happened on our runs.

[jgehrcke]

@nitive

A new workflow_dispatch event can be used to trigger workflow for non-default branch.

Are you sure that this can address the problem discussed here? I have tried this and failed. Here is what I did:

• I added a new file .github/workflows/update.yml on a non-default branch, called workflowtest.
• I pushed that branch to my repository.

I followed Actions - GitHub Docs and tried

$ curl -H "Authorization: token ${GITHUB_API_TOKEN}" https://api.github.com/repos/jgehrcke/foo/actions/workflows/update.yml/dispatches -d '{"ref":"workflowtest"}'
{
  "message": "Not Found",
  "documentation_url": "https://docs.github.com/rest/reference/actions#create-a-workflow-dispatch-event"
}

It seems like update.yml isn’t known to the system yet, because it’s not on the default branch.

The Actions tab in the UI of course also doesn’t show the workflow yet.

@phil-opp has tried hard to clarify the challenge he’d like to overcome:

we need some way to trigger a workflow run on a different branch using the workflow file of that branch

This is really important for the developer experience around building workflows/actions. I’ve commented on that before, here: How to develop (iterate on, debug!) a workflow file in a non-default branch? - #3 by brightran

I don’t want to commit to main/master before having tested the workflow properly.

[Nitive]

@jgehrcke we found a workaround to trigger workflow_dispatch workflow committed to non-default branch.

1. Create a workflow with push trigger like this one

name: My workflow
on:
  push:
jobs:

build-tools:

runs-on: ubuntu-latest

steps:

- run: echo 1

2. Push it
3. Change push to workflow_dispatch commit and push the change
4. Change the workflow whatever you like
5. Trigger workflow from API

We are not happy that we have to make an extra commit every time, but at least we don’t have to commit workflow to default branch

[HarikrishnanBalagopal]

I am having the same issue but in my case the workflow yaml is on the default branch main

I can dispatch the workflow if I specify ref as main or refs/heads/main
but it fails if I try any other branch

$ curl   -X POST   -H "Accept: application/vnd.github.v3+json" -H 'Authorization: token ***'   https://api.github.com/repos/HarikrishnanBalagopal/yohoo/actions/workflows/fooworkflow.yml/dispatches   -d '{"ref":"refs/heads/foo"}'
{
  "message": "Workflow does not have 'workflow_dispatch' trigger",
  "documentation_url": "https://docs.github.com/rest/reference/actions#create-a-workflow-dispatch-event"
}

To be clear this error is different from the error for non existent workflows:

$ curl   -X POST   -H "Accept: application/vnd.github.v3+json" -H 'Authorization: token ***'   https://api.github.com/repos/HarikrishnanBalagopal/yohoo/actions/workflows/fooworkflowsss.yml/dispatches   -d '{"ref":"refs/heads/hmmm"}'
{
  "message": "Not Found",
  "documentation_url": "https://docs.github.com/rest/reference/actions#create-a-workflow-dispatch-event"
}

and this error is also different from the error for non-existent branches:

$ curl   -X POST   -H "Accept: application/vnd.github.v3+json" -H 'Authorization: token ***'   https://api.github.com/repos/HarikrishnanBalagopal/yohoo/actions/workflows/fooworkflow.yml/dispatches   -d '{"ref":"refs/heads/weird"}'
{
  "message": "No ref found for: refs/heads/weird",
  "documentation_url": "https://docs.github.com/rest/reference/actions#create-a-workflow-dispatch-event"
}

[HarikrishnanBalagopal]

I got it working after committing the workflow yaml to both the default branch and the branch you want to run on.
So in my case had to commit to both main and foo

[kaihendry]

Whoa, I hope Github developers make this less of a mess.

1. count/serverless.yml at c1ade5ccad4d348658a39e02d6144ebe209b853f · kaihendry/count · GitHub
2. count/serverless.yml at e9d58727e08af4bb6a9a7003481b088f56be1fe7 · kaihendry/count · GitHub

Say I modify 2, i.e. the workflow files are not synced. Which one gets run? It appear 2 gets run. So I’m thinking 1. could be a LOT simpler.

github.com

kaihendry/count

ns

Comparing serverless platforms. Contribute to kaihendry/count development by creating an account on GitHub.

[AZ-X]

Any updates? I just want to get a workaround if the parameters could pass through an overridden value of GITHUB_SHA.
For example, git create ref/tag API

github.com

marvinpinto/actions/blob/4d6da7f4aa2ff406ad115549df3d9972487ce797/packages/automatic-releases/src/main.ts#L295

  context.sha,
);

const changelog = await getChangelog(client, context.repo.owner, context.repo.repo, commitsSinceRelease);

if (args.automaticReleaseTag) {
  await createReleaseTag(client, {
    owner: context.repo.owner,
    ref: `refs/tags/${args.automaticReleaseTag}`,
    repo: context.repo.repo,
    sha: context.sha,
  });

  await deletePreviousGitHubRelease(client, {
    owner: context.repo.owner,
    repo: context.repo.repo,
    tag: args.automaticReleaseTag,
  });
}

const releaseUploadUrl = await generateNewGitHubRelease(client, {

[kranthikumar-kvs-by]

Any update on this?
We too are looking to trigger repository_dispatch on different branches

[zhangguanzhang]

same issue on

curl \
-X POST https://api.github.com/repos/zhangguanzhang/xxxx/dispatches \
-H "Accept: application/vnd.github.everest-preview+json" \
-H "Authorization: token xxxx" \
-d '{
    "event_type":"xxxxxx",
    "client_payload":{
        "target":"dev"
    }
}'

[jamesmortensen]

I think there's some confusion in this thread. In the GitHub Action docs, I thought the feature everyone is looking for is called "repository_dispatch" but in the REST documentation, it's referred to as "workflow_dispatch", which in GitHub Actions is a manually triggered event from the UI.

https://docs.github.com/en/rest/actions/workflows#create-a-workflow-dispatch-event

https://docs.github.com/en/rest/repos/repos#create-a-repository-dispatch-event

In the docs, I can see that both can be triggered via a REST call, and there are slight differences in the request paths and data payloads. Would someone at GitHub be able to clarify the use-cases for both of these in the docs? What are the advantages of one over the other? The title of the post is about repository_dispatch, but people are also asking about and suggesting workflow_dispatch, which might be leading to some confusion.

Thank you!
James

[jaderyang-sms]

Any update on this? or any workaround?

[jamesmortensen]

If I were to get really crazy about this, I would create a workflow on the default branch that gets triggered by repository dispatch. As part of the payload, I might include the branch name, or just hard code it.

In that workflow, I would then clone the repo, change branches to the target branch, and then make an empty commit and push it to that branch, triggering the target workflow by a push.

The end result is this: We kick-off the process with repository dispatch and eventually trigger a workflow which runs on a branch, triggered via proxy.

You can do an empty commit like this:
git commit --allow-empty -m "run workflow"

[amit-teachmint]

Hi All,
I find this working after specifying branch name in client payload

curl --request POST -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" --url 'https://api.github.com/repos/OWNER/REPO/dispatches' --header 'authorization: Bearer <TOKEN>' --data '{"event_type": "NAME","client_payload":{"ref":"BRANCH","INPUTS_KEY":"INPUTS_VALUE"}}'

[racitores]

Agree. I think the best alternative when using the API is to include the branch in within the payload as this doc states.

[standage-thanh]

Yes, we can do with workflow-dispatch-event

[wparad]

Just got so annoyed that this doesn't work out of the box for pull requests, that I just had to build it myself: https://github.com/marketplace/actions/rebuild-stale-pullrequests