From 785dd3919606b224ea8a556feba1430261836753 Mon Sep 17 00:00:00 2001
From: Michal Konečný <mkonecny@redhat.com>
Date: Nov 29 2022 10:26:59 +0000
Subject: Add API key information to Jenkins CI setup


When migrating old Pagure Jenkins instance to new one I found out that
information about API key is missing in Pagure CI - Jenkins guide. So here it is
with example function that could be used by any project.

Signed-off-by: Michal Konečný <mkonecny@redhat.com>

---

diff --git a/doc/usage/pagure_ci_jenkins.rst b/doc/usage/pagure_ci_jenkins.rst
index bacfc23..629b1b7 100644
--- a/doc/usage/pagure_ci_jenkins.rst
+++ b/doc/usage/pagure_ci_jenkins.rst
@@ -121,3 +121,28 @@ Example Script
     fi
 
     # Part of the script specific to how you run the tests on your project
+
+* To use the URL to POST results you need to add API key to Jenkins instance.
+  This API key needs to have `Update an issue, status, comments, custom fields...`
+  ACL. In Jenkins add it in `Manage Jenkins` -> `Manage Credentials` -> `Stores scoped to Jenkins`
+  -> `Jenkins` -> `Global credentials (unrestricted)` -> `Add Credentials` as kind
+  `Secret text` (ID will be used in script).
+
+Example function used in Jenkins pipeline script
+
+::
+
+   # 'pagure-auth' is the ID of the credentials
+
+   def notifyPagurePR(repo, msg, status, phase, credentials = 'pagure-auth'){
+       def json = JsonOutput.toJson([name: 'pagure', url: env.JOB_NAME, build: [full_url: currentBuild.absoluteUrl, status: status, number: currentBuild.number, phase: phase]])
+       println json
+
+       withCredentials([string(credentialsId: credentials, variable: "PAGURE_PUSH_SECRET")]) {
+           /* We need to notify pagure that jenkins finished but then pagure will
+             wait for jenkins to be done, so if we wait for pagure's answer we're
+             basically stuck in a loop where both jenkins and pagure are waiting
+             for each other */
+           sh "timeout 1 curl -X POST -d \'$json\' https://pagure.io/api/0/ci/jenkins/$repo/\${PAGURE_PUSH_SECRET}/build-finished -H \"Content-Type: application/json\" | true"
+       }
+   }