Create a service principal for a CI/CD pipeline

Go to Administer and select Service Principals.

The list holds the API token principals your pipelines use. Each principal is scoped to one or more projects and is ingest only.

Select Create service principal.

Under Name, give the principal a name that identifies the pipeline it serves, such as ci-orders-pipeline.

Use a name you will recognize in an audit. The principal appears under this name everywhere access is reviewed.

Under Project scope, select the projects the pipeline needs. You can search the project list.

The scope is the point of the principal. A pipeline that reports on two projects should be scoped to those two, not to the workspace. The principal can only send data for connections and changelogs in these projects, and anything outside them is rejected.

Select Create & generate token.

The token is displayed once and cannot be retrieved afterwards. Select Copy token and store it in your CI system's secret store before you close the dialog.

The dialog also shows a configuration summary. The principal is ingest only, and the connections and changelogs it reports on must already be registered in Liquibase Secure server.

When you have saved the token, select I've saved the token to close the dialog.

Liquibase sends the token to Liquibase Secure server for you each time it runs in the pipeline. You do not add an Authorization header yourself. Instead, give Liquibase the token and the server address in the pipeline's configuration. For example, set these environment variables in the pipeline job that runs Liquibase:

Be sure to:

• Replace your_server_api_url with your server's API root, including the /api prefix. For example, https://liquibase.example.com/api

• Replace your_service_principal_token with the token you saved. Read it from your CI system's secret store rather than committing it.

• Replace your_connection_identifier and your_changelog_identifier with the identifiers of a connection and a changelog registered in a project the principal is scoped to.

You can set the same values as liquibase.platform.* properties in liquibase.properties instead. A service principal must send both identifiers. If either one is not registered, or is outside the principal's project scope, the data is rejected.

From the service principal list you can:

• Rotate to issue a new token for the same principal. The current token stops working immediately, so update your pipeline's secret before its next run. The replacement is shown once, the same way.

• Revoke to disable the principal. Its token stops working immediately, and this cannot be undone. Operations it already sent are kept. A revoked principal stays in the list and is shown as revoked.

Note: A service principal's project scope and permissions are set when you create it. There is no screen for changing them afterwards. To change what a principal can reach, create a replacement and revoke the old one.