Triggering runs and tasks manually surely can be a lot of fun, but you would probably expect Geopoiesis to know about new merges to your main branch and start runs accordingly. Also, you will probably want some feedback on your Pull Requests, as already advertised. For this, you will need to set up an integration with your VCS provider using webhooks. At the time of writing this document, only GitHub is supported, with GitLab in the works.

ngrok setup

So far we've been running Geopoiesis on localhost:1983 and it was sufficient. That won't work for webhooks though, since they need to point to a publicly accessible address on the Internet. In order to do that while still testing Geopoiesis on the local machine, we will use ngrok. ngrok allows you to expose a web server running on your local machine to the internet.

First, download the ngrok binary for your OS and install by following the instructions. Next, start your Geopoiesis server in one terminal tab, and in the other use ngrok to set up a tunnel to your local port 1983:

$ ngrok http -subdomain geopoiesis 1983

You may want to replace geopoiesis with something more custom to avoid name clash with some some other Geopoiesis user testing the product.

If all goes well, you should see something like this:

Now you can visit one of the ngrok.io endpoints and see your app:


Actually, not so fast. When we first set up the application configuration, we specified that the hello-world scope is using localhost domain. When the HTTP request hits Geopoiesis, it matches the hostname against the list of scopes to determine which scope to serve. Upon finding none, it returns a 404. In order to fix it, we will need to change the domain setting in our config.hcl file to point to our new ngrok endpoint. After doing that, restart the Geopoiesis server and visit your ngrok endpoint again - now you should see your app up and running.

Webhook setup

Once your app is accessible on a public address, navigate to the project you've set up you Geopoiesis for in the Source setup step. In GitHub, go to Settings > Webhooks and click the Add webhook button. You will see a form like this:

As payload URL you are going to use the public endpoint for your app. Expected content type is application/json, and the secret is the random string you generated when setting up source. Geopoiesis only works with push events, so no need to send it anything more. Once you're ready, you can click the Add webhook button.

Now when you push a new commit to the branch tracked by your Geopoiesis scope, Geopoiesis will start a run which looks exactly the same as the one you triggered manually two steps before.

Commit status

Following the main branch and automatically starting runs is a neat trick, but where Geopoiesis brings even more value is when it provides feedback on Pull Requests. The webhook you've set up in the previous step is all you really need to use this functionality. In order to see it in action, create a new branch in your local repository checkout, make a small change and push it to GitHub. If both your ngrok endpoint and your local Geopoiesis server are up, you should see a commit status on your Pull Request:

When you click on the Details link next to the Geopoiesis commit status, you will be redirected to the Geopoiesis run associated with that commit. It allows you to preview changes (if any) that the change would cause to your Terraform state.

Retrying commit runs

One thing worth noting is that any finished non-tracked commit run can be retried, whether it is successful or failed. It is useful in two cases. First, when a failure was caused by misconfiguration - for example when a new feature requires an extra environment variable. Second, when you want to run the check against a new state snapshot. In either case it's as easy as just pressing the RETRY button in your run view:

Commit state diagram

Commits to a non-tracked branch follow very similar state transitions to the tracked ones, with two notable exceptions. First, there is no BLOCKED state. Non-tracked commits do not modify or even refresh the Terraform state, so they can run concurrently. Second, there is no confirmation and apply phase. Instead, a successfully executed non-tracked commit run only reports whether applying it would or would not cause changes to the Terraform state.

Each of the above state corresponds to a different GitHub commit status state. Geopoiesis WAITING, PLAN INITIALIZING and PLANNING all map to a pending GitHub state, CANCELED, PLAN FAILED and PLAN CRASHED - to failure, and NO CHANGES and HAS CHANGES - to success.