Codex: Advanced agentic configuration

By default, Agentic Pipelines uses a system-provided Codex configuration that is suitable for simple use cases. For more advanced scenarios, you can:

Provide your own codex-config-overrides.toml and refer to it in the configuration path within the bitbucket-pipelines.yml
Override configuration fields directly from bitbucket-pipelines.yml
Add additional MCP servers
Plug in an Atlassian MCP server or TWG CLI by providing a user API token

Codex Provider requirements

The Codex runs out of the box on most of the latest major Linux-based Docker images. If you prefer to use the default image, please use atlassian/default-image:5 as the adapter requires OpenSSL 3.

However, Codex has a few non-mandatory dependencies that are recommended but not required:

For fast file search, Codex uses ripgrep (rg).
For sandboxing, Codex uses bubblewrap (bwrap). Agentic Pipelines disables the sandbox by default. However, if you are planning to utilize the sandbox feature, follow the Codex Sandbox Documentation to setup the bwrap.

You can always check your environment by running codex doctor. Refer to the Codex CLI documentation for more details.

Provide your own custom Codex config file

You can supply your own Codex configuration (a TOML file) and have Pipelines merge it with the system base config.

Note: Codex configuration uses TOML. Provide your file via config.path (see below). Pipelines merges it with the system config and writes the result to .codex/config.toml in your repository — this generated file is added to Git's exclude list, so do not commit your own .codex/config.toml (it will be regenerated). See the Codex configuration reference for the full list of keys.

You can store the configuration:

in your repository (for example .codex/my-config.toml or codex-config-overrides.toml)
included in the build image
generated earlier in the step script

The configuration file at config.path is merged with the Pipelines system configuration. See Agentic Pipelines - System defaults for details on what is configured for you.

Example config.toml

model = "gpt-5.5"
model_reasoning_effort = "high"

Use configuration overrides in `bitbucket-pipelines.yml`

Instead of, or in addition to, a config file, you can define config.overrides directly in your pipeline YAML. Overrides can be provided by a Dynamic Pipelines Provider to enforce specific agentic configuration.

構造

These can be specified on both the agent and step level.

overrides use the same structure as the Codex configuration schema, expressed as a YAML object.

Merge order

Configurations are merged in this order (later wins):

Pipeline system base configuration
User configuration from config.path (TOML)
User configuration from config.overrides (YAML)
System‑enforced overrides

Within a given configuration level:

Maps are merged by key
Lists are overwritten (system‑enforced overrides are appended)

例

bitbucket-pipelines.yml

definitions:
  agents:
    my-agent:
      prompt: Explain this repository
      provider: codex
pipelines:
  default:
    - step:
        script:
          - agent: my-agent
            config:
              overrides:
                model: gpt-5.5
                model_reasoning_effort: high

config.toml (from config.path)

model = "gpt-5.4"
model_reasoning_effort = "medium"
web_search = "cached"

Merged configuration

model from the YAML overrides wins
model_reasoning_effort from the YAML overrides wins
web_search is retained from the config file

model = "gpt-5.5"
model_reasoning_effort = "high"
web_search = "cached"

Sandboxing and permissions

Known limitation

An OS-level sandbox may rely on bubblewrap depending on the setting. Check Codex’s official documentation on how to set it up, if needed Sandbox – Codex | OpenAI Developers

Codex controls what the agent can do through two Codex settings — sandbox_mode and approval_policy. On top of that, you can use the permissions.on-ask setting in the Bitbucket Pipelines configuration to control how Agentic Pipelines responds to potential permission requests from Codex. All three settings work together. For each action the agent attempts:

sandbox_mode decides whether the action is within the allowed boundary. If it is, the action runs immediately. If it crosses the boundary (for example, writing outside the workspace, or network access), Codex escalates to step 2. Check Codex Sandbox documentation for more details.
approval_policy decides what to do with that boundary-crossing action — run it, refuse it outright, or raise an approval request. Check Codex Permissions Documentations for more details.
When an approval request is raised, Agentic Pipelines answers the request on your behalf based on the permissions.on-ask configuration.

For more details about how permission works within Codex, refer to Permissions – Codex | OpenAI Developers and Sandbox – Codex | OpenAI Developers.

Configure what the agent may do using Codex’s `sandbox_mode`

Set sandbox_mode via config.path or config.overrides:

read-only — the agent can read files but cannot modify the workspace
workspace-write — the agent can read and write within the workspace; grant extra paths with writable_roots
danger-full-access — no restrictions (default in Agentic Pipelines)

The sandbox permission boundary can also be fine-tuned. Check Codex Permissions Documentation for more details.

Example — restrict the agent to writing only within the workspace:

definitions:
  agents:
    my-agent:
      prompt: Update the changelog
      provider: codex
      config:
        overrides:
          sandbox_mode: workspace-write
