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.

この記事は次のような方にお勧めです

  • Developers who want to run PHP/Composer projects on the OpenAI Codex
  • People who want to build projects that depend on private GitHub repositories
  • Engineers who want to make secret management smarter using CI/CD and cloud IDE
  • composer installPeople who are stuck on 404 / authentication required
  • People who want to learn best practices for PAT + COMPOSER_AUTH
Table of Contents

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.1

GITHUB_TOKEN So that's not okay?

In GitHub Actions, you can GITHUB_TOKENs using the automatically generated < wpml_ignored_tag ​​>.
However...

  1. Narrow scope of effect
    < GITHUB_TOKEN ​​> is limited to that repository, so it is not sufficient in cases where you want to resolve cross-organizational dependencies.
  2. Short-lived: Issued for each runner execution and cannot be reused by external services (such as Composer containers).
  3. Not compatible with Composer's authentication format
    Composer will not recognize < GITHUB_TOKEN ​​> if you simply pass it to the environment variable, so you need to rewrite < auth.json ​​> with an additional script.

Considering these points, it is easier and safer to put COMPOSER_AUTH as a secret, as it is always available and can be done with just one JSON.

"Dedicated PAT" rather than "limited token" is the GitOps best practice.

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.2

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

Issuing a token for Composer on the GitHub Personal Access Token creation screen

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.3

ステップ
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

Environment settings screen with COMPOSER_AUTH registered in the Secrets section of OpenAI Codex
Adding COMPOSER_AUTH to the Codex Secrets allows Composer to authenticate access to private repositories.

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

COMPOSER_AUTH is correctly reflected in the OpenAI Codex terminal, and composer authentication is successful.

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.4

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.5

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

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 ↩︎

Categories
Codex and Generation AI
Tags
Previous article
Ultimate Member Practical Guide ①: Create a user registration form with drag and drop in just 4 steps!
2025年6月4日