Automation & GitHub API

Using the GitHub Contents API

If your automation creates or updates files in constants/trustCenterRegistry/ via the GitHub Contents API, follow these rules to avoid 409 Conflict and 422 Unprocessable Entity errors.

1. Content must be valid Base64 only

The content field must be a single string of valid Base64 (characters A-Z, a-z, 0-9, +, /, and = only).

• Do not embed JSON-style escape sequences inside the Base64 string (e.g. \n, \b, \\). Those characters are invalid in Base64 and will result in 422 "content is not valid Base64".
• Do: Encode the raw file bytes (UTF-8) once with a standard Base64 encoder. Use that string as-is as content. Do not double-escape or pretty-print the payload so that newlines or backslashes are introduced into the Base64.

Example (Node):

Buffer.from(fileContent, 'utf8').toString('base64')
// Use the result directly — no further escaping.

2. When updating, use the current file SHA

For PUT (create or update), if the file already exists you must send the current blob sha of that file in the request body.

• Do not reuse an old SHA from a previous run. After any commit that touches the file, the blob SHA on the default branch changes. Reusing an old SHA causes 409 Conflict ("file does not match …").
• Do: Before each update, GET the file:

GET /repos/{owner}/{repo}/contents/constants/trustCenterRegistry/{filename}

Use the sha from that response in the PUT body. If the file does not exist, omit sha for a create.

3. Idempotency / duplicate runs

If the same file is written twice (e.g. retries or duplicate tasks), the second run will 409 unless it uses the SHA from after the first run. To avoid that:

• Skip writing if the file already exists and content is unchanged, or
• Always GET the file first and use the returned sha for the PUT.

4. Registry file format

Each file in constants/trustCenterRegistry/ is a default export with name, website, trustCenter, platform, and iconUrl. See Adding Trust Centers for the exact format.

5. Generating a valid payload locally

From the repo root you can generate a request body with correct Base64 for a given registry file:

node scripts/utilities/github-contents-payload.js \
  constants/trustCenterRegistry/affinity.js \
  "Add trust center for Affinity"

This prints JSON you can use as the body for PUT /repos/trustlists/TrustLists/contents/constants/trustCenterRegistry/affinity.js (plus you must GET the current sha first if the file already exists).