chore: update onboarding instructions with PEM key location in GitHub

[gitcoindev]

Providing the URL will make it easier to onboard new developers.

Resolves https://github.com/ubiquibot/plugin-template/issues/7

I will keep updating docs in case I find any information that could be added and set it as a draft until instructions are clear to onboard a new joiner. I am quite sure I will make all docs tested and ready for final review over the weekend.

[gitcoindev]

I created a series of 7 short screencasts that together make a hello world plugin tutorial for new plugin developers. This should enable a 0-day onboarding for everyone. I will paste the screencasts as comments and later try to add them directly to the README.md.

1. Creating a SMEE webhook.

https://github.com/ubiquity/ubiquibot-kernel/assets/88761781/83760432-7d98-41f1-90c9-68ffa438db2a

[gitcoindev]

Second screencast larger than 10MB, I need to reduce its size before pasting - in progress..

[gitcoindev]

2. Creating and configuring GitHub app

02_creating-and-configuring-github-app.webm

[gitcoindev]

3. Creating environment variables

https://github.com/ubiquity/ubiquibot-kernel/assets/88761781/1b2bc7c5-1bf9-412f-b39a-a3c18ce05670

[gitcoindev]

4. Inserting variables into config.

https://github.com/ubiquity/ubiquibot-kernel/assets/88761781/170612a4-793c-4018-9e26-30ff1f828d1a

[gitcoindev]

5. Installing app.

https://github.com/ubiquity/ubiquibot-kernel/assets/88761781/9e71fed5-c29d-4aa7-99a7-bcacf8af11a5

[gitcoindev]

6. Creating plugin config.

https://github.com/ubiquity/ubiquibot-kernel/assets/88761781/9b422078-e1a0-430b-b50b-af751232d059

[gitcoindev]

7. Running hello world plugin.

https://github.com/ubiquity/ubiquibot-kernel/assets/88761781/3bfae8e5-142b-4f23-89ac-0f2ce58bbc46

[gitcoindev]

I created a separate wiki page with the content https://github.com/ubiquity/ubiquibot-kernel/wiki/Hello-world-plugin-onboarding-tutorial and added a link to README.md.

[0x4007]

Do you have any proposals on how to streamline the process further?

[rndquu]

4. Inserting variables into config.

   04_inserting_variables_into_config.mp4

Only senior devs know how to quit vim without restarting OS :)

[gitcoindev]

Do you have any proposals on how to streamline the process further?

I will try to provide both examples mentioned by @rndquu till Friday EOD.

[gitcoindev]

Do you have any proposals on how to streamline the process further?

I will try to provide both examples mentioned by @rndquu till Friday EOD.

I must confess on Friday I was surprised with a surprise party and got back to life on Sunday afternoon. But I was able to create a plugin skeleton in my fork based on the plugin-template repository, already. I will continue finalizing it this week. Then I will need to redo this from scratch during a screencast recording session. All screencasts will be published during the next days.

[gitcoindev]

Just to let you know - I am not idling and keep working on this but I have been stuck for quite some time now on the 'action' version of a plugin in my fork. The bot config in my org is in a private repository and kernel gets 404 when trying to access it, I also checked the same happens via rest api:

https://api.github.com/repos/korrrba/ubiquibot-config/contents/.github%2F.ubiquibot-config.yml

vs public config in the plugin which is visible

https://api.github.com/repos/korrrba/ubiquibot-hello-world-testing/contents/.github%2F.ubiquibot-config.yml

Perhaps kernel (v2) needs access / explicit permissions as well to access this. I think I need some rest and will get back to this tomorrow. All the other settings seem to be fine, I wrote a very simple handler to mimic the hello world so it should be pretty straightforward to run..

[gentlementlegen]

@gitcoindev Are you saying it runs fine when the configuration is public? I am also using a private repo on my org for the Action plugins with the kernel and it works fine so far. I don't recall setting particular permissions for that but it is possible it was required. Did you install the app on that repository, and is the config available on the branch you are trying to access?

[rndquu]

Yes, as gentlementlegen noted check that:

1. The bot is installed both in the plugin repo and in the repo where the config is located
2. The bot has read permission for repository contents

If that doesn't help try to set all of the permissions to read and write, perhaps we're missing smth.

[gitcoindev]

Thank you for the hints and I am sorry for the delay. What seemed simple somehow blocked me. I need to unlock my brain and go back into the dev zone. Please give me 1-2 days max and I will finalize the videos.

[gitcoindev]

I yet again apologize for the delay. I am alive but a few unexpected events happened and as a result I literally could not move since Tuesday. Fortunately, I avoided surgery. I have a full day available tomorrow, please give me time until Friday EOD to complete this task.

