#822 Feeding information into Ontrack

ontrack-docs/src/docs/asciidoc/api.adoc

@@ -1,2 +1,5 @@
 [[api]]
 == Ontrack API
+
+[[api-graphql]]
+=== Ontrack GraphQL API

ontrack-docs/src/docs/asciidoc/feeding-api.adoc

@@ -0,0 +1,32 @@
+[[feeding-api]]
+=== Using the API
+
+Ontrack provides a <<api-graphql,GraphQL API>> 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 <<api-graphql>> for a complete information.

ontrack-docs/src/docs/asciidoc/feeding-cli.adoc

@@ -0,0 +1,16 @@
+[[feeding-cli]]
+=== Ontrack CLI
+
+Instead of using the <<feeding-api,API>> 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.

ontrack-docs/src/docs/asciidoc/feeding-github.adoc

@@ -0,0 +1,44 @@
+[[feeding-github]]
+=== GitHub actions
+
+You can easily use the <<feeding-cli,Ontrack CLI>> 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: <ontrack-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 <<feedback-cli,Ontrack CLI>> 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 ...
+----

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-library,Ontrack Jenkins pipeline library>>.
+
+[[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 <<feeding-jenkins-library,Ontrack Jenkins pipeline library>> described below.
+====
+
+[[feeding-jenkins-library]]
+==== Jenkins pipeline library
+
+The Ontrack Jenkins pipeline library wraps the <<feeding-cli,Ontrack CLI>> into convenient pipeline steps.
+
+[NOTE]
+====
+To be implemented. As much as possible, the pipeline library will mimic the steps which were provided by the <<feeding-jenkins-plugin,Jenkins plug-in>>.
+====
+
+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,
+                    )
+                }
+            }
+        }
+    }
+}
+----

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 <<integrations>> chapter.
+
+Ontrack provides an <<feeding-api,API>> for tools to inject data, but more specialized integrations are provided as well:
+
+* the <<feeding-cli,Ontrack CLI>>
+* the <<feeding-jenkins,Ontrack Jenkins plug-in>>
+* a set of <<feeding-github,Ontrack GitHub actions>>
+
+include::feeding-api.adoc[]
+
+include::feeding-cli.adoc[]
+
+include::feeding-jenkins.adoc[]
+
+include::feeding-github.adoc[]

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[]

ontrack-docs/src/docs/asciidoc/integration.adoc → ontrack-docs/src/docs/asciidoc/integrations.adoc

@@ -1,5 +1,5 @@
-[[integration]]
-== Integration
+[[integrations]]
+== Integrations
 
 include::integration-elasticsearch.adoc[]