@bigbinary/neeto-github-frontend 1.0.1

package/README.md

@@ -0,0 +1,296 @@
+# neeto-github-nano
+
+A Ruby gem that manages GitHub integration across neeto products
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "neeto-github-engine", git: "https://#{github_auth_string}@github.com/bigbinary/neeto-github-nano.git", branch: "stable"
+
+gem "octokit"
+```
+
+And then execute:
+
+```bash
+bundle
+```
+
+Or use `gem install`:
+
+```bash
+gem install neeto-github-engine octokit
+```
+
+## Migration
+
+To Copy migration files, run:
+
+```bash
+rails g neeto_github_engine:install
+```
+
+After adding the migration file, run:
+
+```bash
+bundle exec rails db:migrate
+```
+
+## Integration
+
+`neeto-github-engine` supports OAuth apps and GitHub apps. Depending upon the use case you can use either one or both together. Refer to the link below to understand the differences between a Github app and an OAuth app: <https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps>
+
+1. [Integrate OAuth app](#integrate-oauth-app)
+2. [Integrate GitHub app](#integrate-github-app)
+
+## Integrate OAuth app
+
+### Create an OAuth app on GitHub
+
+Refer to this: <https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app>
+
+Set the Callback URL as:
+
+```text
+https://connect.neeto<AppName>.com
+```
+
+Here, the subdomain can be anything like `connect` or `app`.
+The domain will be the application domain.
+Create different OAuth apps for staging and production.
+
+After getting the `client_id` and `client_secret`,
+add this to the `secrets.yml` file in your application.
+
+```yml
+default:
+  github_oauth_app:
+    client_id: <%= ENV["GITHUB_CLIENT_ID"] %>
+    client_secret: <%= ENV["GITHUB_CLIENT_SECRET"] %>
+```
+
+and add the secrets to ENV.
+
+### Add JWT private and public keys
+
+Run the following ruby command to generate an RSA key pair:
+
+```ruby
+rsa = OpenSSL::PKey::RSA.generate(2048)
+```
+
+The following command prints the private key:
+
+```ruby
+rsa.to_s
+```
+
+The following command prints the public key:
+
+```ruby
+rsa.public_key.to_s
+```
+
+Store the private and public keys as environment variables,
+let's say, as `JWT_PRIVATE_KEY` and `JWT_PUBLIC_KEY`, respectively.
+Then add the keys to the `secrets.yml` file in your application,
+as shown below:
+
+```yml
+default:
+  jwt:
+    private_key: <%= ENV['JWT_PRIVATE_KEY'].inspect %>
+    public_key: <%= ENV['JWT_PUBLIC_KEY'].inspect %>
+```
+
+### Add association
+
+```bash
+rails g neeto_github_engine:integration <entity>
+```
+
+For example, if the `organization` model should have many accounts, you should run:
+
+```bash
+rails g neeto_github_engine:integration organization
+```
+
+This will add `NeetoGithubEngine::Integratable` concern to the `Organization` model.
+
+### Controllers to store the access token
+
+- `AuthorizeController` (`/neeto_github/authorize`)
+  This action accepts 4 params:
+
+1. integrator_type
+2. integrator_id
+3. redirect_path
+4. scope
+
+For Example, if the `Organization` is the integrator of accounts then redirect the user to:
+
+```js
+/neeto_github/authorize?${qs.stringify({
+   integrator_type: 'Organization',
+   integrator_id: organizationId,
+   scope: "repo",
+   redirect_path: `/settings/github-integration`,
+ })}
+```
+
+where the `scope` is what scope level application needs to access GitHub and
+`redirect_path` is where the user needs to be redirected after the authorization is completed.
+
+### Controllers
+
+```ruby
+NeetoGithubEngine::AccountsController
+```
+
+The controller mentioned above can be used to fetch GitHub accounts.
+
+Mandatory params:
+
+- `integrator_id`
+- `integrator_type`
+
+### Add Repository to Entity
+
+```bash
+rails g neeto_github_engine:repository <entity>
+```
+
+The above command will:
+
+1. Create a file in `app/models` with the name `<entity>Repository.rb`.
+2. Add an association to the entity model.
+
+### Link Pull Request With Entity
+```
+include NeetoGithubEngine::Linkable
+```
+The above concern will associate the entity with `NeetoGithubEngine::PullRequest` Model.
+
+### Using controllers
+
+- Controllers must inherit from
+
+  ```ruby
+    NeetoGithubEngine::BaseController
+  ```
+
+  Mandatory params: account_id
+
+## Integrate GitHub app
+
+### Create a GitHub app in GitHub
+
+Refer: https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app
+
+**⚠️ When creating a GitHub app make sure to not to include spaces or special characters (except hyphen ``-``) in the GitHub App name field**
+
+Set the post installation setup url in the GitHub app's general settings page as:
+```
+https://app.neeto<AppName>.com/neeto_github/app_installations/callbacks
+```
+Here, the subdomain can be anything like connect or app. The domain will be the application domain.
+
+Enable the webhooks and set the webhook url as:
+
+```
+https://app.neeto<AppName>.com/neeto_github/webhooks
+```
+You can choose a random string of text with high entropy as `webhook_secret`.
+
+After getting the `app_id`, `app_name`, `private_key` and `webhook_secret`, add them to the secrets.yml file in your application.
+
+```yml
+default: &default
+  github_app:
+    id: <%= ENV["GITHUB_APP_ID"] %>
+    name: <%= ENV["GITHUB_APP_NAME"] %>
+    private_key: <%= ENV["GITHUB_APP_PRIVATE_KEY"].inspect %>
+    webhook_secret: <%= ENV["GITHUB_APP_WEBHOOK_SECRET"] %>
+```
+
+Follow the steps of OAuth app integration for adding [JWT private and public keys](#add-jwt-private-and-public-keys) and [association](#add-association).
+
+
+### Install GitHub app
+
+`AppInstallationsController#new` Used to install the github app in the user specified repositories. This action accepts 4 URL query parameters:
+
+1. integrator_type
+2. integrator_id
+3. redirect_path
+4. fallback_redirect_path
+
+Here the `redirect_path` is where the user needs to be redirected after the installation is completed and `fallback_redirect_path` is where the user needs to redirected in case of any error.
+
+```
+GET /neeto_github/app_installations/new?integrator_type=<integrator_type>&integrator_id=<integrator_id>&redirect_path=/settings&fallback_redirect_path=/settings
+```
+
+### Fetch app installations
+
+`AppInstallationsController#index` Used to list app installations that are associated with an integrator. This action accepts 4 URL query parameters:
+
+1. integrator_type
+2. integrator_id
+3. page_size (optional)
+4. page (optional)
+
+```
+GET /neeto_github/app_installations?integrator_type=<integrator_type>&integrator_id=<integrator_id>&page_size=10&page=1
+```
+
+### Destroy app installation
+
+`AppInstallationsController#destroy` Used to destroy a particular `AppInstallation`. This action accepts 3  URL parameters:
+
+Query parameters:
+1. integrator_type
+2. integrator_id
+
+Path parameters:
+1. app_installation_id
+
+```
+DELETE /neeto_github/app_installations/<app_installation_id>?integrator_type=<integrator_type>&integrator_id=<integrator_id>
+```
+
+### Fetch app installation repositories
+
+`AppInstallations::RepositoriesController#index` Used to list the repositories of an installed github app. This action accepts 3 URL parameters:
+
+Query parameters:
+1. integrator_type
+2. integrator_id
+
+Path parameters:
+1. app_installation_id
+
+```
+GET /neeto_github/app_installations/<app_installation_id>/repositories?integrator_id=<integrator_id>&integrator_type=<integrator_type>
+```
+
+### Get an issue detail
+
+`AppInstallations::Repositories::IssuesController#Issue` This action provides the details of an github issue. This action accepts 5 URL parameters:
+
+Query parameters:
+1. integrator_type
+2. integrator_id
+
+Path parameters:
+1. app_installation_id
+4. repository_full_name
+3. issue_number
+
+`repository_full_name` should be URL encoded. You can use `encodeURIComponent` javascript method to URL encode `repository_full_name`.
+
+```
+GET /neeto_github/app_installations/<app_installation_id>/repositories/<url_encoded_repository_full_name>/issues/<issue_number>?integrator_id=<integrator_id>&integrator_type=<integrator_type>
+```

package/app/javascript/src/translations/en.json

@@ -0,0 +1,25 @@
+{
+  "connect": "Connect",
+  "github": "Github",
+  "noRepos": "No repositories found",
+  "noReposDescription": "Connect a GitHub repository to begin using your existing repos for new services.",
+  "notConnectedDescription": "Connect your neetoCI account to GitHub to begin using your existing repos for new services.",
+  "configureAccount": "Configure account",
+  "connectAccount": "Connect account",
+  "connectGithub": "Connect GitHub",
+  "connectARepo": "Connect a repository",
+  "connectRepository": "Connect repository",
+  "continue": "Continue",
+  "publicGitRepo": "Public Git repository",
+  "publicGitRepoDescription": "Use a public repository by entering the URL below.",
+  "publicGitRepoPlaceholder": "https://github.com/bigbinary/example-app",
+  "countOf": {
+    "repos_one": "{{count}} repo",
+    "repos_other": "{{count}} repos"
+  },
+  "neetoGithubNanoModal": {
+    "title": "Create a new project",
+    "description": "Connect your Git repository or use an existing public repository URL."
+  },
+  "troubleshoot": "Can't find a repository that's already connected? <troubleshootLink>Troubleshoot</troubleshootLink> your GitHub connection."
+}