Do you know how to handle special characters in GitHub Secrets and Variables?

GitHub Secrets and Variables are an invaluable way to store sensitive information such as API keys, tokens, and passwords for use in your GitHub Actions. However, it's important to understand how special characters are handled in order to avoid issues in your workflows.

When storing Secrets and Variables in GitHub, it's common that these are stored with special characters (for example: "$", "&", "(", ")", "<", ">"). We have a few ways to use these in our GitHub Actions:

❌ Bad - Referencing the raw text as-is
✅ Good - Referencing the raw text in enclosing quotes
✅ Best - Escaping all special characters when saving the Secret or Variable

❌ Referencing as-is

Storing text containing special characters Secret or Variable and referencing this directly in our Action can lead to issues as it might not be interpreted as text as intended.

secret with parentheses — Figure: A Secret or Variable with special characters can cause issues if improperly handled

action no quotes — Figure: Bad example - Accessing this Secret as-is will lead to a syntax error in our Action

parentheses error — Figure: A syntax error is thrown due to the special characters

✅ Referencing in quotes

One simple way to avoid this is to wrap your Secrets or Variables in single or double quotes when using them in your GitHub Actions. This will ensure that these are not interpreted incorrectly and will be treated as a string.

action with quotes — Figure: Good example - Wrapping our Secret in quotes means it will be correctly treated as text

output with quotes — Figure: Our Secret is now handled correctly when wrapped in quotes

However, it's important to note that this can still cause issues in certain scenarios. For instance, if the Secret or Variable contains double quotes and is also wrapped by double quotes in our Action, it will have trouble parsing this and will throw an error.

secret with quote — Figure: Bad example - Trying to wrap this Secret in double quotes will lead to an error

quote error — Figure: The lone double quote character means this string cannot be interpreted correctly

✅ Escaping all special characters when storing Secret or Variable (Recommended)

A better way to handle this is to escape these special characters when storing your Secret or Variable. This can be done by adding a backslash ("") before each special character. This will ensure that these characters are interpreted as literal characters and will also help prevent potential ambiguity from using enclosing quotes.

escaped secret — Figure: Good (best) example - Escaping the special characters mean this string will be interpreted correctly

output escaped — Figure: The escaped characters mean our string is now interpreted correctly without the need to wrap in quotes

GitHub