diff --git a/ontrack-docs/src/docs/asciidoc/api.adoc b/ontrack-docs/src/docs/asciidoc/api.adoc index 514d6207173..44c99a7ce21 100644 --- a/ontrack-docs/src/docs/asciidoc/api.adoc +++ b/ontrack-docs/src/docs/asciidoc/api.adoc @@ -1,2 +1,5 @@ [[api]] == Ontrack API + +[[api-graphql]] +=== Ontrack GraphQL API diff --git a/ontrack-docs/src/docs/asciidoc/feeding-api.adoc b/ontrack-docs/src/docs/asciidoc/feeding-api.adoc new file mode 100644 index 00000000000..19d78cfbd45 --- /dev/null +++ b/ontrack-docs/src/docs/asciidoc/feeding-api.adoc @@ -0,0 +1,32 @@ +[[feeding-api]] +=== Using the API + +Ontrack provides a <> to interact with it: + +* queries to get information from Ontrack +* mutations to inject information from Ontrack + +Example: to create a new build for an existing project & branch: + +[source,graphql] +---- +mutation { + createBuild(input: { + projectName: "my-project", + branchName: "my-branch", + name: "1234", + runInfo: { + runTime: 12 + } + }) { + build { + id + } + errors { + message + } + } +} +---- + +See <> for a complete information. diff --git a/ontrack-docs/src/docs/asciidoc/feeding-cli.adoc b/ontrack-docs/src/docs/asciidoc/feeding-cli.adoc new file mode 100644 index 00000000000..216f462d7c3 --- /dev/null +++ b/ontrack-docs/src/docs/asciidoc/feeding-cli.adoc @@ -0,0 +1,16 @@ +[[feeding-cli]] +=== Ontrack CLI + +Instead of using the <> directly, you can use the https://github.com/nemerosa/ontrack-cli[Ontrack CLI], a multi-platform client which wraps the API calls into convenient commands. + +For example, to create a new build for an existing project & branch: + +[source,bash] +---- +ontrack-cli build setup \ + --project my-project \ + --branch my-branch \ + --build 1234 +---- + +See the https://github.com/nemerosa/ontrack-cli[Ontrack CLI] documentation for more information about the installation, configuration & usage of this client. diff --git a/ontrack-docs/src/docs/asciidoc/feeding-github.adoc b/ontrack-docs/src/docs/asciidoc/feeding-github.adoc new file mode 100644 index 00000000000..59421bd9345 --- /dev/null +++ b/ontrack-docs/src/docs/asciidoc/feeding-github.adoc @@ -0,0 +1,44 @@ +[[feeding-github]] +=== GitHub actions + +You can easily use the <> from your GitHub workflows by using the following actions: + +* https://github.com/nemerosa/ontrack-github-actions-cli-setup[`nemerosa/ontrack-github-actions-cli-setup`] - install, configures and use the CLI to setup a project and branch in Ontrack based on GitHub information: + +[source,yaml] +---- +- name: Setup the CLI + uses: nemerosa/ontrack-github-actions-cli-setup@v1 + with: + github-token: ${{ github.token }} + only-for: nemerosa + url: + token: ${{ secrets.ONTRACK_TOKEN }} + config: github.com + indexation: 120 +---- + +* https://github.com/nemerosa/ontrack-github-actions-cli-validation[`nemerosa/ontrack-github-actions-cli-validation`] - creates a validation run for a build based on GitHub information: + +[source,yaml] +---- +- name: Ontrack build validation + uses: nemerosa/ontrack-github-actions-cli-validation@main + with: + step-name: Ontrack build + validation: BUILD + build: ${{ github.run_number }} + token: ${{ github.token }} +---- + +Note that when https://github.com/nemerosa/ontrack-github-actions-cli-setup[`nemerosa/ontrack-github-actions-cli-setup`] has been called into your workflow job, the <> becomes available in all subsequent steps and be used directly: + +[source,yaml] +---- +- name: Setup the CLI + uses: nemerosa/ontrack-github-actions-cli-setup@v1 + with: + # ... +- name: Using the CLI + run: ontrack-cli ... +---- diff --git a/ontrack-docs/src/docs/asciidoc/feeding-jenkins.adoc b/ontrack-docs/src/docs/asciidoc/feeding-jenkins.adoc new file mode 100644 index 00000000000..e8f36b735a0 --- /dev/null +++ b/ontrack-docs/src/docs/asciidoc/feeding-jenkins.adoc @@ -0,0 +1,72 @@ +[[feeding-jenkins]] +=== Jenkins plug-in + +If you're using https://jenkins.io[Jenkins] as a CI engine, you can either use the https://github.com/jenkinsci/ontrack-plugin[Ontrack Jenkins plug-in] or the <>. + +[[feeding-jenkins-plugin]] +==== Jenkins plug-in + +The https://github.com/jenkinsci/ontrack-plugin[Ontrack Jenkins plug-in] relies on API to inject data into Ontrack. + +For example, to create a build: + +[source,groovy] +---- +pipeline { + stages { + stage('Build') { + // ... + // Computes the `version` variable + // ... + post { + success { + ontrackBuild( + project: 'my-project', + branch: 'my-branch', + build: version, + ) + } + } + } + } +} +---- + +[WARNING] +==== +The https://github.com/jenkinsci/ontrack-plugin[Ontrack Jenkins plug-in] will be deprecated at some point, in favor of using the <> described below. +==== + +[[feeding-jenkins-library]] +==== Jenkins pipeline library + +The Ontrack Jenkins pipeline library wraps the <> into convenient pipeline steps. + +[NOTE] +==== +To be implemented. As much as possible, the pipeline library will mimic the steps which were provided by the <>. +==== + +For example, to create a build: + +[source,groovy] +---- +pipeline { + stages { + stage('Build') { + // ... + // Computes the `version` variable + // ... + post { + success { + ontrackBuild( + project: 'my-project', + branch: 'my-branch', + build: version, + ) + } + } + } + } +} +---- diff --git a/ontrack-docs/src/docs/asciidoc/feeding.adoc b/ontrack-docs/src/docs/asciidoc/feeding.adoc index 4e926795ade..d98ad447779 100644 --- a/ontrack-docs/src/docs/asciidoc/feeding.adoc +++ b/ontrack-docs/src/docs/asciidoc/feeding.adoc @@ -1,2 +1,22 @@ [[feeding]] == Feeding information in Ontrack + +Ontrack gathers and structures information which is sent by other tools in a CI/CD ecosystem or collected from them. + +Foremost among the tools which will feed information into Ontrack are the CI engines. They can initialize projects and branches, they can create builds, validations and promotions, they can inject meta-information like timings, test results or links between builds. + +NOTE: Ontrack gathers also information out of ticketing systems, artifact managers or source control systems. This aspect is covered in the <> chapter. + +Ontrack provides an <> for tools to inject data, but more specialized integrations are provided as well: + +* the <> +* the <> +* a set of <> + +include::feeding-api.adoc[] + +include::feeding-cli.adoc[] + +include::feeding-jenkins.adoc[] + +include::feeding-github.adoc[] diff --git a/ontrack-docs/src/docs/asciidoc/index.adoc b/ontrack-docs/src/docs/asciidoc/index.adoc index 5912ce25d5f..51ccdbdc1f9 100644 --- a/ontrack-docs/src/docs/asciidoc/index.adoc +++ b/ontrack-docs/src/docs/asciidoc/index.adoc @@ -27,6 +27,8 @@ include::authentication.adoc[] include::feeding.adoc[] +include::integrations.adoc[] + include::usage.adoc[] include::api.adoc[] diff --git a/ontrack-docs/src/docs/asciidoc/integration.adoc b/ontrack-docs/src/docs/asciidoc/integrations.adoc similarity index 90% rename from ontrack-docs/src/docs/asciidoc/integration.adoc rename to ontrack-docs/src/docs/asciidoc/integrations.adoc index 7a9986a0394..6b4b60c3f5b 100644 --- a/ontrack-docs/src/docs/asciidoc/integration.adoc +++ b/ontrack-docs/src/docs/asciidoc/integrations.adoc @@ -1,5 +1,5 @@ -[[integration]] -== Integration +[[integrations]] +== Integrations include::integration-elasticsearch.adoc[]