How to solve composer install of private GitHub in OpenAI Codex with COMPOSER_AUTH

Hello, I'm Wakatchi (@wakatchi_tech).

There are some required settings when connecting to a private GitHub repository with OpenAI Codex, so I'll make a note of them here.

TL;DR;

If you want to access a private GitHub repository when resolving Composer dependencies in an OpenAI Codex environment, the standard approach is to pass COMPOSER_AUTH, which is a JSON wrapper around a GitHub PAT (Personal Access Token), as a secret.

You can use Composer's "environment variable-based authentication" mechanism as is, and Codex will automatically inject secrets into the container, so you don't have to commit unnecessary configuration files.

When setting the secret in the Codex, don't forget to wrap it in JSON with < github-oauth ​​> instead of the access token itself.

Introduction

When I recently came across the Codex, < composer install ​​> got stuck on 404/authentication required.

After some research, it seems that the Codex setup script runs under a Docker container + network restrictions, so Composer was unable to shake hands with GitHub.

The solution is to register COMPOSER_AUTH as a Codex secret... I came to this conclusion, which is a pretty obvious one, so I'll summarize the steps and some pitfalls as a memo.

What is COMPOSER_AUTH anyway?

• Composerはauth.jsonの代わりにCOMPOSER_AUTH環境変数を読む機能を持つ。
• The value is just the same JSON as < auth.json{"github-oauth":{"github.com":"ghp_xxxxx..."}} ​​> stored “on one line” (in the Codex, just paste it into the secret described below).

This method does not require you to store authentication information in the repository, so it is safe from a GitOps perspective.¹

Why does the Codex require COMPOSER_AUTH?

1. Codex is designed to run code in isolated containers, either locally or in the cloud
2. The container does not have a GitHub PAT, so the app cannot obtain the dependent libraries it needs,composer install and fails.
3. Codex's Environment <>> Secrets can pass environment variables and secrets.
4. Works well with Composer's environment variable authentication → COMPOSER_AUTH is the only choice

The same steps are covered in a how-to article on dev.to, and are a common path for many PHP developers.²

Registering secrets in the Codex environment

If you issue an access token on GitHub and register the secret on the Codex dashboard, < composer install ​​> will be allowed through.

Issue an access token on GitHub

Issue an access token (PAT) in your account's settings > Developer settings > Personal access tokens.

Both fine-grained and classic tokens are OK.

repo If you have a scope, that's OK.³

ステップ

1

Creating JSON on a single line

Create a string using the issued access token.

{"github-oauth":{"github.com":"<PAT>"}}

ステップ

2

Add COMPOSER_AUTH in Codex → ​​Environment → Secrets

Copy and paste the JSON created in step 2 into the value of COMPSER_AUTH.

If you simply copy and paste the access token as is, authentication will fail.

I completely forgot that it was in JSON format and wasted hours troubleshooting it.

ステップ

3

Check with Setup Script just to be sure

Setup Scriptで: "${COMPOSER_AUTH:?}"と記述し、ターミナルで実行してみると、COMPOSER_AUTHが正しく設定いるかを確認します。

Check the execution result in the terminal to confirm that the JSON you set in step 2 is set correctly.

: "${COMPOSER_AUTH:?}"

ステップ

4

Troubleshooting & Best Practices

404: Invalid access token

I suspect the PAT has expired or has insufficient scope.⁴

Check with the following command.

curl -H "Authorization: token <PAT>" https://api.github.com/user

Parse error due to newline in JSON

Remove line breaks in the editor or use VS Code's "Make single line" command to format.

CI/CD requires PAT for a different repository

GITHUB_TOKEN Since is limited to the target repository, the basic approach is to issue a PAT and set it as a secret variable.

Stack Overflow Case Studies

GitLab CI also requires COMPOSER_AUTH, and if it is not set, the build will fail.⁵

Some people prefer SSH Instead, but Codex says it's easier to do it using just the environment variables.⁶

Conclusion

Since Codex is an "AI agent that runs code in a container," handling authentication to external services is key.

If you prepare COMPOSER_AUTH as a secret, you can instantly solve the common problem of private repositories around Composer, and your setup script will also be neater.

これでもう auth.json を.gitIgnoreし忘れて焦る日々とはおさらば！

Use the information in this article to eliminate any potential problems and enjoy a fun Codex life.

I hope this article is of some help.

Thank you for reading to the end!

References

1. Documentation on using composer with private repositories ↩︎
2. How to Make ChatGPT Codex Work with PHP and Symfony ↩︎
3. enerate a GitHub Personal Access Token for Private Composer Packages ↩︎
4. Documentation on using composer with private repositories ↩︎
5. Gitlab Autodeploy Laravel private repo composer install COMPOSER_AUTH env var not read ↩︎
6. How to add private github repository as Composer dependency Ask Question ↩︎