What Is URL Encoding? Percent-Encoding Explained

URL encoding (percent-encoding) replaces characters that are unsafe in a URL with a percent sign followed by their hex byte value.

URLs can only safely contain a limited set of characters, so anything outside that set - spaces, slashes, ampersands, non-ASCII letters - has to be escaped. URL encoding does this by replacing each unsafe byte with a percent sign and two hex digits. It matters in CI whenever you build URLs from variables or embed tokens and credentials in them.

What URL encoding is

URL encoding, also called percent-encoding, represents an unsafe character as a percent sign followed by the two-digit hexadecimal value of its byte. A space becomes %20, an ampersand becomes %26. This keeps the URL parseable because reserved characters no longer collide with the URLs own syntax.

Reserved versus unreserved characters

Some characters - letters, digits, and a few symbols - are safe to use literally. Others are reserved because they have meaning in a URL, like the slash that separates path segments or the question mark that starts a query. When you want one of those as data rather than structure, you encode it.

Encoding query parameters

Query string values frequently contain characters that would otherwise break the URL - spaces, equals signs, or another ampersand. Encoding each value ensures the server splits the parameters correctly instead of misreading where one value ends and the next begins.

URL encoding in CI

In pipelines you build URLs from variables all the time - calling an API with a search term, or embedding a token in a git remote URL. A token or password with a special character like a slash or at-sign must be URL-encoded, or it will corrupt the URL and the request will fail.

Percent-encoding a query value

# Encode a value before putting it in a URL in CI
steps:
  - run: |
      enc=$(jq -rn --arg v "$QUERY" '$v|@uri')
      curl "https://api.example.com/search?q=$enc"

Why it bites in pipelines

A common failure is a CI secret like a token containing a special character that silently breaks an authenticated URL. URL-encoding the credential before embedding it - or using a header instead - avoids a confusing 401 or malformed-request error.

Key takeaways

URL encoding replaces unsafe characters with a percent sign and their two-digit hex byte value.
Reserved characters have URL meaning, so you encode them when they are data, not structure.
In CI, tokens and query values with special characters must be URL-encoded or they corrupt the request.