GitLab Jira forge installation API

openapi: 3.2.0
info:
  title: GitLab REST Jira forge installation API
  description: GitLab REST API used to interact with a GitLab installation.
  termsOfService: https://handbook.gitlab.com/handbook/legal/api-terms/
  version: '19.6'
  license:
    name: CC BY-SA 4.0
    url: https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE
    x-gitlab-description: The license applies to the OpenAPI specification document itself. For terms governing use of the GitLab API, see the termsOfService field.
servers:
- url: https://{hostname}
  description: GitLab REST API
  variables:
    hostname:
      default: gitlab.com
      description: Your GitLab instance hostname
security:
- http: []
- oauth2: []
- apiKey: []
tags:
- name: Jira forge installation
  description: 'Use this API to configure a GitLab for Jira (Forge) installation, by setting the GitLab instance URL

    it points to and registering the system token it uses to synchronize development information. For more

    information, see the Jira integrations.'
  x-displayName: Jira Forge installation
paths:
  /api/v4/integrations/jira_forge/installation:
    put:
      operationId: putApiV4IntegrationsJiraForgeInstallation
      summary: Update the GitLab for Jira (Forge) installation instance URL
      description: Sets the GitLab instance the installation points at. Omit instance_url (or send null) for GitLab.com. Requires a Jira site or organization admin.
      tags:
      - Jira forge installation
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesBasicSuccess'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Unprocessable entity
        '400':
          description: Bad Request
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/putApiV4IntegrationsJiraForgeInstallationRequest'
      x-gitlab-lifecycle: experiment
    delete:
      operationId: deleteApiV4IntegrationsJiraForgeInstallation
      summary: Destroy the GitLab for Jira (Forge) installation on app uninstall
      description: Called by the Forge app preUninstall hook. A pure-native install fires no Connect uninstalled event, so this is what removes the installation, its subscriptions, and deactivates the linked jira_cloud_app integrations. FIT authentication carries the same trust as the signed Connect lifecycle event, so no Jira admin check is needed. Succeeds with no change when the installation is already gone.
      tags:
      - Jira forge installation
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesBasicSuccess'
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable entity
      x-gitlab-lifecycle: experiment
  /api/v4/integrations/jira_forge/installation/forge_token:
    post:
      operationId: postApiV4IntegrationsJiraForgeInstallationForgeToken
      summary: Register the GitLab for Jira (Forge) system token for direct dev-info sync
      description: Stores the Forge app system OAuth token (X-Forge-Oauth-System header) and the Jira apiBaseUrl (from the FIT), so GitLab pushes dev-info directly to Jira. See Atlassian::Forge::SystemTokenClient.
      tags:
      - Jira forge installation
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesBasicSuccess'
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable entity
        '400':
          description: Bad Request
      x-gitlab-lifecycle: experiment
components:
  schemas:
    putApiV4IntegrationsJiraForgeInstallationRequest:
      type: object
      properties:
        instance_url:
          type:
          - string
          - 'null'
          description: Base URL of the self-managed GitLab instance; null for GitLab.com
          maxLength: 1024
    APIEntitiesBasicSuccess:
      type: object
      properties:
        success:
          type: object
  securitySchemes:
    http:
      type: http
      scheme: bearer
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://gitlab.com/oauth/authorize
          tokenUrl: https://gitlab.com/oauth/token
          refreshUrl: https://gitlab.com/oauth/token
          scopes:
            api: Grants complete read/write access to the API, including all groups and projects, the container registry, the dependency proxy, and the package registry.
            read_api: Grants read access to the API, including all groups and projects, the container registry, and the package registry.
            read_user: Grants read-only access to your profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users.
            create_runner: Grants create access to the runners.
            manage_runner: Grants access to manage the runners.
            k8s_proxy: Grants permission to perform Kubernetes API calls using the agent for Kubernetes.
            self_rotate: Grants permission for token to rotate itself.
            mcp: Grants read-write access to remote Model Context Protocol (MCP) server for tools execution.
            mcp_orbit: Grants access to the Orbit Knowledge Graph MCP server for graph queries and schema retrieval.
    apiKey:
      type: apiKey
      name: PRIVATE-TOKEN
      in: header