Git Hub

Get the installation URL for the GitHub App

GET /api/github/accounts/install-url

Query Parameters

redirectUri string (required)

Response

200 — OK

Get the settings for the GitHub App

GET /api/github/app/settings

Response

200 — Success

CanUseGitHubApp boolean
CanUseTrustedFlow boolean

{
  "CanUseGitHubApp": true,
  "CanUseTrustedFlow": true
}

Get the status of the registration between Octopus Server and the GitHub App

GET /api/github/app/status

Response

200 — Response containing the status of the registration between Octopus Server and the GitHub App

Status string
The status of the GitHub App registration. Valid values are: Connected, RegistrationInvalid, Error. Minimum length 1.

{
  "Status": "string"
}

Get GitHub App connections for the space

GET /api/{spaceId}/github/connections

Also reachable at /api/spaces/{spaceIdentifier}/github/connections.

Path Parameters

spaceId string (required)

Query Parameters

skip integer (required)
Number of items to skip. Defaults to zero. Minimum 0.
take integer (required)
Number of items to take. Defaults to 30. Minimum 0.

Response

200 — All GitHub App connections for the space

Connections array of object
- Id string
- Installation object
- Status enum
  Allowed values: ConnectionNotFound, InstallationNotFound, InstallationSuspended, Connected, Error.
ItemsPerPage integer
NumberOfPages integer
TotalResults integer

{
  "Connections": [
    {
      "Id": "string",
      "Installation": {
        "AccountAvatarUrl": "string",
        "AccountId": "string",
        "AccountLogin": "string",
        "AccountType": "string",
        "AllRepositories": true,
        "InstallationId": "string"
      },
      "Status": "ConnectionNotFound"
    }
  ],
  "ItemsPerPage": 0,
  "NumberOfPages": 0,
  "TotalResults": 0
}

Create a new GitHub App connection for an installation

POST /api/{spaceId}/github/connections

Also reachable at /api/spaces/{spaceIdentifier}/github/connections.

Path Parameters

spaceId string (required)

Request Body

InstallationId string (required)
Minimum length 1.
RepositoryIds array of string (required)
SpaceId string (required)

Response

201 — Created

{
  "InstallationId": "string",
  "RepositoryIds": [
    "string"
  ],
  "SpaceId": "Spaces-1"
}

"string"

Get the GitHub repositories for the current connection

GET /api/{spaceId}/github/connections/{connectionId}/repositories

Also reachable at /api/spaces/{spaceIdentifier}/github/connections/{connectionId}/repositories.

Path Parameters

connectionId string (required)
spaceId string (required)

Response

200 — GitHub repositories available for the current connection

Repositories array of object
- DefaultBranch string
- GitUrl string
- IsAdmin boolean
- IsPrivate boolean
- Language string
- RepositoryId string
- RepositoryName string
- Visibility string

{
  "Repositories": [
    {
      "DefaultBranch": "string",
      "GitUrl": "string",
      "IsAdmin": true,
      "IsPrivate": true,
      "Language": "string",
      "RepositoryId": "string",
      "RepositoryName": "string",
      "Visibility": "string"
    }
  ]
}

Get a single GitHub app connection by id

GET /api/{spaceId}/github/connections/{id}

Also reachable at /api/spaces/{spaceIdentifier}/github/connections/{id}.

Path Parameters

id string (required)
spaceId string (required)

Response

200 — A GitHub app connection

Id string
Installation object
- AccountAvatarUrl string
- AccountId string
- AccountLogin string
- AccountType string
- AllRepositories boolean
  true if the installation has access to all repositories in the account, false if it has access to only selected repositories.
- InstallationId string
Repositories array of object
- DefaultBranch string
- GitUrl string
- IsAdmin boolean
- IsPrivate boolean
- Language string
- RepositoryId string
- RepositoryName string
- Visibility string
SpaceId string
Status string
Minimum length 1.
StatusUserMessage string
UnknownRepositories array of object
Repositories IDs that are configured on the connection but do not have a matching repository returned from GitHub.
- RepositoryId string
- RepositoryName string

{
  "Id": "string",
  "Installation": {
    "AccountAvatarUrl": "string",
    "AccountId": "string",
    "AccountLogin": "string",
    "AccountType": "string",
    "AllRepositories": true,
    "InstallationId": "string"
  },
  "Repositories": [
    {
      "DefaultBranch": "string",
      "GitUrl": "string",
      "IsAdmin": true,
      "IsPrivate": true,
      "Language": "string",
      "RepositoryId": "string",
      "RepositoryName": "string",
      "Visibility": "string"
    }
  ],
  "SpaceId": "Spaces-1",
  "Status": "string",
  "StatusUserMessage": "string",
  "UnknownRepositories": [
    {
      "RepositoryId": "string",
      "RepositoryName": "string"
    }
  ]
}

