Skip to content

Commit 2e08dc2

Browse files
saberkan-glsaberkan-gl
committed
docs: update how to use GitLab with GitLab CI/CD Catalog component
1 parent 200d8ef commit 2e08dc2

1 file changed

Lines changed: 70 additions & 95 deletions

File tree

  • content/documentation/guides/automation

‎content/documentation/guides/automation/gitlab.md‎

Lines changed: 70 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ draft: false
33
title: "Using GitLab CI"
44
date: 2019-11-11
55
publishdate: 2019-11-11
6-
lastmod: 2025-09-08
6+
lastmod: 2025-10-03
77
weight: 7
88
---
99

@@ -14,7 +14,13 @@ This guide shows how to integrate Microcks within your GitLab CI pipelines. You
1414
- **Import** API [Artifacts](/documentation/references/artifacts/) (OpenAPI, Postman, AsyncAPI, etc.) into a Microcks instance
1515
- **Launch tests** against a deployed API endpoint to verify contract conformance
1616

17-
We rely on the [Microcks CLI](/documentation/guides/automation/cli) executed via its container image inside GitLab CI jobs. Authentication uses a Microcks [Service Account](/documentation/explanations/service-account).
17+
To Integrate Microcks within your GitLab CI pipelines you can rely on [GitLab CI/CD Components](https://gitlab.com/explore/catalog/microcks-cncf/microcks-community/microcks-gitlab-components).
18+
19+
Authentication uses a Microcks [Service Account](/documentation/explanations/service-account).
20+
21+
## Finding the Component
22+
The Microcks GitLab Components are available in the GitLab CI/CD Catalog at:
23+
https://gitlab.com/explore/catalog/microcks-cncf/microcks-community/microcks-gitlab-components
1824

1925
## 1. Prerequisites
2026

@@ -30,118 +36,87 @@ We recommend storing credentials as masked GitLab CI variables:
3036

3137
In your project, navigate to Settings → CI/CD → Variables and add the variables above. Mark credentials as masked and protected according to your workflow.
3238

33-
## 2. Import job (push artifacts into Microcks)
39+
## 2. Importing API Artifacts (push artifacts into Microcks)
3440

35-
Use the `microcks-cli` container to import one or multiple specification files. Optionally mark artifacts as `primary` to drive multi-artifact behavior (see [Multi-artifacts](/documentation/explanations/multi-artifacts)).
41+
Use the `microcks-import` component to import one or multiple specification files.
3642

3743
```yaml
3844
# .gitlab-ci.yml (excerpt)
45+
include:
46+
- component: gitlab.com/microcks-cncf/microcks-community/microcks-gitlab-components/microcks-import@~latest
47+
inputs:
48+
specs: "specs/weather-forecast-openapi.yml:true,specs/weather-forecast-postman.json:false"
49+
microcks_url: "https://microcks.apps.acme.com/api/"
50+
keycloak_client_id: $KEYCLOAK_CLIENT_ID
51+
keycloak_client_secret: $KEYCLOAK_CLIENT_SECRET
52+
stage: import
53+
image: "quay.io/microcks/microcks-cli:latest"
54+
3955
stages:
4056
- import
41-
42-
import-specs:
43-
stage: import
44-
image: quay.io/microcks/microcks-cli:latest
45-
variables:
46-
MICROCKS_URL: "$MICROCKS_URL" # set at project/group level
47-
KEYCLOAK_CLIENT_ID: "$KEYCLOAK_CLIENT_ID" # set at project/group level
48-
KEYCLOAK_CLIENT_SECRET: "$KEYCLOAK_CLIENT_SECRET" # set at project/group level
49-
script:
50-
- |
51-
microcks-cli import \
52-
'specs/weather-forecast-openapi.yml:true,specs/weather-forecast-postman.json:false' \
53-
--microcksURL="$MICROCKS_URL" \
54-
--keycloakClientId="$KEYCLOAK_CLIENT_ID" \
55-
--keycloakClientSecret="$KEYCLOAK_CLIENT_SECRET"
5657
```
5758
58-
Notes:
59+
## Inputs
5960
60-
- The argument to `import` is a comma-separated list of `<file[:primary]>` entries.
61-
- If you use self-signed certificates, add `--insecure`.
61+
| Input | Description | Type | Default |
62+
|-------|-------------|------|---------|
63+
| `microcks_url` | URL of the Microcks instance | string | `$MICROCKS_URL` |
64+
| `keycloak_client_id` | Keycloak client ID for authentication | string | `$KEYCLOAK_CLIENT_ID` |
65+
| `keycloak_client_secret` | Keycloak client secret for authentication | string | `$KEYCLOAK_CLIENT_SECRET` |
66+
| `specs` | Specification files to import (format: 'file1:mainArtifact,file2:mainArtifact') | string | `specs/weather-forecast-openapi.yml:true,specs/weather-forecast-postman.json:false` |
67+
| `stage` | CI/CD stage for the import job | string | `import` |
68+
| `image` | Docker image to use for the import job | string | `quay.io/microcks/microcks-cli:latest` |
6269

63-
## 3. Test job (run contract tests)
70+
Note:
71+
By default, the component `gitlab.com/microcks-cncf/microcks-community/microcks-gitlab-components/microcks-import@~latest` uses the latest released component version. You can use a specific version by specifying it in the component reference. For example to use the component version 0.0.1 use the following component reference:
72+
```
73+
include:
74+
- component: gitlab.com/microcks-cncf/microcks-community/microcks-gitlab-components/microcks-import@0.0.1
75+
```
6476

65-
Run a contract test against your deployed API endpoint with one of the supported runners (`HTTP`, `SOAP`, `SOAP_UI`, `POSTMAN`, `OPEN_API_SCHEMA`, `ASYNC_API_SCHEMA`).
77+
## 3. Running Conformance Tests
78+
79+
Run a contract test against your deployed API endpoint with one of the supported runners (`HTTP`, `SOAP`, `SOAP_UI`, `POSTMAN`, `OPEN_API_SCHEMA`, `ASYNC_API_SCHEMA`) by using `microcks-test` component
6680

6781
```yaml
6882
# .gitlab-ci.yml (excerpt)
83+
include:
84+
- component: gitlab.com/microcks-cncf/microcks-community/microcks-gitlab-components/microcks-test@~latest
85+
inputs:
86+
api_name_version: "My API:1.0.0"
87+
test_endpoint: "https://my-api.example.com"
88+
test_runner: "OPEN_API_SCHEMA"
89+
microcks_url: "https://microcks.apps.acme.com/api/"
90+
keycloak_client_id: $KEYCLOAK_CLIENT_ID
91+
keycloak_client_secret: $KEYCLOAK_CLIENT_SECRET
92+
stage: test
93+
image: "quay.io/microcks/microcks-cli:latest"
94+
6995
stages:
7096
- test
71-
72-
test-api-contract:
73-
stage: test
74-
image: quay.io/microcks/microcks-cli:latest
75-
variables:
76-
MICROCKS_URL: "$MICROCKS_URL"
77-
KEYCLOAK_CLIENT_ID: "$KEYCLOAK_CLIENT_ID"
78-
KEYCLOAK_CLIENT_SECRET: "$KEYCLOAK_CLIENT_SECRET"
79-
script:
80-
- |
81-
microcks-cli test \
82-
'API Pastry - 2.0:2.0.0' \
83-
'https://my-api-pastry.apps.example.com' \
84-
OPEN_API_SCHEMA \
85-
--microcksURL="$MICROCKS_URL" \
86-
--keycloakClientId="$KEYCLOAK_CLIENT_ID" \
87-
--keycloakClientSecret="$KEYCLOAK_CLIENT_SECRET" \
88-
--waitFor=10sec
8997
```
9098

91-
Notes:
92-
93-
- The first three arguments are: `<apiName:apiVersion>` `<testEndpoint>` `<runner>`.
94-
- `--waitFor` lets the job wait for test completion up to the specified duration.
95-
- Add `--insecure` if your Microcks endpoint uses self-signed certificates.
96-
97-
## 4. End-to-end example pipeline
98-
99-
Below is a minimal pipeline with two stages: import artifacts and test the deployed API. Adapt the `only/except` or `rules` to your workflow.
100-
101-
```yaml
102-
# .gitlab-ci.yml
103-
stages: [import, test]
104-
105-
variables:
106-
# Prefer defining these at project/group level in Settings → CI/CD → Variables
107-
MICROCKS_URL: "$MICROCKS_URL"
108-
KEYCLOAK_CLIENT_ID: "$KEYCLOAK_CLIENT_ID"
109-
KEYCLOAK_CLIENT_SECRET: "$KEYCLOAK_CLIENT_SECRET"
110-
111-
import-specs:
112-
stage: import
113-
image: quay.io/microcks/microcks-cli:latest
114-
script:
115-
- microcks-cli version
116-
- |
117-
microcks-cli import \
118-
'specs/weather-forecast-openapi.yml:true,specs/weather-forecast-postman.json:false' \
119-
--microcksURL="$MICROCKS_URL" \
120-
--keycloakClientId="$KEYCLOAK_CLIENT_ID" \
121-
--keycloakClientSecret="$KEYCLOAK_CLIENT_SECRET"
122-
rules:
123-
- if: $CI_COMMIT_BRANCH
124-
125-
test-api-contract:
126-
stage: test
127-
image: quay.io/microcks/microcks-cli:latest
128-
needs: ["import-specs"]
129-
script:
130-
- |
131-
microcks-cli test \
132-
'API Pastry - 2.0:2.0.0' \
133-
'https://my-api-pastry.apps.example.com' \
134-
OPEN_API_SCHEMA \
135-
--microcksURL="$MICROCKS_URL" \
136-
--keycloakClientId="$KEYCLOAK_CLIENT_ID" \
137-
--keycloakClientSecret="$KEYCLOAK_CLIENT_SECRET" \
138-
--waitFor=10sec
139-
rules:
140-
- if: $CI_COMMIT_BRANCH
99+
## Inputs
100+
101+
| Input | Description | Type | Default |
102+
|-------|-------------|------|---------|
103+
| `microcks_url` | URL of the Microcks instance | string | `$MICROCKS_URL` |
104+
| `keycloak_client_id` | Keycloak client ID for authentication | string | `$KEYCLOAK_CLIENT_ID` |
105+
| `keycloak_client_secret` | Keycloak client secret for authentication | string | `$KEYCLOAK_CLIENT_SECRET` |
106+
| `api_name_version` | API name and version to test (format: 'API Name:version') | string | `API Pastry - 2.0:2.0.0` |
107+
| `test_endpoint` | Endpoint URL to test against | string | `https://my-api-pastry.apps.example.com` |
108+
| `test_runner` | Test runner to use | string | `OPEN_API_SCHEMA` |
109+
| `wait_for` | Time to wait for test completion | string | `10sec` |
110+
| `stage` | CI/CD stage for the test job | string | `test` |
111+
| `image` | Docker image to use for the test job | string | `quay.io/microcks/microcks-cli:latest` |
112+
113+
Note:
114+
By default, the component `gitlab.com/microcks-cncf/microcks-community/microcks-gitlab-components/microcks-test@~latest` uses the latest released component version. You can use a specific version by specifying it in the component reference. For example to use the component version 0.0.1 use the following component reference:
115+
```
116+
include:
117+
- component: gitlab.com/microcks-cncf/microcks-community/microcks-gitlab-components/microcks-test@0.0.1
141118
```
142119

143120
## Wrap-up
144121

145-
You have learned how to use the `microcks-cli` inside GitLab CI to import API artifacts and run contract tests. The CLI reuses the same authentication foundation described in the [Automation API guide](/documentation/guides/automation/api) and relies on a [Service Account](/documentation/explanations/service-account). For CLI flags and options, check the [Microcks CLI](/documentation/guides/automation/cli) guide and the tool's README.
146-
147-
If you prefer a native CI integration, see also the guides for [GitHub Actions](/documentation/guides/automation/github-actions) and [Jenkins](/documentation/guides/automation/jenkins).
122+
You have learned how to use the Microcks GitLab Components to import API artifacts and run conformance tests directly from the GitLab CI/CD Catalog. The components provide a reusable and versioned integration that simplifies your pipeline configuration. Behind the scenes, they leverage the `microcks-cli` and use the same authentication foundation described in the [Automation API guide](/documentation/guides/automation/api), relying on a [Service Account](/documentation/explanations/service-account). For the most up-to-date information and available versions, check the [GitLab CI/CD Catalog](https://gitlab.com/explore/catalog/microcks-cncf/microcks-community/microcks-gitlab-components).

0 commit comments

Comments
 (0)