Consolidate VCS integration guides with org/user/project/pipeline content #9715
Conversation
|
|
||
| As a CircleCI _user_ you can create and access _organizations_. You can access zero, one, or many organizations. You can create new organizations and/or join an existing organization. | ||
|
|
||
| You can log in to CircleCI using one of the following methods: |
There was a problem hiding this comment.
Do we want to call out that they are mutually exclusive?
e.g. if you have an email/password account and you attempt to log-in with a social login account, that will create a new account and vice versa.
| * Email and password | ||
| * Social login (GitHub, Bitbucket) | ||
|
|
||
| To view your user account integrations, navigate to menu:User Settings[Account Integrations]. |
There was a problem hiding this comment.
I don't know if this sentence is necessary given what you have just below
There was a problem hiding this comment.
I'm coming back to this after having read the Organization section...
I almost feel like it's worth listing the available account integration types...
As in, as an explanation of what a user is and what are the available user integrations , not as an explanation specifically user settings page, if you know what I mean.
The goal here would be to ensure users understand that there are two types:
User (CircleCI) --> User (VCS) - typically called "authorization"
Org (CircleCI) --> Org (VCS) - typically called "connection" or "installation"
something like:
A CircleCI user account can be integrated with VCS user accounts via authorization.
- GitHub:
- GitHub Oauth app authorization: displayed in user settings > account integrations, managed in GitHub at https://github.com/settings/applications. Not mutually exclusive with GitHub App authorization
- Github App authorization: not displayed in user settings, if you are not "authorized" you will see a button in the top navbar that prompts you to authorize. Managed in GitHub at https://github.com/settings/apps/authorizations. Not mutually exclusive with OAuth app authorization - Bitbucket: Displayed in user settings > Account integrations, mutually exclusive with other VCS authorization, managed in bitbucket at [I know there is a page but I've just spent 15 minutes trying to access my broken bitbucket org]
- Gitlab: not displayed in user settings > Account integrations. Mutually exclusive with other VCS authorizaitons except GitHub App. Managed in Gitlab at https://gitlab.com/-/user_settings/applications
There was a problem hiding this comment.
(will get back to this later or we should talk sync)
| | User settings section | What you will find here | ||
|
|
||
| | Account Integrations | ||
| | Displays your user ID as well as account integrations with VCS providers. You will find a list of which GitHub or Bitbucket organizations you are connected with. You can disconnect your OAuth connections with GitHub or Bitbucket here. |
There was a problem hiding this comment.
Even though I hope we can solve this soon-ish, I think it's worth calling out that currently for GitHub there is only a component representing the "GitHub OAuth app" integration/authorization, not one representing the Authorization for the CircleCI GitHub App.
(I just opened a PR to change the component title from "GitHub" to "GitHub OAuth app"
| | Beta Program | ||
| | Opt in to CircleCI's beta program. Beta features you opt in to will be listed on this page. | ||
|
|
||
| |=== |
There was a problem hiding this comment.
For users that login with email/password there are two additional tabs, "Email" and "Password".
| Create an organization to manage the following: | ||
|
|
||
| * Multiple projects under a single entity. |
There was a problem hiding this comment.
This almost implies that creating an organization is optional and it's only used as "grouping". As in, it implies that if I wanted to I could build on a single project I can do that outside of an organization.
I think we a make it clearer that it's not the case.
I think "Create an organization to manage the following:" is what makes it sound optional, if you get what I mean?
There was a problem hiding this comment.
I almost would just drop this section, because the same content is expressed below in
Each organization has its own settings, including security, integrations, and resource management, allowing you to coordinate and control your CI/CD processes across multiple projects and users.
| Create an organization to manage the following: | ||
|
|
||
| * Multiple projects under a single entity. | ||
| * CI/CD pipelines specific to your team or company needs. | ||
| * Invites for team members. | ||
| * Assignment of roles (`circleci` orgs only, roles for `github` and `bitbucket` orgs are inherited and managed through the VCS provider). |
There was a problem hiding this comment.
also do the reader this line may be hard to get, since it comes before we present the 3 org types
|
|
||
| Each organization has its own settings, including security, integrations, and resource management, allowing you to coordinate and control your CI/CD processes across multiple projects and users. | ||
|
|
||
| A CircleCI _organization_ can be one of three types: |
There was a problem hiding this comment.
would we want to add here a link to how to tell the type of your org?
|
|
||
| A CircleCI _organization_ can be one of three types: | ||
|
|
||
| * `circleci`: This organization type is created separately to any VCS connection between CircleCI and your code repositories. Within a `circleci` organization you create projects and then connect them to your code repositories. |
There was a problem hiding this comment.
| * `circleci`: This organization type is created separately to any VCS connection between CircleCI and your code repositories. Within a `circleci` organization you create projects and then connect them to your code repositories. | |
| * `circleci`: This organization type exists independently of any VCS connection. Projects within a circleci organization are created in CircleCI first, then connected to your code repositories. |
| A CircleCI _organization_ can be one of three types: | ||
|
|
||
| * `circleci`: This organization type is created separately to any VCS connection between CircleCI and your code repositories. Within a `circleci` organization you create projects and then connect them to your code repositories. | ||
| * `github`: A `github` organization uses an OAuth app connection and is created when you log in to CircleCI using your GitHub account. Your GitHub repositories appear as projects that can be set up in CircleCI. |
There was a problem hiding this comment.
| * `github`: A `github` organization uses an OAuth app connection and is created when you log in to CircleCI using your GitHub account. Your GitHub repositories appear as projects that can be set up in CircleCI. | |
| * `github`: A `github` organization uses an OAuth app connection and is created when you log in to CircleCI using your GitHub account. Your GitHub repositories are imported as projects that can be set up in CircleCI. |
There was a problem hiding this comment.
actually I'm just thinking about the details... maybe something like this would be more precise, unless it's redundant because explained better elsewhere?
| * `github`: A `github` organization uses an OAuth app connection and is created when you log in to CircleCI using your GitHub account. Your GitHub repositories appear as projects that can be set up in CircleCI. | |
| * `github`: This organization type is created automatically when you authorize CircleCI to access your GitHub account via OAuth app (this happens automatically when you sign in with GitHub social login). Your GitHub repositories are imported as available projects in CircleCI. You cannot create projects that don't correspond to existing repositories in your GitHub personal account or organizations. |
|
|
||
| * `circleci`: This organization type is created separately to any VCS connection between CircleCI and your code repositories. Within a `circleci` organization you create projects and then connect them to your code repositories. | ||
| * `github`: A `github` organization uses an OAuth app connection and is created when you log in to CircleCI using your GitHub account. Your GitHub repositories appear as projects that can be set up in CircleCI. | ||
| * `bitbucket`: A `bitbucket` organization is created when you log in to CircleCI using your Bitbucket account. Your Bitbucket repositories appear as projects that can be set up in CircleCI. |
There was a problem hiding this comment.
Maybe something similar to the above here
Description
The main change in this PR is: Create new page: Users, organizations and integrations guide
Bring in all content from VCS integration pages into this one page and describe feature support byt user/org type/integration type/pipeline type.
Archive VCS-specific integration pages
This PR also includes many fixes for cross references which have had to be updated due to the move of all this content
Reasons
Why did you make these changes?
Content Checklist
Please follow our style when contributing to CircleCI docs. Our style guide is here: https://circleci.com/docs/style/style-guide-overview.
Please take a moment to check through the following items when submitting your PR (this is just a guide so will not be relevant for all PRs):