events-that-trigger-workflows: add unreachable tag note

[wh0]

Why:

It's worth documenting, imo.

It's true though, right? Reproduce this behavior:

git checkout -b feature
cat >.github/workflows/build.yml <<EOF
...
EOF
git add .github/workflows/build.yml
git commit -m "ci: add build"
git tag feature-workflow-test-1
git push origin feature-workflow-test-1 # push tag but not branch

Closes:

What's being changed (if available, include any code snippets, screenshots, or gifs):

Check off the following:

• A subject matter expert (SME) has reviewed the technical accuracy of the content in this PR. In most cases, the author can be the SME. Open source contributions may require an SME review from GitHub staff.
• The changes in this PR meet the docs fundamentals that are required for all content.
• All CI checks are passing and the changes look good in the review environment.

[github-actions]

How to review these changes 👓

Thank you for your contribution. To review these changes, choose one of the following options:

• Spin up a codespace
• Set up a local development environment

A Hubber will need to deploy your changes internally to review.

Table of review links

Note: Please update the URL for your staging server or codespace.

The table shows the files in the content directory that were changed in this pull request. This helps you review your changes on a staging server. Changes to the data directory are not included in this table.

Source	Review	Production	What Changed
actions/reference/workflows-and-actions/events-that-trigger-workflows.md	fpt ghec ghes@ 3.17 3.16 3.15 3.14	fpt ghec ghes@ 3.17 3.16 3.15 3.14

Key: fpt: Free, Pro, Team; ghec: GitHub Enterprise Cloud; ghes: GitHub Enterprise Server

🤖 This comment is automatically generated.

[wh0]

shoot, I think I just encountered a situation where pushing an unreachable tag ref did start a run

[Sharra-writes]

@wh0 Thanks for opening a PR! If you're not sure whether this behavior occurs consistently/is intended, could you talk to our support team? They're better at tracking down answers to those kinds of questions than those of us here in docs.

[wh0]

thanks, let me confirm with them

[wh0]

support says "yes expected, p.s. how dare you speak to me"

Hello wh0,

Thank you for contacting GitHub Support.

This level of support is available exclusively as part of a paid GitHub plan, Copilot Business, or Copilot Enterprise. It looks as though you do not currently have a qualifying plan. If you would like to use this service, please consider upgrading your account to any of our paid plans (i.e, Pro, Team or Enterprise).

What I can say, based on the information I have to hand, what you’re seeing is expected behaviour: a push that only creates or updates a tag whose target commit is not reachable from any branch will not trigger Actions workflows. For push events on tags, Actions requires the tag’s target commit to be reachable from the repository’s branch refs. If the commit is only referenced by a tag with no branch pointing to it, the event will be ignored and no workflow run will be created. You do have a point in that this edge case isn’t mentioned clearly in our docs though, so I do appreciate your PR suggestion to add.

To get around this, you can:

Push the branch that contains the commit first (or at the same time), then push the tag, or
Create the tag on a commit that’s already on a branch the repo knows about (e.g., the default branch), then push the tag.

For anything else, I'd recommend checking out the GitHub Docs, which will cover just about everything you could need to know about using GitHub, and is collaboratively maintained by both GitHub and our community. You can even propose changes yourself!

If the Docs aren't able to answer your question, try using our awesome GitHub Community discussions. You can search to see if others have encountered the same issue as you, or open a discussion of your own. Most of the answers will come from our community of developers who are just like you, but you'll find dedicated GitHub Community Staff there too, as well as some of our product and engineering colleagues (especially when there are new releases and Technical Previews).

Sometimes your issue may stem from incidents we are already aware of. Please check our GitHub Status page to find out if we're already working on it.

For additional information regarding Support, please visit our "About GitHub Support" page.
Dan | GitHub Support Engineer

[Sharra-writes]

@wh0 The good news is that they opened a PR to fix it internally, so I'm going to close this one. The internal one should be merged soon.