[gitcoindev]

I was able to solve all but one issues in my local setup...

env:
    SUPABASE_URL: ${SUPABASE_URL}
    SUPABASE_KEY: ${SUPABASE_KEY}

TransformDecodeCheckError: Unable to decode value as it does not match the expected schema

even though I pass the secrets they are not recognized, perhaps it is too late today.. will check over the weekend.

[gitcoindev]

I finally created the remaining GitHub actions hello world plugin videos and will put them in the wiki.

1. Creating plugin from template

https://github.com/user-attachments/assets/65a7bb4c-9e1a-4916-8434-c7e16851991a

[gitcoindev]

2. Creating test issue

https://github.com/user-attachments/assets/6eb6a0a6-cb1f-4015-b153-47c5199d353e

[gitcoindev]

3. Creating bot configuration and implementation skeleton

https://github.com/user-attachments/assets/c53ce7ea-9ac2-487d-9010-ab961ef66859

[gitcoindev]

4. Running GitHub actions plugin

https://github.com/user-attachments/assets/c2fb24fa-6e7d-41e8-9366-2bce060c01db

[0x4007]

@gentlementlegen @Keyrxng @whilefoo I think you all have successfully built plugins before right? Can you all verify?

[gentlementlegen]

Works for me, although there is no example with Workers, will it be in a separate PR?

[0x4007]

Works for me, although there is no example with Workers, will it be in a separate PR?

I suppose this would be good to add if its not too complicated.

[gitcoindev]

Works for me, although there is no example with Workers, will it be in a separate PR?

I suppose this would be good to add if its not too complicated.

Sure, I can add the example with workers next week when I am back from the trip.

[rndquu]

The thing with the worker example is that the kernel supports any http server to be a plugin (which is already covered in the wiki at step 7 Running hello world plugin) and cloudflare worker is just another way of setting up an http server.

[Keyrxng]

1. The GitHub app setup and kernel config setup etc is excellent it's clear and easy to follow

2. When the setup was happening only two events were subscribed to, which is true in the case of the plugin but it's the bot that's being setup in that section not the plugin, which I think will lead to confusion as the bot should listen to basically all events no?

3. Having the videos combined into one and hosted somewhere built for it would be a huge bonus. Idk about you folks but GitHub is terrible for video playback, it fails to load and repeats the same section constantly for me forcing me to refresh until it loads and plays it all. It took way longer than it should have to watch these videos and I live alone with really good wifi speeds.

4. Personally, I found the plugin config and the worker confusing. It felt totally different from how actual plugins are built and configured, ts-template usage also confused me but I see it has been updated.

5. The updated video showing the diff of the inserted config values does not show the function that had to be created in order for the plugin to work. I think this is a problem because in watching the first videos my thoughts were "how is the 'world' comment happening without any logic being written", I first checked the repos which korrba and rndquu made before realizing it was a script in the kernel repo. Again, totally different from how things are actually done.

---

I'd have assumed that the plugin-template would be converted into a hello-world plugin which when forked works right out of the box and you have to delete the hello-world.ts file to start building. This is the most streamlined version I can think of and it keeps the kernel separate from plugins which is the model we want to push onto plugin devs really isn't it, not so much the kernel side?

Also you cannot just copy and paste this plugin example so I think it's a bad example to use for onboarding.

---

So for example the worker command for start/stop will be something like bun plugin:start-stop? I'm I right?

When I was helping jordan set things up he said this to me on the 13th and at the time I wasn't aware of the kernel hello-world example but it's clear that it was something he had to wrap his head around. But understood things once I made it clear you had to run both locally, separately and how those interacted with each other i.e the plugin only listens to the kernel and the kernel only listens to GitHub etc...

Which makes me ask what assumptions are we making about people we are onboarding?

clear enough to onboard new developers who have no previous experience with the repository.

There are assumptions being made re: http coms and servers, intuitive enough to seek out examples, intuitive enough to see the poor example and then transform that into a proper plugin via other real examples etc.

I think one or two simple diagrams for how the kernel interacts with plugins and vice versa would go a really long way and cut onboarding time down considerably as it's far easier to understand a new mental model when you can see it visualized.

[rndquu]

Also you cannot just copy and paste this plugin example so I think it's a bad example to use for onboarding.

This "hello-world" plugin is really handy for QAing kernel features. It was not initially meant to be used in the onboarding although it more or less fits this purpose.

Overall I agree that in the next docs iteration we could stick only to the https://github.com/ubiquibot/plugin-template and add more diagrams describing the overall process.