diff --git a/docs/Integration_guide.md b/docs/Integration_guide.md
new file mode 100644
index 0000000..d58ab68
--- /dev/null
+++ b/docs/Integration_guide.md
@@ -0,0 +1,51 @@
+# Integration guide
+
+## Github Actions
+
+In cases where your OpenAPI spec can be generated from your code, it can be useful to see how a pull request changes your API. For this very purpose we have a Github Action.
+
+### Generating the inputs
+
+To use it you need to first get the old (before the pull request) and new (after the pull request) specs.
+
+For example:
+
+- To get the old spec you can:
+  - Download from a public "production" server (if your api is public and you provide an OpenAPI spec)
+  - Checkout the base commit of the pull request and generate is programmatically.
+
+    You can checkout the base commit like so in Github Actions:
+
+    ```bash
+    git checkout $(git merge-base ${{ github.event.pull_request.head.sha }} ${{ github.event.pull_request.base.sha }})
+    ```
+- To get the new spec you can:
+  - Build and run the spec generation for the head commit of the pull request
+
+### Run the action
+
+In our example we have already generated the two OpenAPI specs and placed them in the `old-openapi.yaml` and `new-openapi.yaml` files.
+
+We can now run our action:
+
+##### NOTE: will only work after public release
+
+```yaml
+- uses: typeable/comparest
+    with:
+      old: old-openapi.yaml
+      new: new-openapi.yaml
+      project_name: TEST
+```
+
+This will create a comment on the pull request displaying the changes (if there are any) similar to this:
+
+![](img/github-action-comment.png)
+
+Consecutive runs of the action will update the comment instead of creating new ones. This will prevent the pile-up of compaREST comments and save you from distracting notifications.
+
+## Integrating into something other than Github Actions
+
+We have a dedicated implementation only for Github Actions. However, we provide a generic CLI which can be used to integrate compaREST into arbitrary workflows and CI systems.
+
+You see an example of CLI usage in our [readme](../README.md#assessing-compatibility-automatically).
diff --git a/docs/img/github-action-comment.png b/docs/img/github-action-comment.png
new file mode 100644
index 0000000..881ab07
Binary files /dev/null and b/docs/img/github-action-comment.png differ