Update a GitHub App connection with a new set of repositories

PUT /api/{spaceId}/github/connections/{id}

Also reachable at /api/spaces/{spaceIdentifier}/github/connections/{id}.

Path Parameters

id string (required)
spaceId string (required)

Request Body

Id string (required)
RepositoryIds array of string (required)
SpaceId string (required)

Response

200 — GitHub app connection modified result

{
  "Id": "string",
  "RepositoryIds": [
    "string"
  ],
  "SpaceId": "Spaces-1"
}

{}

Delete a GitHub App Connection

DELETE /api/{spaceId}/github/connections/{id}

Also reachable at /api/spaces/{spaceIdentifier}/github/connections/{id}.

Path Parameters

id string (required)
Id of the GitHub connection to delete.
spaceId string (required)
The ID of the space containing the resource(s).

Response

200 — Used to indicate that a GitHub App Connection has been deleted

{}

Recover GitHub App connection after the registration has changed

POST /api/{spaceId}/github/connections/{id}/recover

Also reachable at /api/spaces/{spaceIdentifier}/github/connections/{id}/recover.

Path Parameters

id string (required)
spaceId string (required)

Request Body

Id string (required)
RepositoryIds array of string (required)
SpaceId string (required)

Response

200 — GitHub app connection recovery result

{
  "Id": "string",
  "RepositoryIds": [
    "string"
  ],
  "SpaceId": "Spaces-1"
}

{}

Recover GitHub App connection after the installation was not found

POST /api/{spaceId}/github/connections/{id}/recover-not-found

Also reachable at /api/spaces/{spaceIdentifier}/github/connections/{id}/recover-not-found.

Path Parameters

id string (required)
spaceId string (required)

Request Body

Id string (required)
InstallationId string (required)
RepositoryIds array of string (required)
SpaceId string (required)

Response

200 — GitHub app connection not-found recovery result

{
  "Id": "string",
  "InstallationId": "string",
  "RepositoryIds": [
    "string"
  ],
  "SpaceId": "Spaces-1"
}

{}

Refresh the GitHub App connection token

POST /api/{spaceId}/github/connections/{id}/refresh

Also reachable at /api/spaces/{spaceIdentifier}/github/connections/{id}/refresh.

Path Parameters

id string (required)
spaceId string (required)

Response

200 — GitHub app connection has been refreshed

{}

Get a list of GitHub organisations accessible to the current GitHub OAuth user. Request will fail if the user does not have a valid GitHub OAuth token

GET /api/{spaceId}/github/installations

Also reachable at /api/spaces/{spaceIdentifier}/github/installations.

Path Parameters

spaceId string (required)

Query Parameters

excludeConnected boolean

Response

200 — List of GitHub organisations accessible to the current GitHub OAuth user

Installations array of object
- AccountAvatarUrl string
- AccountId string
- AccountLogin string
- AccountType string
- AllRepositories boolean
  true if the installation has access to all repositories in the account, false if it has access to only selected repositories.
- InstallationId string

{
  "Installations": [
    {
      "AccountAvatarUrl": "string",
      "AccountId": "string",
      "AccountLogin": "string",
      "AccountType": "string",
      "AllRepositories": true,
      "InstallationId": "string"
    }
  ]
}

Handle the response from GitHub after an application has been installed or updated

GET /api/github/installations/updated

Query Parameters

installation_id string
redirectUri string (required)

Response

200 — OK

Get the GitHub repositories for an installation visible to the current user https://docs.github.com/en/rest/apps/installations?apiVersion=2022-11-28#list-repositories-accessible-to-the-user-access-token

GET /api/github/installations/{installationId}/repositories

Path Parameters

installationId string (required)

Query Parameters

skip integer (required)
Number of items to skip. Defaults to zero. Minimum 0.
take integer (required)
Number of items to take. Defaults to 30. Minimum 0.

Response

200 — Success

ItemType string
Items array of object
- DefaultBranch string
- GitUrl string
- IsAdmin boolean
- IsPrivate boolean
- Language string
- RepositoryId string
- RepositoryName string
- Visibility string
ItemsPerPage integer
LastPageNumber integer
NumberOfPages integer
TotalResults integer

