How to set up GitHub to install external projects

ir engine is extensible via projects /manual/concepts/projects , which can contain new scenes, new avatars, new static resources, additional code, and more ir engine integrates with github to push and pull projects for backup and restoration, and one can also install existing projects from github in order to install projects from private repositories, or to push local project changes to a github repo, an oauth app from github (not a github app, that is something different) needs to be created, and the logged in user must be connected in ir engine to github (i e must have logged in via github at some point) and have permission to access the source and destination repositories note that it is recommended that you complete most of this before the initial installation of your deployment, so that you can log in via github and be granted admin status as the first logged in user if you do not, then you will either need to manually insert some of these values into the database so that you can log yourself in; have another log method configured already and use that logged in admin user; or reset the database with these values configured in the updated helm configuration that is used for the reset create a github oauth app in an organization, or your user you can either create an oauth app for your personal github account or for an organization that you have sufficient permissions on either will work for this setup the general instructions for doing this can be found here https //docs github com/en/developers/apps/building oauth apps/creating an oauth app the specifics you'll need to enter are as follows application name anything you want homepage url whatever you want, this is just what is linked to from the oauth authorization page authorization callback url enter https //api \<domain>/oauth/github/callback , e g https //api example com/oauth/github/callback ^ enable device flow leave unchecked ^if you are running this locally off of localhost, this should be https //localhost 3030/oauth/github/callback if you are using an explicit ip address instead of localhost , then use that ip address here, but keep the 3030 , as that is the port that the api server runs on, and github needs to call back to the api server create client secret, note client id once the app has been created, you will be redirected to the general settings for it here, you will generate one credential for the app, so that your deployment can be authenticated make note of client id near the top of this page is the client id for the app this is a public id for the app it will be used when configuring ir engine generate client secret below client id is a section client secrets none are created by default, so click the button generate a new client secret as the notifications that appear say, you will only see the full secret right now, so copy it somewhere retrievable (but not anywhere publicly accessible) if you ever lose the secret, you can always generate a new one configure ir engine deployment with ids/keys pre initial installation if you have not done the initial installation/deployment yet, then you can add most of the values above to the helm configuration, and they will be inserted into the database so that github login is enabled from the start, and you can then log in via github and be granted admin status enter the client id for github client id , and the client secret for github client secret in the section api extraenv it is advised that you enclose all of these in double quotes in the yaml file, so that they are interpreted as strings even if they start with a number, e g github client id "17592577832789234" if you see github app id , it is not used; it is left over from a prior implementation of github apps, which no longer works continue with the setup instructions when you run helm install with your configuration file, the github credentials will be included post installation, if you have another authentication method configured if you have already installed the platform but configured it with another login method, such as email or another oauth provider, then log in as an admin user if you haven't logged in with anything yet, then the first user that logs in will be made an admin go to /admin/settings click on the authentication selector a page should open with a section oauth that takes up the bottom two thirds under github , enter the client id under key and the client secret under secret click the save button at the bottom post installation, if you do not have any authentication method configured if you have already set up the platform but did not configure any authentication method, then you are in a bit of a bind where you can't log in to get admin privileges, but need admin privileges to configure an authentication method the way around this is to reset the database and provide the github credentials as part of this process this is similar to what would happen on initial installation note that this will erase anything you've done so far, but without any admins, the most you'd have been likely to do is change some guest users' avatars open your helm configuration enter the client id for github client id and the client secret for github client secret in the section api extraenv it is advised that you enclose all of these in double quotes in the yaml file, so that they are interpreted as strings even if they start with a number, e g github client id "17592577832789234" next, run helm upgrade reuse values f \<path/to/configuration yaml> set string api extraenv force db refresh=true \<stage name> ir engine/ir engine this tells helm to restart the api servers, and for them to wipe the database and reseed it with the values in the configuration file it should only take a minute or two, and you should then run helm upgrade reuse values set string api extraenv force db refresh=false \<stage name> ir engine/ir engine to unset the flag telling it to reset the database once this is done, you should be able to log in with github and be granted admin status logging in with github and granting access to other organizations when you log in with github, you will be asked to grant access to your user information as well as the repositories that the oauth app has authorized for ir engine will have access to your personal repositories and, if the oauth app was created in a github organization, all repositories in that organization it will not have inherent push access to other organizations' repositories or pull access to their private repositories there are two ways to grant access to other repositories when you are first signing in via github and are presented with the screen to authorize the oauth app's permissions, you should see a section near the bottom that shows all of the organizations you are in if you have admin rights to that organization, you can grant access if you do not have admin rights, then you can request access, and someone who does have admin rights will have to approve it if you have already gone through the oauth approval page, it will not be shown again all subsequent logins will bypass this page\[^1] in order to grant the oauth app access to other organizations, follow these steps https //docs github com/en/organizations/managing oauth access to your organizations data/approving oauth apps for your organization in short form go to ( https //github com/settings/applications https //github com/settings/applications ) click on the name of the oauth app installed in ir engine under organization access , click on grant/request for the organizations you want ir engine to have access to installing ir engine projects from github see the section 'graphical install flow /manual/concepts/projects for more information on how to install projects from github user repo access to github (with optional webhooks) users can push projects to github if they have write/maintain/admin access to the associated github repository since fetching this access from the github api every time a user fetches their projects can take a noticeable amount of time, ir engine stores users' github repo access in its database this is much faster to access there are multiple actions that will make the engine re fetch and update users' repo access when a user logs in via github when a user clicks on the button "refresh github repo access" on /admin/projects or /studio (must be logged in as a user that is associated with a github account) via a github webhook must manually configure this setting up github webhook ir engine currently only supports webhook notifications for collaborators being added/edited/removed changes in teams are not handled by ir engine due to the opacity of team members (team change webhooks do not include team members, and the engine does not track who is in a team) an admin needs to go to /admin/settings, click on 'server', then enter a secret key in the field "github webhook secret", then click the save button the secret can be any string you make up randomly generated strings are encouraged next, go to gitgub in the repository or organization that you want to send updates for, go to settings > code(, planning,) and automation > webhooks, then click "add webhook" for payload url, enter \<your api subdomain>/github repo access webhook , e g https //api example com/github repo access webhook set content type to application/json for secret, enter the secret from the earlier step for "which events would you like to trigger this webhook?", select "let me select individual events " in the list of events that appears, uncheck "pushes", anf check "collaborator add, remove, or changed" at the very bottom of the page, click the green button "add webhook" after the webhook is created, the webhook will send a ping request to the api endpoint you provided if the url was entered correctly, and the secret was entered correctly in both ends, the ping should get a 200 response you can check the status under the "recent deliveries" tab of that webhook on github when this is working, whenever a user is added, removed, or has their access modified, the engine will re fetch the user's full set of github repo accesses and update the database's records