post:
  summary: Trigger a rebuild, release or service run via an API token
  description: |
    This route allows to trigger

    - a Project/Package rebuild
    - a Project/Package release
    - a Package service run

    via an API token.

    You are required to authenticate with the API token secret. The API token secret needs
    to be provided either by HTTP headers or by a Hash-based Message Authentication Code (HMAC).

    See the [/person/{login}/token](#/Person/post_person__login__token) endpoint for
    information how to create an API token.
  security:
    - GitLab_key_authentication: []
  parameters:
    - in: header
      name: X-OBS-SIGNATURE
      description: |
        A HMAC of the request body, signed with the API token secret.
        Only useful in combination with the id parameter.
      schema:
        type: string
      example: 123458568938927827827
    - in: header
      name: X-HUB-SIGNATURE-256
      description: |
        A HMAC of the request body, signed with the API token secret.
        Only useful in combination with the id parameter.
      schema:
        type: string
      example: 123458568938927827827
    - in: header
      name: X-Pagure-Signature-256
      description: |
        A HMAC of the request body, signed with the API token secret.
        Only useful in combination with the id parameter.
      schema:
        type: string
      example: 123458568938927827827
    - in: header
      name: X-GitLab-Token
      description: The API token secret.
      schema:
        type: string
      example: THE_TOKEN_SECRET
    - in: header
      name: Authorization
      description: The API token secret in the Token realm.
      schema:
        type: string
      example: Token THE_TOKEN_SECRET
    - in: query
      name: id
      description: |
        Numerical ID of the token to trigger.
        This is required if you authenticate via a HMAC.
      schema:
        type: integer
      example: 1
    - in: query
      name: project
      description: |
        If the API token does not have a package assigned you can set a project via this parameter.
        The operation of the API token is then executed on this project.
      schema:
        type: string
      example: home:user
    - in: query
      name: package
      description: |
        If the API token does not have a package assigned you can set a package via this parameter.
        The operation of the API token is then executed on this package.

        Setting this requires the project parameter to be set too.
      schema:
        type: string
      example: vim
    - in: query
      name: repository
      description: |
        Restrict the API token operation to this repository.
        
        Only has an effect if the API token operation is 'rebuild' or 'release'.
      schema:
        type: string
      example: openSUSE_Factory
    - in: query
      name: arch
      description: |
        Restrict the API token operation to this architecture with this name.
        
        Only has an effect when the API token operation is 'rebuild' or 'release'.
      schema:
        type: string
      example: x86_64
    - in: query
      name: targetproject
      description: |
        Release binaries only to the provided project with this name.
        Setting this requires the 'targetrepository' parameter to be set also.

        Only has an effect if the API token operation is 'release'.
      schema:
        type: string
      example: devel:languages:ruby
    - in: query
      name: targetrepository
      description: |
        Release binaries only to the target repository with this name.
        Setting this requires the 'targetproject' parameter to be set also.

        Only has an effect if the API token operation is 'release'.
      schema:
        type: string
      example: openSUSE_Factory
    - in: query
      name: filter_source_repository
      description: |
        Release binaries only from the repository with this name.

        Only has an effect if the API token operation is 'release'.
      schema:
        type: string
      example: openSUSE_Factory
  responses:
    '200':
      $ref: '../components/responses/succeeded.yaml'
    '400':
      description: Bad Request.
      content:
        application/xml; charset=utf-8:
          schema:
            $ref: '../components/schemas/api_response.yaml'
          example:
            code: invalid_token
            summary: No valid token found
    '403':
      description: Forbidden.
      content:
        application/xml; charset=utf-8:
          schema:
            $ref: '../components/schemas/api_response.yaml'
          example:
            code: permission_denied
            summary: No valid token found
    '404':
      description: Not Found.
      content:
        application/xml; charset=utf-8:
          schema:
            $ref: '../components/schemas/api_response.yaml'
          examples:
            unknown_project:
              summary: Project not found
              value:
                code: unknown_project
                details: 'Project not found: home:Admin'
            unknown_package:
              summary: Package not found
              value:
                code: unknown_package
                details: 'Package not found: home:Admin/foo'
  tags:
    - Trigger
