From d6816a68cc003313cd5829aa01bf508a035ec3a6 Mon Sep 17 00:00:00 2001 From: Vincent Date: Fri, 23 Aug 2024 15:32:01 +0200 Subject: [PATCH] docs: add a page about connections --- apps/website/astro.config.mjs | 4 +- apps/website/src/content/docs/index.mdx | 2 +- .../index.md => overview/get-started.md} | 2 +- .../content/docs/{about => overview}/index.md | 0 .../src/content/docs/self-host/index.md | 2 +- .../content/docs/user-guide/attention-set.md | 2 +- .../content/docs/user-guide/connections.md | 50 +++++++++++++++++-- .../src/content/docs/user-guide/inbox.md | 3 +- .../src/content/docs/user-guide/index.mdx | 24 +++++++++ 9 files changed, 78 insertions(+), 11 deletions(-) rename apps/website/src/content/docs/{user-guide/index.md => overview/get-started.md} (98%) rename apps/website/src/content/docs/{about => overview}/index.md (100%) create mode 100644 apps/website/src/content/docs/user-guide/index.mdx diff --git a/apps/website/astro.config.mjs b/apps/website/astro.config.mjs index 567126f..22f972f 100644 --- a/apps/website/astro.config.mjs +++ b/apps/website/astro.config.mjs @@ -22,8 +22,8 @@ export default defineConfig({ }, sidebar: [ { - label: "About", - autogenerate: { directory: "about" }, + label: "Overview", + autogenerate: { directory: "overview" }, }, { label: "User Guide", diff --git a/apps/website/src/content/docs/index.mdx b/apps/website/src/content/docs/index.mdx index c39cebf..9024b0a 100644 --- a/apps/website/src/content/docs/index.mdx +++ b/apps/website/src/content/docs/index.mdx @@ -7,7 +7,7 @@ hero: tagline: A better inbox for GitHub pull requests. actions: - text: Read The Docs - link: ./about/ + link: ./overview/ icon: right-arrow - text: Try Now link: https://mergeable.pages.dev diff --git a/apps/website/src/content/docs/user-guide/index.md b/apps/website/src/content/docs/overview/get-started.md similarity index 98% rename from apps/website/src/content/docs/user-guide/index.md rename to apps/website/src/content/docs/overview/get-started.md index e05bc7c..4edf347 100644 --- a/apps/website/src/content/docs/user-guide/index.md +++ b/apps/website/src/content/docs/overview/get-started.md @@ -1,5 +1,5 @@ --- -title: Getting started +title: Get started sidebar: order: 1 --- diff --git a/apps/website/src/content/docs/about/index.md b/apps/website/src/content/docs/overview/index.md similarity index 100% rename from apps/website/src/content/docs/about/index.md rename to apps/website/src/content/docs/overview/index.md diff --git a/apps/website/src/content/docs/self-host/index.md b/apps/website/src/content/docs/self-host/index.md index 0e98797..d5f533f 100644 --- a/apps/website/src/content/docs/self-host/index.md +++ b/apps/website/src/content/docs/self-host/index.md @@ -1,5 +1,5 @@ --- -title: Getting started +title: Introduction sidebar: order: 1 --- diff --git a/apps/website/src/content/docs/user-guide/attention-set.md b/apps/website/src/content/docs/user-guide/attention-set.md index 7b10b97..fabb6ea 100644 --- a/apps/website/src/content/docs/user-guide/attention-set.md +++ b/apps/website/src/content/docs/user-guide/attention-set.md @@ -2,5 +2,5 @@ title: Use the attention set draft: true sidebar: - order: 3 + order: 4 --- diff --git a/apps/website/src/content/docs/user-guide/connections.md b/apps/website/src/content/docs/user-guide/connections.md index de88520..4364483 100644 --- a/apps/website/src/content/docs/user-guide/connections.md +++ b/apps/website/src/content/docs/user-guide/connections.md @@ -1,9 +1,51 @@ --- -title: Configure connections -draft: true +title: Setup connections sidebar: - order: 4 + order: 2 --- +A unique capability of Mergeable is that it can connect to any number of GitHub instances. +A connection is made of a GitHub API endpoint and an access token. + +Most people will use it with [github.com](https://github.com), but it is also able to connect to a GitHub Enterprise installation. +Multiple connections to the same instance may even exist, which may be useful to connect different user accounts with different permissions. + +## Add a new connection + +You can add a new connection from the settings page, and clicking on "New connection". +The following dialog will open: + +![New connection dialog](../../../assets/screenshots/new-connection.png) + +You need to provide a URL and an access token. +The URL must be a GitHub API endpoint (**not** a UI endpoint). +For github.com, the URL is `https://api.github.com`. +For GitHub Enterprise installations, the URL is usually the hostname followed by `/api/v3`. + +Because all interactions with GitHub will happen in your browser, you need to make sure that your machine has connectivity to the provided endpoint. +However, the location where Mergeable is deployed does not matter, since it will not directly reach out to GitHub. + +The access token is generated from GitHub from Settings > Developer settings > Personal access tokens. +Please refer to GitHub's documentation to [learn more about access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). + +The label is optional and purely informational. +It is only used in the settings page to help distinguish similar connections (e.g., two connections to the same instance of GitHub). + +The organizations filter is used to restrict access to a connection to a particular set of GitHub organizations. +By default, Mergeable will search across all pull requests that the access token has access to. +In some situations, you may want to only search across a subset of GitHub organizations, e.g., to restrict the scope to a business or personal context. + +## Edit a connection + +You may edit an existing connection by clicking on the "Edit" button in its row. +The edit dialog also contains a link to delete the connection permanently. + +## Access token permissions + +GitHub personal access tokens come in two flavours: classic and fine-grained. For now, Mergeable has only been tested with classic access tokens. -Make sure to select at least the `read:org`, `repo` and `user` scopes. +To be used with Mergeable, an access token needs at least the following scopes: + +* `read:org`: Access which teams a user is a member of, used to determine if it is a requested reviewer via a requested team. +* `repo`: Search for pull requests and related information, such as reviews and CI checks. +* `user`: Access basic information about the user, such as their name. \ No newline at end of file diff --git a/apps/website/src/content/docs/user-guide/inbox.md b/apps/website/src/content/docs/user-guide/inbox.md index 57f2388..0803538 100644 --- a/apps/website/src/content/docs/user-guide/inbox.md +++ b/apps/website/src/content/docs/user-guide/inbox.md @@ -1,7 +1,7 @@ --- title: Use the inbox sidebar: - order: 2 + order: 3 --- The landing page of Mergeable is its inbox, that shows all pull requests in your radar. @@ -35,6 +35,7 @@ Results from all individual search queries will be merged and displayed together ### Edit a section You may edit an existing section by clicking on the pencil icon on the right side, next to its label. +The edit dialog also contains a link to delete the section permanently. ### Move sections diff --git a/apps/website/src/content/docs/user-guide/index.mdx b/apps/website/src/content/docs/user-guide/index.mdx new file mode 100644 index 0000000..297c4de --- /dev/null +++ b/apps/website/src/content/docs/user-guide/index.mdx @@ -0,0 +1,24 @@ +--- +title: Introduction +prev: false +next: false +sidebar: + order: 0 +--- + +import { LinkCard, CardGrid } from '@astrojs/starlight/components' + +This section contains the user documentation for the Web application. + + + + + \ No newline at end of file