GitHub app blog

content/blog/2020/04/2020-04-16-github-app-authentication.adoc

@@ -0,0 +1,90 @@
+---
+layout: post
+title: "GitHub app authentication released"
+tags:
+- github
+- github-branch-source
+author: timja
+---
+
+I'm excited to announce support for authenticating as a GitHub app in Jenkins.
+
+It has been released in link:https://github.com/jenkinsci/github-branch-source-plugin/releases/tag/github-branch-source-2.7.0-beta1[GitHub Branch Source 2.7.0-beta1]. This has been a long awaited feature by many users.
+
+ Authenticating as a GitHub app brings many benefits:
+
+* **Larger rate limits** - The rate limit for a GitHub app scales with your organization size, 
+whereas a user based token has a limit of 5000 regardless of how many repositories you have.
+
+* ** User-independent authentication** - Each GitHub app has its own user-independent authentication. No more need for 'bot' users or figuring out who should be the owner of 2FA or OAuth tokens.
+
+* **Improved security and tighter permissions** - GitHub Apps offers much finer-grained permissions compared to a service user and its personal access tokens. This lets the Jenkins GitHub app require a much smaller set of privileges to run properly.
+
+* **Access to GitHub Checks API** - GitHub Apps can access the the  link:https://developer.github.com/v3/checks/[GitHub Checks API] to create check runs and check suites from Jenkins jobs and provide detailed feedback on commits as well as code annotation
+
+== Getting started
+
+Install the link:https://plugins.jenkins.io/github-branch-source/[GitHub Branch Source plugin],
+make sure the version is at least 2.7.0-beta1. 
+Then follow the link:https://github.com/jenkinsci/github-branch-source-plugin/blob/master/docs/github-app.adoc[setup guide].  These instructions are also linked from the plugin’s README on GitHub.
+
+Once you've finished setting it up, Jenkins will validate your credential and you should see your new rate limit.
+Here's an example on a large org:
+
+image:/images/github-app-rate-limit.png[GitHub app rate limit]
+
+== How do I get an API token in my pipeline?
+
+You can access the Bearer token for the GitHub API by just loading a 'Username/Password' credential as usual,
+the plugin will handle authenticating with GitHub in the background.
+
+This could be used to call additional GitHub API endpoints from your pipeline, possibly the
+link:https://developer.github.com/v3/repos/deployments/[deployments api] or you may wish to implement your own
+links:https://developer.github.com/v3/checks/[checks api] integration until Jenkins supports this out of the box.
+
+_Note: the api token you get will only be valid for one hour, don't get it at the start of the pipeline and assume it will be valid all the way through_
+
+[source, groovy]
+----
+
+pipeline {
+  agent any
+
+  stages{
+    stage('Check run') { 
+      steps {
+        withCredentials([usernamePassword(credentialsId: 'githubapp-jenkins',
+                                          usernameVariable: 'GITHUB_APP',
+                                          passwordVariable: 'GITHUB_JWT_TOKEN')]) {
+            sh '''
+            curl -H "Content-Type: application/json" \
+                 -H "Accept: application/vnd.github.antiope-preview+json" \
+                 -H "authorization: Bearer ${GITHUB_JWT_TOKEN}" \
+                 -d '{ "name": "check_run", \
+                       "head_sha": "'${GIT_COMMIT}'", \
+                       "status": "in_progress", \
+                       "external_id": "42", \
+                       "started_at": "2020-03-05T11:14:52Z", \
+                       "output": { "title": "Check run from Jenkins!", \
+                                   "summary": "This is a check run which has been generated from Jenkins as GitHub App", \
+                                   "text": "...and that is awesome"}}' https://api.github.com/repos/<org>/<repo>/check-runs
+            '''
+        }
+      }
+    }
+  }
+}
+
+
+----
+
+== What's next
+
+GitHub Apps authentication in Jenkins is a huge improvement.  Many teams have already started using it and have helped improve it by giving pre-release feedback. There are more improvements on the way. 
+
+There's a proposed Google Summer of Code project: link:https://jenkins.io/projects/gsoc/2020/project-ideas/github-checks/[GitHub Checks API for Jenkins Plugins].  
+It will look at integrating with the link:https://developer.github.com/v3/checks/[checks api], 
+with a focus on reporting issues found using the link:https://plugins.jenkins.io/warnings-ng/[warnings-ng plugin]
+directly onto the GitHub pull requests, along with test results summary on GitHub.
+If you want to get involved with this, join the link:https://gitter.im/jenkinsci/gsoc-sig[gitter channel]
+and ask how you can help.