You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: "How to developing and test your GitHub Apps with faasd"
3
-
description: "In this guide, we are going to demonstrate how to build our GitHub App and run it locally on our faasd instance then expose it to the internet using inlets to be able to Github can send events to it"
4
-
tags: inlets-pro inletsctl go github-application faasd rasperry-pi caddy tls
2
+
title: "You're doing it wrong. Integrate with GitHub the right way GitHub Apps"
3
+
description: "In this guide, we are going to demonstrate how to build your own GitHub App to get a fine-grained integration with GitHub's API and to act on the behalf of its users."
4
+
tags: inlets-pro inletsctl go github-application faasd raspberry-pi
How to build our GitHub App and run it locally on our faasd instance then expose it to the internet using inlets to be able to Github can send events to it
12
+
In this guide, we are going to demonstrate how to build your own GitHub App to get a fine-grained integration with GitHub's API and to act on the behalf of its users
14
13
15
14
# Introduction
16
15
17
-
In this guide, we are going to develop a [GitHub App](https://docs.github.com/en/free-pro-team@latest/developers/apps) using Go, then we deploy it as a serverless function to make use of [faasd](https://github.com/openfaas/faasd) which is a lightweight & portable faas engine.We are also going to do this demo on our local environment, so we should open our function which runs on our local environment to the Internet so Github can send events to our function. In order to do that we use inlets-pro which provides secure TCP/L4 tunnels.
16
+
With [28 million developers on the platform and 85 million repositories](https://www.theverge.com/2018/6/18/17474284/microsoft-github-acquisition-developer-reaction), integrating with GitHub is not just fun, it's essential. Some companies have even built integrations so good, [that GitHub bought them](https://techcrunch.com/2019/09/18/github-acquires-code-analysis-tool-semmle/) and made them part of the core platform. This has happened multiple times.
17
+
18
+
So why is it that so many of you are doing it wrong? Many of you are still using OAuth apps which are considered legacy and have scopes which are far too broad. Many more of you are taking extreme risks by using Personal Access Tokens (PATs), most of which can do anything to your account and repositories.
19
+
20
+
> GitHub Apps are first-class actors within GitHub and unlike the legacy OAuth apps, allow or fine-grained actions to be performed on your user's repositories.
21
+
22
+
In this guide, we are going to develop a [GitHub App](https://docs.github.com/en/free-pro-team@latest/developers/apps) using Go, then we deploy it as a serverless function to make use of [faasd](https://github.com/openfaas/faasd) which is a lightweight & portable faas engine. We are also going to do this demo on our local environment, so we should open our function which runs on our local environment to the Internet so Github can send events to our function. In order to do that we use inlets-pro which provides secure TCP/L4 tunnels.
23
+
24
+
A GitHub App acts on its own behalf, taking actions via the API directly using its own identity, which means you don't need to maintain a bot or service account as a separate user. GitHub Apps can be installed directly on organizations and user accounts and granted access to specific repositories. They come with built-in webhooks and narrow, specific permissions. When you set up your GitHub App, you can select the repositories you want it to access. For example, in this guide we are going to develop a Github App that respond or close the comments for your repositories that you installed Github App for.
18
25
19
-
GitHub Apps are first-class actors within GitHub. A GitHub App acts on its own behalf, taking actions via the API directly using its own identity, which means you don't need to maintain a bot or service account as a separate user. GitHub Apps can be installed directly on organizations and user accounts and granted access to specific repositories. They come with built-in webhooks and narrow, specific permissions. When you set up your GitHub App, you can select the repositories you want it to access. For example, in this guide we are going to develop a Github App that respond or close the comments for your repositories that you installed Github App for. Also there is a two good examples available on that topic: [Derek](https://github.com/alexellis/derek) and [OpenFaaS Cloud](https://github.com/openfaas/openfaas-cloud).
26
+
Two examples that make thorough use of GitHub Apps are below:
20
27
21
-
Derek is a Github App that reduces fatigue for maintainers by automating governance and delegating permissions to your team and community. It provides the following automations:
22
-
- Generate changelogs for releases with PRs merged and commits added
23
-
- Let designated non-admin users manage Issues and PRs by commenting Derek <command> or /command
24
-
- Enforce Developer Certificate of Origin (DCO) checking (optional)
Derek is a GitHub bot that reduces fatigue for maintainers by automating governance and delegating permissions to your team and community. It provides the following automation:
32
+
33
+
- Generate changelogs for releases with PRs merged and commits added, crediting everyone invokved
34
+
- Let designated non-admin users manage Issues and PRs by commenting `Derek <command>` or `/command`
35
+
- Enforce [Developer Certificate of Origin (DCO)](https://developercertificate.org/) checking (optional)
25
36
- Automatically label/flag PRs without a Description
26
37
27
-
OpenFaaS Cloud is designed as Multi-user OpenFaaS Platform. With OpenFaaS Cloud functions are managed through typing git push which reduces the tooling and learning curve required to operate functions for your team. As soon as OpenFaaS Cloud receives a push event from git it will run through a build-workflow which clones your repo, builds a Docker image, pushes it to a registry and then deploys your functions to your cluster. Each user can access and monitor their functions through their personal dashboard.
38
+
OpenFaaS Cloud is designed as Multi-user version of OpenFaaS with CI/CD built in and a new dashboard. It is aimed at platform engineers who want to give functions to their team, whilst shielding them from Kubernetes at the same time.
39
+
40
+
With OpenFaaS Cloud functions are managed through typing `git push` which reduces the tooling and learning curve required to operate functions for your team. As soon as OpenFaaS Cloud receives a push event from git it will run through a build-workflow which clones your repo, builds a Docker image, pushes it to a registry and then deploys your functions to your cluster. Each user can access and monitor their functions through their personal dashboard.
28
41
29
42
## Pre-requisites
30
43
31
44
* DigitalOcean Account - We are going to use DigitalOcean as a provider to host our exit-node.
32
-
* arkade - arkade provides a portable marketplace for downloading your favourite devops CLIs and installing helm charts, with a single command.
45
+
*[arkade](https://get-arkade.dev) - arkade provides a portable marketplace for downloading your favourite devops CLIs and installing helm charts, with a single command.
33
46
* inletsctl - inletsctl automates the task of creating an exit-node on cloud infrastructure.
34
47
* inlets-pro - You can use inlets-pro to tunnel out any TCP traffic from an internal network to another network.
35
48
* multipass - Multipass provides a command line interface to launch, manage and generally fiddle about with instances of Linux.
36
49
* faas-cli - This is a CLI for use with OpenFaaS - a serverless functions framework for Docker & Kubernetes.
37
50
38
51
Now we are ready to go 🚀
39
52
40
-
## Setup exit-node server on DigitalOcean
53
+
## Setup your exit-node server on DigitalOcean
54
+
41
55
For this tutorial you will need to have an account and API key with one of the [supported providers](https://github.com/inlets/inletsctl#featuresbacklog), or you can create an exit-server manually and install inlets PRO there yourself.
42
56
43
57
For this tutorial, the DigitalOcean provider will be used. You can get [free credits on DigitalOcean with this link](https://m.do.co/c/8d4e75e9886f).
@@ -68,13 +82,17 @@ $ inletsctl create \
68
82
--pro
69
83
```
70
84
85
+
You can also change the region flag to a DigitalOcean region close to your network
86
+
87
+
> See [the docs for inletsctl](https://docs.inlets.dev/#/tools/inletsctl?id=inletsctl-reference-documentation) for examples of how to use other providers like AWS EC2, Azure and GCP.
88
+
71
89
If everything goes well, you should see your newly created "exit-node" on the homepage of your the DigitalOcean account like the following:
> If you curious about what the "exit-node or exit-server" is, you can follow a link in the inlets documentation [here](https://docs.inlets.dev/#/?id=exit-servers).
76
94
77
-
## Setting up a new GitHub App
95
+
## Create the new GitHub App on GitHub
78
96
79
97
To register a new app, visit the app settings page in your GitHub profile, and click New GitHub App.
80
98
@@ -106,7 +124,8 @@ In order to get up and running with your own faasd installation on your Mac you
106
124
Let's start our Ubuntu VM with multipass.First, we need a cloud-config.txt to set up faasd while bootstrapping VM.
> Note: `multipass launch` can be configured with more CPUs, RAM and additional disk capacity, just run `--help` to see how.
148
+
149
+
Check the VM if it is working properly:
127
150
128
151
```bash
129
-
$ multipas list
152
+
$ multipass list
130
153
Name State IPv4 Image
131
154
faasd Running 192.168.64.25 Ubuntu 20.04 LTS
132
155
```
133
156
134
-
## Build and Deploy function
135
-
For this demo, we are going to use golang to develop our GitHub App, in order to do that, first, we need to pull the corresponding function template for the golang.
157
+
You can connect to the VM through SSH or via `multipass exec faasd`.
158
+
159
+
To get the IP address simply run `multipass info faasd`:
160
+
161
+
```bash
162
+
$ multipass info faasd
163
+
Name: faasd
164
+
State: Running
165
+
IPv4: 192.168.64.25
166
+
Release: Ubuntu 20.04.1 LTS
167
+
Image hash: d68d50a4067d (Ubuntu 20.04 LTS)
168
+
Load: 0.68 1.09 0.54
169
+
Disk usage: 1.9G out of 4.7G
170
+
Memory usage: 259.8M out of 981.4M
171
+
```
172
+
173
+
## Build and deploy a webhook receiver function
174
+
175
+
For this demo, we are going to use Golang to develop a function that responds to any webhooks sent to us from the GitHub App.
176
+
177
+
In order to do that, first, we need to pull the corresponding function template for the Golang.
136
178
137
179
We need to install "faas-cli" tool for that but we need to install arkade first because arkade is the marketplace for our favourite devops CLIs.
We can now find the Golang template we want and continue to create our function.
150
192
151
193
```bash
152
194
# let's look at the available Go function templates within the OpenFaaS store
@@ -160,10 +202,11 @@ $ faas-cli template store pull golang-middleware
160
202
$ faas-cli new issues-bot --lang golang-middleware --prefix <DOCKER_HUB_ID>
161
203
```
162
204
163
-
You can find all the code details in the [GitHub repository](https://github.com/developer-guy/faasd-github-bot).
205
+
You can find all the code details in my GitHub repository: [developer-guy/faasd-github-bot](https://github.com/developer-guy/faasd-github-bot).
206
+
207
+
After you've created the function, you need to define a build-arg to use Go modules, an environment variable for the GitHub App ID (found in the GitHub UI) and a secret for the the webhook secret (for verifying genuine payloads) and the private key (for acting on the behalf of a user).
164
208
165
-
After created the function, we need to define some arguments, environments and secrets for the function.
166
-
Let's add them:
209
+
Let's add them to the YAML file created by `faas-cli new`:
167
210
168
211
```yaml
169
212
build_args:
@@ -172,44 +215,38 @@ Let's add them:
172
215
- webhook-secret # your secret goes here
173
216
- private-key-secret # your private key goes here
174
217
environment:
175
-
APP_ID: ""#your app id goes here
218
+
APP_ID: ""#your app id goes here
176
219
```
177
220
178
-
Finally, we need to create those secrets above with make use of faas-cli.
221
+
Next we need to create the above two secrets.
179
222
180
-
Let's create our secrets.
223
+
Download the private key for the GitHub app to your host using the GitHub UI.
We should create a secret in faasd, in order to do that we need to access the Gateway of faasd.
231
+
Now it's time to authenticate `faas-cli` so that we can do a deployment to our faasd instance from our laptop. This would work the same if you were deploying faasd to a cloud instance.
Now that you can develop first-class integrations with GitHub, with fine-grained permissions and do things the right way. OAuth works are very broadly defined and personal access tokens (PATs) are just the wrong tool for the job and very risky if someone were to find it.
294
+
295
+
Each user that installs your app is called an installation and has their own API limit of 1000 calls per hour.
296
+
297
+
So what will you build?
298
+
299
+
You could develop a bot, an integration, a linter as a service, integrate a machine-learning model from the OpenFaaS function store, and a whole host of other things. It's up to you to decide.
300
+
301
+
Do you already have a preferred way to deploy and run HTTP servers which isn't faasd? We're OK with that and want you to know that what you learned here about inlets and GitHub Apps can apply whether you run with a Docker container or just deploy a binary directly to a server.
302
+
303
+
### Want to learn more about use-cases and faasd?
248
304
249
-
* Special Thanks to [Alex Ellis](https://twitter.com/alexellisuk) for all guidance and for merging changes into OpenFaaS to better support this workflow.
250
-
* Special Thanks to [Furkan Türkal](https://twitter.com/furkanturkaI) for all the support.
251
-
* Special Thanks to [Kumar Utsav Anand](https://twitter.com/Utsav2Anand) for all the support.
305
+
There is a new eBook and video workshop from Alex, the founder of OpenFaaS and faasd.
306
+
307
+
<blockquote class="twitter-tweet"><p lang="en" dir="ltr">I've just published: "Serverless for Everyone Else" on <a href="https://twitter.com/gumroad?ref_src=twsrc%5Etfw">@gumroad</a> <br><br>Automate your workflow with the official guide to faasd - a minimalist's approach to severless functions.<a href="https://twitter.com/hashtag/serverless?src=hash&ref_src=twsrc%5Etfw">#serverless</a> <a href="https://twitter.com/hashtag/faas?src=hash&ref_src=twsrc%5Etfw">#faas</a> <a href="https://twitter.com/hashtag/ebook?src=hash&ref_src=twsrc%5Etfw">#ebook</a> <a href="https://twitter.com/hashtag/learn?src=hash&ref_src=twsrc%5Etfw">#learn</a> <a href="https://twitter.com/hashtag/nodejs?src=hash&ref_src=twsrc%5Etfw">#nodejs</a> <a href="https://t.co/hGCbV8OTEj">https://t.co/hGCbV8OTEj</a></p>— Alex Ellis (@alexellisuk) <a href="https://twitter.com/alexellisuk/status/1350079792612339715?ref_src=twsrc%5Etfw">January 15, 2021</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
308
+
309
+
If you get a copy before the end of January on the DevOps PRO tier, you'll get the eBook, a Grafana dashboard and a free upgrade to the 50 minute video workshop.
0 commit comments