Improve UX for Github project sync

[taylordowns2000]

At the time of writing, I think this is the current UX flow (is this correct @zacck ?) for the new Github version control system:

1. Click "install github"
2. Select repo(s) in github*.
3. [ Maybe see error - "We've set up your PRC but you can't use it until your GitHub org administrator grants access." ]
4. [ Maybe wait for authorization from GitHub admin ]
5. Select repo and branch, click save.
6. Navigate to Github and compose two new workflows:
7. The first workflow happens "on commit" to some branch** and executes the OpenFn/deploy_action action
8. The second workflow happens "on repository dispatch event" and executes the OpenFn/pull_action action
9. Navigate to OpenFn and click "sync"
10. Navigate to GitHub and see the code from OpenFn appear in your github repo.
11. Make a change on GitHub.
12. Navigate to OpenFn and see the project get updated on OpenFn.

*Can we limit it to just one? What happens if they install in two or ten?
**How do we know if it's the same as the branch you chose in step 5?

Before we ask someone to go through this process we should clean it up significantly.

In v1, OpenFn actually added a webhook to the repo so that no additional github config was required. This should be possible in v2 as well, given that a GitHub app can create and manage workflows in the repo that it was installed in.

Note that after these workflows are created, we need Lightning to verify that they've been set up properly.
In v1, once we get the success message after creating the webhook we display that webhook ID to the user:

Questions:

1. Should this be a single workflow? Should, on commit to branch X OR on repostiory_dispatch_event should the workflow: (a) check for changes on lightning, (b) merge them in alongside whatever local changes were just made in github, if any, then (c) deploy to lightning?

[zacck]

@taylordowns2000
Yes the flow you decribe is what we should demo, some notes however.

Above on point 3. Github does not enable us to know if an app ID is created or not, the following is the error body we get before permissions and also when the installation_id is wrong. I can use the copy above for the message however it will replace the other one for errors.

 body: %{
     "documentation_url" => "https://docs.github.com/rest/reference/apps#create-an-installation-access-token-for-an-app",
     "message" => "Not Found"
   }

On limiting them to just one, we can't do that as that is entirely done in Github, if they install to more than one repo the repos and their branches will be available on the pickList

On knowing the branches are the same, in the context of checking through the REST API it appears we can't check that
https://docs.github.com/en/rest/actions/workflows?apiVersion=2022-11-28#get-a-workflow

On Creating workflows via the REST API from what I can see is a Read API
https://docs.github.com/en/rest/actions/workflows?apiVersion=2022-11-28

On verifying if the workflows are setup well I am unsure of how to get that implemented. I'll go through the API some more.

Proposals for the questions:

1. Yes, it can be a single workflow with a number of triggers.

on -> repository_dispatch

• checkout the code
• pull changes from Lightning
• commit this changes into the repo with the message in the payload.
• if the commit is to a branch that is the same as the one set to deploy below, the workflow will deploy the changes in this commit.

on -> push_to_branch

• checkout the state and spec to branch
• use this as state and spec and deploy this to the lightning instance
• and commit the new state and spec and updated by the deploy result

[taylordowns2000]

All sounds good. For creating the workflows, I think this needs to be done by opening a PR (via the github app) once the user installs the github app:

Note how you set up Renovate for github repos… once you’ve installed, you’ll see this PR (link below) show up on your repo. The PR creates a workflow and asks to merge it into main. That workflow uses the renovate github action.

• How to install renovate: https://github.com/renovatebot/renovate/blob/main/docs/usage/getting-started/installing-onboarding.md
• The renovate github action: https://github.com/renovatebot/github-action

[zacck]

@taylordowns2000 do we have further action for this?

[taylordowns2000]

when you're happy with the documentation for the current flow, yes, I think we should have lightning propose these workflows in a PR when a user installs them: https://github.com/OpenFn/demo-openhie/tree/main/.github/workflows

but please finish the docs before moving onto this

[taylordowns2000]

• Noting that this issue will be complete when we automate adding the Github .github/workflows/pull.yml and .github/workflows/deploy.yml
• (Another UX feature will be opened later.)

The files:

• https://github.com/OpenFn/demo-openhie/blob/main/.github/workflows/pull.yml
• https://github.com/OpenFn/demo-openhie/blob/main/.github/workflows/deploy.yml