branch names with @ are not processed

[llrs-roche]

Select Topic Area

Question

Body

I know I can use an action like:

jobs:
    id:
        name: ID-name
        uses: org/repo/path/file.yaml@branch_name

However, when the branch name has an @ the workflow fails (we use branch names such as fix@main) to signal where the fix is going to get merged (main in this example)

jobs:
    id:
        name: ID-name
        uses: org/repo/path/file.yaml@fix@main

The error message I get is:

Invalid workflow file: .github/workflows/check.yaml#L24
invalid value workflow reference: too many '@' in workflow reference

I then need to use the SHA number which when I'm working on updating/fixing org/repo/path/file.yaml I need to change each SHA for each commit.
Is there any workaround to make it easier to use these branches (besides the obvious solution of not using this branch naming scheme)?

[github-actions[bot]]

🕒 Discussion Activity Reminder 🕒

This Discussion has been labeled as dormant by an automated system for having no activity in the last 60 days. Please consider one the following actions:

1️⃣ Close as Out of Date: If the topic is no longer relevant, close the Discussion as out of date at the bottom of the page.

2️⃣ Provide More Information: Share additional details or context — or let the community know if you've found a solution on your own.

3️⃣ Mark a Reply as Answer: If your question has been answered by a reply, mark the most helpful reply as the solution.

Note: This dormant notification will only apply to Discussions with the Question label. To learn more, see our recent announcement.

Thank you for helping bring this Discussion to a resolution! 💬

[llrs-roche]

I haven't found a solution (yet).

[github-actions[bot]]

🕒 Discussion Activity Reminder 🕒

This Discussion has been labeled as dormant by an automated system for having no activity in the last 60 days. Please consider one the following actions:

1️⃣ Close as Out of Date: If the topic is no longer relevant, close the Discussion as out of date at the bottom of the page.

2️⃣ Provide More Information: Share additional details or context — or let the community know if you've found a solution on your own.

3️⃣ Mark a Reply as Answer: If your question has been answered by a reply, mark the most helpful reply as the solution.

Note: This dormant notification will only apply to Discussions with the Question label. To learn more, see our recent announcement.

Thank you for helping bring this Discussion to a resolution! 💬

[bharathkreddy]

You're running into a limitation of GitHub Actions syntax: the uses: keyword expects the reference (ref) to be formatted like this:

uses: org/repo/path/file.yaml@ref

But ref must not contain multiple @ characters, because GitHub interprets the last @ as the start of the ref, so a branch like fix@main breaks the parser.

You can use a Temporary Branch With Dash/Slash Format

git checkout -b fix-at-main
git push origin fix-at-main

Then in your workflow:

uses: org/repo/path/file.yaml@fix-at-main

[llrs-roche]

Many thanks for your answer. Do you have any source for this "GitHub interprets the last @ as the start of the ref"?

[Shaxzodbek16]

1. Quote the branch name
   git checkout "feature@beta"
2. Escape the @
   git checkout feature\@beta
   If your Git tools (e.g., CI/CD pipeline, GUI client) are breaking due to @, rename the branch:
   git branch -m "feature@beta" "feature-beta"

[llrs-roche]

This is not related to github actions.

[codebyviral]

❗ Branch Names with @ Are Not Processed – Here's Why

This issue most likely stems from the disparity between how the @ symbol is handled by the shell, by Git, and by various tools and interfaces built around Git.

---

🧠 Understanding @ in Git

In Git, the @ symbol is a shorthand for HEAD. So when you run a command like:

git checkout @

[1Thef0x]

GitHub Actions does not support @ characters in branch names when used in the uses: field because the @ symbol is a reserved character used to separate the action path from the ref (branch, tag, or commit SHA).

like /uses: org/repo/path/file.yaml@fix@main

[llrs-roche]

Were can I read more about "@ symbol is a reserved character"? Are there any other reserved characters like "." ?

[mehtahrishi]

its best to not use any special chracters for your branch names use like main, master, test, dev , etc

[github-actions[bot]]

🕒 Discussion Activity Reminder 🕒

This Discussion has been labeled as dormant by an automated system for having no activity in the last 60 days. Please consider one the following actions:

1️⃣ Close as Out of Date: If the topic is no longer relevant, close the Discussion as out of date at the bottom of the page.

2️⃣ Provide More Information: Share additional details or context — or let the community know if you've found a solution on your own.

3️⃣ Mark a Reply as Answer: If your question has been answered by a reply, mark the most helpful reply as the solution.

Note: This dormant notification will only apply to Discussions with the Question label. To learn more, see our recent announcement.

Thank you for helping bring this Discussion to a resolution! 💬

[llrs-roche]

This is still an issue!

[github-actions[bot]]

🕒 Discussion Activity Reminder 🕒

This Discussion has been labeled as dormant by an automated system for having no activity in the last 60 days. Please consider one the following actions:

1️⃣ Close as Out of Date: If the topic is no longer relevant, close the Discussion as out of date at the bottom of the page.

2️⃣ Provide More Information: Share additional details or context — or let the community know if you've found a solution on your own.

3️⃣ Mark a Reply as Answer: If your question has been answered by a reply, mark the most helpful reply as the solution.

Note: This dormant notification will only apply to Discussions with the Question label. To learn more, see our recent announcement.

Thank you for helping bring this Discussion to a resolution! 💬

[llrs-roche]

This is still an issue!