此内容没有您所选择的语言版本。
Chapter 2. User onboarding
If your organization is already running a OpenShift Dev Spaces instance, you can get started as a new user by learning how to start a new workspace, manage your workspaces, and authenticate yourself to a Git server from a workspace:
2.1. Starting a new workspace with a clone of a Git repository
Working with OpenShift Dev Spaces in your browser involves multiple URLs:
- The URL of your organization’s OpenShift Dev Spaces instance, used as part of all the following URLs
- The URL of the Workspaces page of your OpenShift Dev Spaces dashboard with the workspace control panel
- The URLs for starting a new workspace
- The URLs of your workspaces in use
With OpenShift Dev Spaces, you can visit a URL in your browser to start a new workspace that contains a clone of a Git repository. This way, you can clone a Git repository that is hosted on GitHub, a GitLab instance, or a Bitbucket server.
You can also use the Git Repo URL * field on the Create Workspace page of your OpenShift Dev Spaces dashboard to enter the URL of a Git repository to start a new workspace.
Prerequisites
- Your organization has a running instance of OpenShift Dev Spaces.
-
You know the FQDN URL of your organization’s OpenShift Dev Spaces instance:
https://devspaces-<openshift_deployment_name>.<domain_name>
. - Optional: You have authentication to the Git server configured.
Your Git repository maintainer keeps the
devfile.yaml
or.devfile.yaml
file in the root directory of the Git repository. (For alternative file names and file paths, see Section 2.2, “Optional parameters for the URLs for starting a new workspace”.)TipYou can also start a new workspace by supplying the URL of a Git repository that contains no devfile. Doing so results in a workspace with the Che-Theia IDE and the Universal Developer Image.
Procedure
To start a new workspace with a clone of a Git repository:
- Optional: Visit your OpenShift Dev Spaces dashboard pages to authenticate to your organization’s instance of OpenShift Dev Spaces.
Visit the URL to start a new workspace using the basic syntax:
https://devspaces-<openshift_deployment_name>.<domain_name>#<git_repository_url>
TipYou can extend this URL with optional parameters:
https://devspaces-<openshift_deployment_name>.<domain_name>#<git_repository_url>?<optional_parameters> 1
Example 2.1. A URL for starting a new workspace
https://devspaces-<openshift_deployment_name>.<domain_name>#https://github.com/che-samples/cpp-hello-world
Example 2.2. The URL syntax for starting a new workspace with a clone of a GitHub-hosted repository
With GitHub and GitLab, you can even use the URL of a specific branch of the repository to be cloned:
-
https://devspaces-<openshift_deployment_name>.<domain_name>#https://github.com/<user_or_org>/<repository>
starts a new workspace with a clone of the default branch. -
https://devspaces-<openshift_deployment_name>.<domain_name>#https://github.com/<user_or_org>/<repository>/tree/<branch_name>
starts a new workspace with a clone of the specified branch. -
https://devspaces-<openshift_deployment_name>.<domain_name>#https://github.com/<user_or_org>/<repository>/pull/<pull_request_id>
starts a new workspace with a clone of the branch of the pull request.
After you enter the URL to start a new workspace in a browser tab, it renders the workspace-starting page.
When the new workspace is ready, the workspace IDE loads in the browser tab.
A clone of the Git repository is present in the filesystem of the new workspace.
The workspace has a unique URL:
https://devspaces-<openshift_deployment_name>.<domain_name>#workspace<unique_url>
.-
Although this is not possible in the address bar, you can add a URL for starting a new workspace as a bookmark by using the browser bookmark manager:
- In Mozilla Firefox, go to ☰ > Bookmarks > Manage bookmarks Ctrl+Shift+O > Bookmarks Toolbar > Organize > Add bookmark.
- In Google Chrome, go to ⋮ > Bookmarks > Bookmark manager > Bookmarks bar > ⋮ > Add new bookmark.
2.2. Optional parameters for the URLs for starting a new workspace
When you start a new workspace, OpenShift Dev Spaces configures the workspace according to the instructions in the devfile. When you use a URL to start a new workspace, you can append optional parameters to the URL that further configure the workspace. You can use these parameters to specify a workspace IDE, start duplicate workspaces, and specify a devfile file name or path.
2.2.1. URL parameter concatenation
The URL for starting a new workspace supports concatenation of multiple optional URL parameters by using &
with the following URL syntax:
https://devspaces-<openshift_deployment_name>.<domain_name>#<git_repository_url>?<url_parameter_1>&<url_parameter_2>&<url_parameter_3>
Example 2.3. A URL for starting a new workspace with the URL of a Git repository and optional URL parameters
The complete URL for the browser:
https://devspaces-<openshift_deployment_name>.<domain_name>#https://github.com/che-samples/cpp-hello-world?new&che-editor=che-incubator/intellij-community/latest&devfilePath=tests/testdevfile.yaml
Explanation of the parts of the URL:
https://devspaces-<openshift_deployment_name>.<domain_name> 1 #https://github.com/che-samples/cpp-hello-world 2 ?new&che-editor=che-incubator/intellij-community/latest&devfilePath=tests/testdevfile.yaml 3
2.2.2. URL parameter for the workspace IDE
If the URL for starting a new workspace doesn’t contain a URL parameter specifying the integrated development environment (IDE), the workspace loads with the default IDE: Che Theia.
The URL parameter for specifying another supported IDE is che-editor=<editor_key>
:
https://devspaces-<openshift_deployment_name>.<domain_name>#<git_repository_url>?che-editor=<editor_key>
IDE | <editor_key> value | Note |
---|---|---|
|
Default editor when the URL parameter or | |
| ||
|
2.2.3. URL parameter for starting duplicate workspaces
Visiting a URL for starting a new workspace results in a new workspace according to the devfile and with a clone of the linked Git repository.
In some situations, you may need to have multiple workspaces that are duplicates in terms of the devfile and the linked Git repository. You can do this by visiting the same URL for starting a new workspace with a URL parameter.
The URL parameter for starting a duplicate workspace is new
:
https://devspaces-<openshift_deployment_name>.<domain_name>#<git_repository_url>?new
If you currently have a workspace that you started using a URL, then visiting the URL again without the new
URL parameter results in an error message.
2.2.4. URL parameter for the devfile file name
When you visit a URL for starting a new workspace, OpenShift Dev Spaces searches the linked Git repository for a devfile with the file name .devfile.yaml
or devfile.yaml
. The devfile in the linked Git repository must follow this file-naming convention.
In some situations, you may need to specify a different, unconventional file name for the devfile.
The URL parameter for specifying an unconventional file name of the devfile is df=<filename>.yaml
:
https://devspaces-<openshift_deployment_name>.<domain_name>#<git_repository_url>?df=<filename>.yaml 1
- 1
<filename>.yaml
is an unconventional file name of the devfile in the linked Git repository.
The df=<filename>.yaml
parameter also has a long version: devfilePath=<filename>.yaml
.
2.2.5. URL parameter for the devfile file path
When you visit a URL for starting a new workspace, OpenShift Dev Spaces searches the root directory of the linked Git repository for a devfile with the file name .devfile.yaml
or devfile.yaml
. The file path of the devfile in the linked Git repository must follow this path convention.
In some situations, you may need to specify a different, unconventional file path for the devfile in the linked Git repository.
The URL parameter for specifying an unconventional file path of the devfile is devfilePath=<relative_file_path>
:
https://devspaces-<openshift_deployment_name>.<domain_name>#<git_repository_url>?devfilePath=<relative_file_path> 1
- 1
<relative_file_path>
is an unconventional file path of the devfile in the linked Git repository.
2.3. Basic actions you can perform on a workspace
You manage your workspaces and verify their current states in the Workspaces page (https://devspaces-<openshift_deployment_name>.<domain_name>/dashboard/#/workspaces
) of your OpenShift Dev Spaces dashboard.
After you start a new workspace, you can perform the following actions on it in the Workspaces page:
Action | GUI steps in the Workspaces page |
---|---|
Reopen a running workspace | Click Open. |
Restart a running workspace | Go to ⋮ > Restart Workspace. |
Stop a running workspace | Go to ⋮ > Stop Workspace. |
Start a stopped workspace | Click Open. |
Delete a workspace | Go to ⋮ > Delete Workspace. |
2.4. Authenticating to a Git server from a workspace
In a workspace, you can run Git commands that require user authentication like cloning a remote private Git repository or pushing to a remote public or private Git repository.
User authentication to a Git server from a workspace can be configured by the administrator or user:
- Your administrator sets up an OAuth application on GitHub, GitLab, or Bitbucket for your organization’s Red Hat OpenShift Dev Spaces instance.
- As a user, you create and apply your own Kubernetes Secrets for your Git credentials store and access token.