Merge pull request #426 from OpenFn/gh_dashboard

Update Link to GH with steps from Portability, new dashboard page

Author: aleksa-krolls

docs/manage-projects/link-to-gh.md

@@ -36,41 +36,93 @@ Click `Configure`...
 5. You'll be redirected to OpenFn. Select the repository and branch you want to
    sync to, and click `Connect Branch`.
 
-6. Your GitHub connection is now set up!
-
-7. Synchronization is _not_ automatic. Each time you want to sync between your
-   project and GitHub, click `Initiate Sync to Branch`.
-
-![Initiate Sync](/img/lightning_gh_initate_sync.png)
-
-:::tip Sync after every major change
-
-Each time you make any significant change in your project, for example changes
-in a job code, make sure to hit `Initiate Sync to Branch` to sync your updates
-to GitHub.
-
-:::
+6. Once you have created a a connection, set up `pull` and `deploy` workflows
+   that use openfn github actions below.
+7. Add `OPENFN_API_KEY` and `OPENFN_PROJECT_ID` repository secrets to your
+   Github repo as described below.
+8. Add a `config.json` file to your repository which specifies your endpoint and
+   paths to project spec and state files.
+9. Click the sync to Github button to initiate a sync from Lightning to GitHub.
+10. Push a change to your selected branch to push changes from Github to
+    Lightning.
+
+#### Github Repository Secrets
+
+The workflows that interact with the OpenFn actions will need the repository set
+up with two secrets used in the github actions:
+
+- OPENFN_API_KEY: This is your API Key as generated from Lightning and will be
+  needed for authentication
+- OPENFN_PROJECT_ID: This is your Project ID from Lightning this will be used to
+  pull from the lightning instance
+
+#### Github Repository Structure
+
+Here you can do pretty much what you want, so long as you've got a `config.json`
+pointing to your project spec, state, and Lightning endpoint.
+
+#### Example [Deploy Workflow](https://github.com/OpenFn/demo-openhie/blob/main/.github/workflows/deploy.yml) for GitHub
+
+See https://docs.github.com/en/actions/quickstart#creating-your-first-workflow
+for more help here.
+
+```yml
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy-to-lightning:
+    runs-on: ubuntu-latest
+    name: A job to deploy to Lightning
+    steps:
+      - name: openfn deploy
+        uses: OpenFn/[email protected]
+        with:
+          secret_input: ${{ secrets.OPENFN_API_KEY }}
+```
+
+#### Example [Pull Workflow](https://github.com/OpenFn/demo-openhie/blob/main/.github/workflows/pull.yml) for GitHub
+
+See https://docs.github.com/en/actions/quickstart#creating-your-first-workflow
+for more help here.
+
+```yml
+on: [repository_dispatch]
+
+jobs:
+  pull-from-lightning:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    name: A job to pull changes from Lightning
+    steps:
+      - name: openfn pull and commit
+        uses: OpenFn/[email protected]
+        with:
+          secret_input: ${{ secrets.OPENFN_API_KEY }}
+          project_id_input: ${{ secrets.OPENFN_PROJECT_ID }}
+          commit_message_input:
+            'user ${{ github.event.client_payload.message }}'
+```
+
+The Lightning [demo instance](https://demo.openfn.org) is currently connected to
+[this repo](https://github.com/OpenFn/demo-openhie/). Feel free to play around
+with it.
+
+11. Your GitHub connection is now set up! From here, each time you want to sync
+    between your project and GitHub, click `Initiate Sycn to Branch`.
 
 ### How It Works in a Nutshell
 
-Your whole OpenFn project can be represented as a `project.yaml` file. It
-includes all your workflow specifications, their name, job code, triggers, and
-so on.
+Your whole OpenFn project can be represented as a project.yaml file.
 
 Using our Command Line Interface, the [@openfn/cli](../deploy/portability.md)
 you can pull a project config from OpenFn to a folder or repo on your computer,
-and you can deploy a change in your `project.yaml` file from that directory or
+and you can deploy a change in your project.yaml file from that directory or
 repo to OpenFn.
 
-:::info
-
-As your `project.yaml` file represents your entire project, this is the file
-that you have to update when you want to deploy any changes to your OpenFn
-project. If you made a change or created a new job, for example, you have to
-include them in the `project.yaml` to deploy.
-
-:::
-
 The `Sync to Github` feature makes use of GitHub actions to automatically deploy
 (after a commit) or pull (when `Initiate Sync to Branch` button is clicked) to
 keep a repository in sync with your OpenFn project.

docs/manage-projects/workflow-dashboard.md

@@ -0,0 +1,25 @@
+---
+title: Monitoring Workflows
+sidebar_label: Monitoring Workflows
+slug: /monitoring-workflows
+---
+
+In this article, you'll learn how you can monitor the status of your Workflows.
+
+## Workflow Dashboard
+
+On your main Workflows page you can get an overview of the number of the Work
+Orders and Runs in your project, and the number and ratio of successes and
+failures.
+
+![Dashboard](/img/lightning_workflow_dashboard.png)
+
+For further investigation, clicking on the number of Work Orders for the
+Workflows as shown bring you to the History of that Workflow. For example, here
+are the 7 Work Orders in a failed state:
+
+![Failed Work Orders](/img/lightning_failed_work_orders.png)
+
+Check out our
+[History docs](https://docs.openfn.org/documentation/monitor-history/activity-history)
+for more on managing and monitoring Runs and Work Orders.

sidebars-main.js

@@ -111,6 +111,7 @@ module.exports = {
         'manage-projects/notifications',
         'manage-projects/link-to-gh',
         'manage-projects/webhook-auth',
+        'manage-projects/workflow-dashboard',
       ],
     },
     {