Test PAT & Environment Configuration

This page covers GitHub PAT usage in test environments and .env configuration. For OAuth App creation, Coder integration, and production security, see the other Token Guide pages.

GitHub PAT in test environments only

In production, OpenFlows forbids personal access tokens. In isolated test and CI environments, however, a PAT can be used as a stand-in for Coder external auth so that integration tests can run without an interactive OAuth flow.

When a PAT is acceptable

The environment is ephemeral, short-lived, and not connected to production repositories.
The PAT is issued from a dedicated test bot account with minimal repository access.
The PAT file is deleted when the test environment is torn down.
The PAT is never committed to source control or baked into an image.

If any of these conditions is not true, use Coder external auth instead.

Place the PAT file

OpenFlows looks for the test PAT at the file path specified by GITHUB_TOKEN. The conventional location is /tmp/github_token. The orchestrator reads the file at startup and uses the PAT only for GitHub operations in test mode. The file should be written before the orchestrator starts and removed after the test run.

bash

# Create a test PAT with only repo access
echo "ghp_..." > /tmp/github_token
chmod 600 /tmp/github_token

# Verify the orchestrator can read it
ls -l /tmp/github_token
# -rw------- 1 openflows openflows 45 Jul 20 12:34 /tmp/github_token

Recommended PAT scopes

Use a classic PAT with the smallest scope set that exercises the code paths you need. For most integration tests, repo is sufficient. If the agents test workflow modifications, add workflow. Do not grant admin, delete_repo, or organization-wide permissions.

Token type	Typical scopes	Use case
OAuth App token	`repo`, `workflow`, `read:org`, `user:email`	Short-lived, per-user, obtained by Coder external auth. Used by the Coder control plane to act on GitHub on behalf of the tenant.
Coder API token	Workspaces, templates, users, and organizations as required by the orchestrator	Long-lived service token issued to the OpenFlows orchestrator. Stored in `CODER_SESSION_TOKEN`.
GitHub PAT (test only)	`repo`, `workflow` if needed	Loaded from `/tmp/github_token` in isolated test environments. Must never be placed inside a Coder workspace.

Never mount /tmp/github_token into a production workspace

The test PAT path is a convenience for CI. If you deploy a production OpenFlows instance, leave GITHUB_TOKEN unset or empty and rely entirely on Coder external auth. A production workspace that contains a GitHub PAT is a deployment failure, not a supported configuration.

Environment configuration

Copy .env.example to .env and fill in the values. The orchestrator reads the file at startup and uses it to locate Coder, identify the GitHub OAuth App, and configure the Redis SharedStore.

bash

cp .env.example .env
# edit .env with your values

The variables that govern token and authentication behavior are:

Variable	Meaning
`GITHUB_OAUTH_CLIENT_ID`	The client ID of the GitHub OAuth App that Coder uses for external authentication. Found on the OAuth App settings page.
`GITHUB_OAUTH_CLIENT_SECRET`	The client secret of the GitHub OAuth App. Treat it as a high-value credential; rotate it immediately if it is exposed.
`GITHUB_OAUTH_REDIRECT_URL`	The callback URL for Coder external auth. Must match the value registered in the OAuth App. Example: `https://coder.example.com/external-auth/callback`.
`CODER_URL`	The root URL of your self-hosted Coder deployment. Example: `https://coder.example.com`.
`CODER_SESSION_TOKEN`	A Coder API token issued to the OpenFlows orchestrator. It grants the orchestrator permission to call the Coder control plane, provision workspaces, and invoke the Chats API.
`GITHUB_TOKEN`	(Test and development only) A file path, conventionally `/tmp/github_token`, that holds a GitHub personal access token. Not used in production.
`OPENFLOWS_REDIS_URL`	Connection string for the Redis SharedStore. Example: `redis://redis:6379`.

After editing .env, run the bootstrap command to validate the connection to Coder and push the required templates:

bash

./scripts/prod.sh bootstrap

The bootstrap command checks that the Coder token is valid and that the GitHub external auth provider is reachable. If either check fails, it prints an actionable error and exits before any tenant is created.

See Scopes, Rotation & Security for least-privilege scopes, rotation procedures, and security best practices.