Forge Containers are now available through Forge's Early Access Program (EAP). To start testing this feature, submit your app's ID to our team through this link.

EAPs are offered to selected users for testing and feedback purposes. APIs and features under EAP are unsupported and subject to change without notice. APIs and features under EAP are not recommended for use in production environments.

For more details, see Forge EAP, Preview, and GA.

Forge Containers uses a sidecar service to act as a proxy and handle your containerised service’s inbound and outbound requests. This sidecar authenticates invocation requests to your service.

Inbound requests

Forge adds the following headers to requests sent to your containerised service’s REST API:

Header	Description
`x-b3-traceid`	Indicates the overall ID of the trace. Every span in a trace shares this ID.
`x-b3-spanid`	Indicates the position of the current operation in the trace tree. The value should not be interpreted: it may or may not be derived from the value of the TraceId.
`x-forge-invocation-id`	A unique ID for an invocation, which you can use to attach context from the invocation to an outbound request (including authentication).
`x-forge-invocation-log-attributes`	An opaque string of log-related metadata (encoded in `base64`). This should be added to JSON-structured logs with a `forge_invocation` key to improve the log filtering experience in the Developer Console.

Outbound requests

All @forge/* packages are not currently supported in Forge Containers, including:

Your app’s containerised service can send requests to the REST APIs of:

Atlassian products like Jira, Confluence, and any other product supported by Forge
Forge hosted services like:
- KVS/Custom Entity Store
- Forge SQL (only accessible via Forge Containers in this EAP)
- Forge Object Store (only accessible via Forge Containers in this EAP)
External hosts declared in the app’s egress permissions

In order to make outbound requests from your container you will need to send requests via the egress sidecar. The URL to communicate with the egress sidecar can be retrieved from the FORGE_EGRESS_PROXY_URL environment variable. Requests to the egress sidecar must contain a forge-proxy-authorization header with the following information:

Field	Required?	Description
`id`	Yes (The request must include either `installationId` or `id`)	An invocation ID that provides the context and authentication for this request (namely, `x-forge-invocation-id` from a corresponding inbound request).
`installationId`		An installation ID that provides the context and authentication for this request (see Call a containerised service without an invocationId for more details).
`as=<user\|app>`	No	Specifies whether to call the API using either the app or its user as its context.
`accountId=<accountId>`	No	Specify an accountId to make a request using offline user impersonation. The `as` field must be set to user. See Offline user impersonation for more information.

For example:

1
2
GET <FORGE_EGRESS_PROXY_URL>/jira/<path>
  -H forge-proxy-authorization: Forge as=<user|app>,id=<x-forge-invocation-id>,accountId=<accountId>

To fetch information on a Forge Invocation Context you can call the following API:

1
2
GET <FORGE_EGRESS_PROXY_URL>/invocation/context
  -H forge-proxy-authorization: Forge id=<x-forge-invocation-id>

API path prefixes

The following table lists each Atlassian/Forge service's corresponding API path prefix. This prefix is appended to your request's FORGE_EGRESS_PROXY_URL.

Prefix	Description
`/invocation/context`	Fetch information on current invocation context. For example: `GET <FORGE_EGRESS_PROXY_URL>/invocation/context -H forge-proxy-authorization: Forge id=<x-forge-invocation-id>`
`/proxy`	Egress to the Internet. For example: `GET <FORGE_EGRESS_PROXY_URL>/proxy/httpbin.org/status/200 -H forge-proxy-authorization: Forge id=<x-forge-invocation-id>`
`/jira`	Egress to Jira APIs: Jira Jira Software Jira Service Management For example: `GET <FORGE_EGRESS_PROXY_URL>/jira/rest/api/3/myself -H forge-proxy-authorization: Forge id=<x-forge-invocation-id>,as=app`
`/confluence`	Egress to the Confluence APIs For example: `GET <FORGE_EGRESS_PROXY_URL>/confluence/wiki/rest/api/user/current -H forge-proxy-authorization: Forge id=<x-forge-invocation-id>,as=app`
`/atlassian/graphql`	Send a request to the GraphQL API. For example: `POST <FORGE_EGRESS_PROXY_URL>/atlassian/graphql -H forge-proxy-authorization: Forge id=<x-forge-invocation-id>,as=app`
`/forge/storage/sql/v1/execute`	Execute a DML statement through the Forge SQL REST API. For example: `POST <FORGE_EGRESS_PROXY_URL>/forge/storage/sql/v1/execute -H forge-proxy-authorization: Forge id=<x-forge-invocation-id>,as=app -d '{ "query": "SELECT * FROM BOOKS;", "method": "all", "params": [] }'`
`/forge/storage/sql/v1/batch`	Execute multiple DML queries in a batch through the Forge SQL REST API. For example: `POST <FORGE_EGRESS_PROXY_URL>/forge/storage/sql/v1/batch -H forge-proxy-authorization: Forge id=<x-forge-invocation-id>,as=app -d '{"statements":[{"query":"INSERT INTO Authors (name, birth_date);","params":["John Doe","1982-01-22 14:45:35"]},{"query":"INSERT INTO Books (title, author, published_date);","params":["MY_FIRST_BOOK","John Doe","2025-01-22 14:45:35"]}]}'`
`/forge/storage/kvs/`	Egress to the KVS/Custom Entity Store's API For example: `POST <FORGE_EGRESS_PROXY_URL>/forge/storage/kvs/v1/get -H forge-proxy-authorization: Forge id=<x-forge-invocation-id>,as=app -d '{ "key": "key" }'`
`/forge/storage/os`	Send a request to the Forge Object Store REST API. For example: `POST <FORGE_EGRESS_PROXY_URL>/forge/storage/os/v1/download-url -H forge-proxy-authorization: Forge id=<x-forge-invocation-id>,as=app -d '{ "key": "key" }'`
`/forge/realtime/publish`	Publish a message through the Forge Realtime REST API. For example: `POST <FORGE_EGRESS_PROXY_URL>/forge/storage/realtime/publish -H forge-proxy-authorization: Forge id=<x-forge-invocation-id>,as=app -d '{ "name": "name-of-the-channel", "payload": "string-message-sent-to-the-channel" }'`
`/atlassian/forge/events/v1/async-events`	Queue an event through the Async Events REST API. For example: `POST <FORGE_EGRESS_PROXY_URL>/atlassian/forge/events/v1/async-events -H forge-proxy-authorization: Forge id=<x-forge-invocation-id>,as=app -d '{ "queueName": "queueName", "events": [ { "body": { "message": "Hello World" }, "delayInSeconds": 5, } ] }'`
`/v0/installations`	Use the App Installations REST API to retrieve all installations for the current app environment. This is useful when making offline API calls on behalf of an installation within your app environment. For example: `GET <FORGE_EGRESS_PROXY_URL>/v0/installations`

Environment Variables

When your container is started it will be injected with the following environment variables:

Variable	Description
`SERVER_PORT`	The port at which the container service should listen for incoming requests. For example: `8080`
`FORGE_APP_ARI`	A unique Atlassian resource identifier (`ari`) assigned to your app. The Forge CLI supplies this identifier when you create or register an app for the first time. For example:`ari:cloud:ecosystem::app/d60dfafb-a14d-4d56-bf03-0c3823d39e2b`
`FORGE_CONTAINER_KEY`	The key of the container, which is the value of the `services:container:key` field in the Forge manifest. For example: `java-service`
`FORGE_EGRESS_PROXY_URL`	The URL to the Forge Containers sidecar service. For example: `http://localhost:7072`
`FORGE_ENV_ARI`	A unique Atlassian resource identifier (`ari`) assigned to your app environment. For example: `ari:cloud:ecosystem::environment/d60dfafb-a14d-4d56-bf03-0c3823d39e2b/d67ce878-3e91-404b-b523-9e1d9bf867d5`
`FORGE_IMAGE_TAG`	The tag of the image that is currently running. For example: `1.0.0`
`FORGE_SERVICE_KEY`	The key of the service, which is the value of the `services:key` field in the Forge manifest. For example: `java-service`

When running forge deploy, all environment variables set through the forge variables set command will also be injected into the container.