Skip to main content
Version: 9.x (Current)

Providers Management

The Mia-Platform console allows you to interface with the most used git providers on the market (see here the supported git providers).
In order to configure a new provider on console you need to call a specific API as documented in the following paragraphs.

As an on-premise customer you have the ability to configure and use an authentication provider that differs from the git provider (i.e. Okta as authentication provider and GitLab as git provider).

info

You must create and configure a service account, which will be used to interact with the chosen Git provider.
As the service account is the only one to interact with the git provider, you will see it as author of some operations like pipelines trigger.

In the following sections, you will see how to use the relative APIs to create a new provider and associate the respective service account's token, which will be appropriately encrypted to ensure a high standard of security.

Providers APIs

In order to create a new provider you must call the respective API using the Console API Portal, under the "Providers" tag.

Providers tag

Two main APIs are exposed:

  • POST - /api/backend/providers: used to create a new provider;
  • PATCH - /api/backend/providers/{providerId}: used to edit an existing provider.
info

These APIs are protected and can be used only if you belong to the group access_token_manager.

Provider creation

To create a new provider, you must invoke the API /api/backend/providers.

Here is the request body form visible in the API Portal:

Providers creation body

We can divide the body in two categories: provider data and credentials data.

The provider data fields are:

  • id (string): it will be used to identify the provider;
  • label (string): an human-readable name for the provider;
  • type (string): the type of provider you are going to insert. Can be gitlab, github, bitbucket or azure-devops;
  • urls (object): an object that contains:
    • apiBase (string): the API base url of the provider (without trailing slash);
    • base (string): the base url of the provider (without trailing slash).

The credentials data fields are:

  • type (string): the type of credentials that you are going to insert. accepted values are token or userPass;
  • content (object): a dynamic object that contains the credentials of the service account.
    • For type userPass: must include userName and password fields;
    • For type token: must include only accessToken field.

Below you can find a complete example of the request, divided by provider:

{
"id": "my-github-provider",
"label": "Mia-Platform GitHub",
"type": "github",
"urls": {
"apiBase": "https://api.github.com",
"base": "https://github.com"
},
"credentials": {
"type": "token",
"content": {
"accessToken": "my-super-super-super-secret-token"
}
}
}
info

The credentials are stored encrypted in MongoDB.
For more information, take a look at the dedicated documentation section.

Associate provider to a Project

To associate the created provider to your project, you can use the CMS.

Navigate through the Projects section, select the desired project and change the providerId in the Repository section.

Insert providerId

Associate provider to a Company

To associate the created provider to your company, you can use the CMS.

Navigate through the Companies section, select the desired project and change the providerId in the Repository section.

Insert providerId

Provider editing

To edit an existing provider, you must invoke the API /api/backend/providers/{providerId}.

The request of this endpoint is identical to the previous one, except that here you have to insert the providerId in the endpoint params instead of the request body.

Here is the form visible in the API Portal:

Provider editing request body

Example code

Insert a provider

Now, we insert a provider of type gitlab, with id gitlab-id:

curl --location --request POST 'https://console-url/api/backend/providers' \
--header 'Cookie: sid={{CHANGE_ME_WITH_YOUR_SID}}' \
--header 'Content-Type: application/json' \
--data-raw '{"credentials":{"type":"token","content":{"accessToken":"my-super-super-super-secret-token"}},"id":"gitlab-id","label":"My GitLab Label","type":"gitlab","urls":{"apiBase":"https://gitlab-test.com/api","base":"https://gitlab-test.com"}}'

Edit a provider

To change the credentials for the provider previously added, with the id gitlab-id:

curl --location --request POST 'https://console-url/api/backend/providers/gitlab-id' \
--header 'Cookie: sid={{CHANGE_ME_WITH_YOUR_SID}}' \
--header 'Content-Type: application/json' \
--data-raw '{"credentials":{"type":"token","content":{"accessToken":"my-new-super-super-super-secret-token"}}'