pipelines:
  default:
    - step:
        script:
          - agent: my-agent

Configure when the agent asks using Codex’s `approval_policy`

Set approval_policy via config.path or config.overrides:

untrusted: ask for approval before running untrusted commands
on-request: Codex decides when to ask in-boundary commands are auto-approved, boundary-crossing ones are escalated (default in Agentic Pipelines)
never: never ask; the agent is then bounded only by sandbox_mode

Approval policy from Codex can also be fine tuned. Check Codex Advanced Configuration for more details.

Configure how the pipeline answers permission requests using `permissions.on-ask`

Because pipelines run non-interactively, Agentic Pipelines answers every approval request Codex raises, based on permissions.on-ask on the agent.

definitions:
  agents:
    my-agent:
      provider: codex
      prompt: "Generate an activity report on this repository and post it in Slack."
      permissions:
        on-ask: allow
pipelines:
  default:
    - step:
        script:
          - agent: my-agent

With on-ask: allow, Agentic Pipelines answers "yes" to every approval request. With on-ask: deny, Agentic Pipelines answers "no" to every approval request. Note this configuration only takes effect whenever Codex asks for permission approval based on the sandbox and approval policy.

Add an extra MCP server

In addition to the Bitbucket Pipelines MCP server (which is provided automatically), you can configure third-party MCP servers to extend the capabilities of your agent.

Unlike some other tools, Codex does not use a .mcp.json file — MCP servers are defined in your Codex configuration under [mcp_servers.<name>] tables. For more details, see the Codex MCP documentation.

1. Define your MCP server in your Codex config

Add an [mcp_servers.<name>] table to a TOML config file and reference it from your pipeline with config.path. Refer to the Provide your own Codex config file section above.

Example .codex/my-config.toml

# stdio server
[mcp_servers.my-stdio-server]
command = "command-to-run"
args = ["arg1", "arg2"]
env = { ENV_VAR = "value" }
# streamable HTTP server
[mcp_servers.my-http-server]
url = "https://example.com/mcp"

Supported transports

Codex supports two transport methods:

STDIO: a local process communicating over standard input/output (most common) — use command, args, and optionally env
HTTP: a MCP server accessed over HTTP — use url, and supply credentials based on requirements from the server.

2. Reference the config in your pipeline

例

definitions:
  agents:
    my-agent:
      prompt: "Do something using my extra MCP tools"
      config:
        path: .codex/my-config.toml
pipelines:
  default:
    - step:
        script:
          - agent: my-agent

Enabling the ChatGPT Apps/connectors support

For the security concern, the built-in Codex Apps support has been disabled by Agentic Pipelines in the default settings. This feature will inject a Codex Apps MCP server into the Codex runtime, which is responsible for fetching and using apps from your ChatGPT configuration.

If you need to use this integration, you can enable it using the custom config or config overrides.

例

# bitbucket-pipelines.yml
definitions:
  agents:
    my-agent:
      prompt: "Do something using codex apps"
      config:
        path: .codex/my-config.toml
pipelines:
  default:
    - step:
        script:
          - agent: my-agent
# .codex/my-config.toml
# <other settings>
# You can refer to codex's doc for more details
# https://developers.openai.com/codex/config-basic#supported-features
[features]
apps = true

Configuring Atlassian MCP (Jira, Confluence, etc.)

Create an API token at https://id.atlassian.com/manage-profile/security/api-tokens.
Build the Authorization header value: Basic followed by the base64 of email:token. For example, run the following in the terminal: printf 'Basic %s' "$(echo -n "user@example.com:$(pbpaste)" | base64)" | pbcopy
Create a repository secret named ATLASSIAN_MCP_AUTH with that value (it should look something like Basic dXNlci4uLg==).
Add the MCP server to your Codex config and reference it from your pipeline (see the examples below).

Codex add the secret into the request header at runtime using env_http_headers, which maps a header name to the name of an environment variable. The repository secret ATLASSIAN_MCP_AUTH is available as an environment variable in the step, and its value is sent verbatim as the Authorization header.

.codex/atlassian-mcp.toml example

[mcp_servers.atlassian-mcp]
url = "https://mcp.atlassian.com/v1/native/mcp"
[mcp_servers.atlassian-mcp.env_http_headers]
Authorization = "ATLASSIAN_MCP_AUTH"

bitbucket-pipelines.yml (snippet) example

definitions:
  agents:
    test-atlassian-mcp:
      provider: codex
      prompt: List all available confluence spaces
      config:
        path: .codex/atlassian-mcp.toml
pipelines:
  custom:
    test-atlassian-mcp:
      - step:
          script:
            - agent: test-atlassian-mcp

この内容はお役に立ちましたか?

正確ではなかった明確ではなかった関係なかった

さらにヘルプが必要ですか?

アトラシアンコミュニティをご利用ください。

コミュニティに質問