{
  "ItemType": "string",
  "Items": [
    {
      "DefaultBranch": "string",
      "GitUrl": "string",
      "IsAdmin": true,
      "IsPrivate": true,
      "Language": "string",
      "RepositoryId": "string",
      "RepositoryName": "string",
      "Visibility": "string"
    }
  ],
  "ItemsPerPage": 0,
  "LastPageNumber": 0,
  "NumberOfPages": 0,
  "TotalResults": 0
}

Reset the GitHub app registration for this Octopus instance. This is a destructive command and will break all existing GitHub app connections across the instance. This should only be used as a last resort to recover connectivity with GitHub

POST /api/github/reset-registration

Response

200 — GitHub app registration was successfully deleted

{}

Search for GitHub repositories for an account visible to the current user https://docs.github.com/en/rest/search/search?apiVersion=2022-11-28#search-repositories

GET /api/github/search/{accountName}/repositories

Path Parameters

accountName string (required)

Query Parameters

keyword string
skip integer (required)
Number of items to skip. Defaults to zero. Minimum 0.
take integer (required)
Number of items to take. Defaults to 30. Minimum 0.

Response

200 — Success

ItemType string
Items array of object
- DefaultBranch string
- GitUrl string
- IsAdmin boolean
- IsPrivate boolean
- Language string
- RepositoryId string
- RepositoryName string
- Visibility string
ItemsPerPage integer
LastPageNumber integer
NumberOfPages integer
TotalResults integer

{
  "ItemType": "string",
  "Items": [
    {
      "DefaultBranch": "string",
      "GitUrl": "string",
      "IsAdmin": true,
      "IsPrivate": true,
      "Language": "string",
      "RepositoryId": "string",
      "RepositoryName": "string",
      "Visibility": "string"
    }
  ],
  "ItemsPerPage": 0,
  "LastPageNumber": 0,
  "NumberOfPages": 0,
  "TotalResults": 0
}

Get status of the users current authorization

GET /api/github/user/app/authorization_status

Query Parameters

includeUserDetails boolean

Response

200 — Get the status of the user’s current authorization.

CanAuthorize boolean
IsAuthorized boolean
UserDetails object
- AvatarUrl string
- Login string
- Name string
- PrimaryEmail string
- RefreshTokenValidTo string
  Format date-time.
- TokenValidTo string
  Format date-time.

{
  "CanAuthorize": true,
  "IsAuthorized": true,
  "UserDetails": {
    "AvatarUrl": "string",
    "Login": "string",
    "Name": "string",
    "PrimaryEmail": "string",
    "RefreshTokenValidTo": "2020-01-01T00:00:00.000Z",
    "TokenValidTo": "2020-01-01T00:00:00.000Z"
  }
}

Authorize the current user with the Octopus GitHub app

POST /api/github/user/app/authorize

Request Body

RedirectUri string (required)
Minimum length 1.

Response

200 — GitHub URL to authorize the GitHub app

AuthorizeUri string
Minimum length 1.

{
  "RedirectUri": "string"
}

{
  "AuthorizeUri": "string"
}

Exchange a GitHub App authorization code for an access token and store in the instance

POST /api/github/user/app/exchange-access-code

Request Body

Code string (required)
Minimum length 1.

Response

200 — Reports the success of exchanging a GitHub App authorization code for an access token

ErrorMessage string
Status string
Minimum length 1.

{
  "Code": "string"
}

{
  "ErrorMessage": "string",
  "Status": "string"
}

Exchange a GitHub App authorization code for an access token and store in the instance

GET /api/github/user/app/token

Query Parameters

code string (required)
redirectUri string (required)

Response

200 — OK

Deauthorize the GitHub app for the current user, removing this users GitHub tokens from Octopus

DELETE /api/github/user/app/token

Response

200 — Deauthorized GitHub app user

{}

Refresh the GitHub current app user. Refreshing the users token and cached GitHub account details

POST /api/github/user/app/token/refresh

Response

200 — GitHub App user has been successfully refreshed

{}

Test connectivity to GitHub using the provided credentials

POST /api/githubissuetracker/connectivitycheck

Request Body

BaseUrl string (required)
The GitHub base URL to test connectivity to. Minimum length 1.
Password string
The GitHub personal access token or password for authentication. If not provided, will be retrieved from configuration.
UserName string
The GitHub username for authentication.

Response

200 — Result of testing connectivity to GitHub

Messages array of object
Messages from the connectivity check.
- Category enum
  Allowed values: Info, Warning, Error.
- Message string
  Minimum length 1.

{
  "BaseUrl": "string",
  "Password": "string",
  "UserName": "string"
}

{
  "Messages": [
    {
      "Category": "Info",
      "Message": "string"
    }
  ]
}