Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "EGit/GitHub/User Guide"
(→Editor) |
m (→Credentials) |
||
| (40 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
== Overview == | == Overview == | ||
| − | The EGit Mylyn connector supports creating task repositories for working with [http://www.github.com GitHub] issues and [http://gist.github.com Gists]. | + | The EGit Mylyn GitHub connector supports creating task repositories for working with [http://www.github.com GitHub] issues, pull requests, and [http://gist.github.com Gists]. A GitHub issue or PR task repository is required for each GitHub project repository you want to access issues or PRs for. A single Gist repository allows you to access all Gists on https://gist.github.com. |
| + | |||
| + | The latest version of the EGit Mylyn GitHub connector can be installed from following update site: | ||
| + | |||
| + | https://download.eclipse.org/egit/github/updates-nightly | ||
| + | |||
| + | == Getting Started== | ||
| + | The Mylyn GitHub connector supports bulk adding all your GitHub repositories to the [https://wiki.eclipse.org/Mylyn/User_Guide#Task_Repositories Mylyn Task Repositorities] view. | ||
| + | # Select '''File > Import...''' | ||
| + | # Select the ''GitHub Task Repositories'' node under the ''Tasks'' category | ||
| + | # Select '''Next''' | ||
| + | # Enter your GitHub credentials on the credentials wizard page | ||
| + | # Select '''Next''' | ||
| + | # Check all the GitHub repositories that you want to access issues from. | ||
| + | # Select '''Finish''' | ||
| + | # Open the ''Task Repositories'' view to browse the newly added task repositories and add queries or create new tasks. | ||
| + | |||
| + | Task repositories can also be added individually in the ''Task Repositories'' view. | ||
| + | |||
| + | === Credentials === | ||
| + | |||
| + | Historically, the EGit Mylyn GitHub connector has supported only username/password authentication. Since version 5.10, it also supports ''token authentication'', which is needed for working with accounts that have two-factor authentication enabled. As of November 13, 2020, GitHub also no longer accepts username/password authentication for API calls, so users always have to use token authentication. | ||
| + | |||
| + | To set up '''token authentication''', log-in via the GitHub web UI to your GitHub account, and create a '''[https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token personal access token]'''. Then enter the token in the Mylyn repository configuration: | ||
| + | |||
| + | [[File:EGit-GitHub Token Authentication.png|alt="Screenshot of a Mylyn 'GitHub Issues' task repository configuration dialog showing the token authentication settings."]] | ||
| + | |||
| + | This dialog shows up when you create a new Mylyn task repository, or when the ''Properties'' of an existing Mylyn task repository are shown. | ||
| + | |||
| + | * Check the "Use Access Token Authentication" checkbox. | ||
| + | * Copy the token value into the "Token" textbox. | ||
| + | * Check the "Save Token" checkbox. | ||
| + | * Click "Validate Settings" to verify that Eclipse can access the GitHub repository with this token. | ||
| + | * Save the configuration. | ||
| + | |||
| + | |||
| + | GitHub personal access tokens give you fine-grained control over what the token holder may do. This is done by assigning "scopes" to tokens. See the [https://docs.github.com/en/free-pro-team@latest/developers/apps/scopes-for-oauth-apps GitHub documentation] for the details. | ||
| + | |||
| + | Some hints: | ||
| + | * A token without scopes gives only ''read-only access to public information''. | ||
| + | * To get write access and access to private repositories your GitHub account has access to, set the '''repo''' scope for the token when you create it. | ||
| + | * To be able to create Gists, also set the '''gist''' scope. | ||
| + | |||
| + | |||
| + | For issue and PR repositories, a user name need not be given when token authentication is used, and the "User ID" field in the dialog becomes read-only. For Gists, the user name is still required. | ||
== Issues == | == Issues == | ||
| Line 10: | Line 54: | ||
* Assignee | * Assignee | ||
* Labels | * Labels | ||
| − | Note that when multiple filters are used in the same query the returned issues match '''all''' of the filters. | + | Note that when multiple filters are used in the same query the returned issues will match '''all''' of the filters. The minimum required for a valid query is at least one status selected and a non-empty title. |
| + | |||
| + | [[Image:GitHubMylynIssueQueryPage.png|center]] | ||
| + | === Issue Editor === | ||
| + | The GitHub issue task editor supports the following: | ||
| + | * Editing the title & description | ||
| + | * Adding a new comment | ||
| + | * Closing & reopening the issue from the ''Actions'' section | ||
| + | * Assigning the issue to someone from the ''People'' section | ||
| + | * Adding and removing labels from the ''Attributes'' section | ||
| + | * Updating the milestone from the ''Attributes'' section | ||
| + | [[Image:GitHubMylynIssueEditor.png|center]] | ||
== Gists == | == Gists == | ||
=== Creating === | === Creating === | ||
| − | Gists can be created by selecting text in a editor or files in an explorer and selecting the '''Create Gist''' context menu. | + | Gists can be created by selecting text in a editor or files in an explorer and selecting either the ''GitHub'' > '''Create Private Gist''' or ''GitHub'' > '''Create Public Gist''' context menu. The Gist will be created in a background job and a notification popup will display with a link to open the newly created Gist. |
=== Queries === | === Queries === | ||
| − | Gist queries only support filtering by a specified GitHub | + | Gist queries only support filtering by a specified GitHub login name. |
| − | === | + | === Gist Editor === |
The task editor for Gists supports the following: | The task editor for Gists supports the following: | ||
| − | * | + | * Editing the description |
| − | * | + | * Adding a new comment |
| − | * Opening the files in a gist | + | * Opening the files in a gist in an editor |
| + | * Adding new files to the gist | ||
| + | * Replacing the content of a file currently in the gist | ||
| + | * Cloning the gist to a local Eclipse project | ||
| + | [[Image:GitHubMylynGistEditor.png|center]] | ||
| + | |||
| + | == Frequently Asked Questions (FAQ) == | ||
| + | * Does the connector support GitHub tokens? | ||
| + | ** '''Yes''', GitHub personal access tokens (PAT) are supported since version 5.10. See [[#Credentials|Credentials]] above. | ||
| + | * Are GitHub API requests made over HTTPS? | ||
| + | ** '''Yes''', all requests made through the GitHub API are over HTTPS. | ||
Latest revision as of 03:11, 6 October 2020
Contents
Overview
The EGit Mylyn GitHub connector supports creating task repositories for working with GitHub issues, pull requests, and Gists. A GitHub issue or PR task repository is required for each GitHub project repository you want to access issues or PRs for. A single Gist repository allows you to access all Gists on https://gist.github.com.
The latest version of the EGit Mylyn GitHub connector can be installed from following update site:
https://download.eclipse.org/egit/github/updates-nightly
Getting Started
The Mylyn GitHub connector supports bulk adding all your GitHub repositories to the Mylyn Task Repositorities view.
- Select File > Import...
- Select the GitHub Task Repositories node under the Tasks category
- Select Next
- Enter your GitHub credentials on the credentials wizard page
- Select Next
- Check all the GitHub repositories that you want to access issues from.
- Select Finish
- Open the Task Repositories view to browse the newly added task repositories and add queries or create new tasks.
Task repositories can also be added individually in the Task Repositories view.
Credentials
Historically, the EGit Mylyn GitHub connector has supported only username/password authentication. Since version 5.10, it also supports token authentication, which is needed for working with accounts that have two-factor authentication enabled. As of November 13, 2020, GitHub also no longer accepts username/password authentication for API calls, so users always have to use token authentication.
To set up token authentication, log-in via the GitHub web UI to your GitHub account, and create a personal access token. Then enter the token in the Mylyn repository configuration:
This dialog shows up when you create a new Mylyn task repository, or when the Properties of an existing Mylyn task repository are shown.
- Check the "Use Access Token Authentication" checkbox.
- Copy the token value into the "Token" textbox.
- Check the "Save Token" checkbox.
- Click "Validate Settings" to verify that Eclipse can access the GitHub repository with this token.
- Save the configuration.
GitHub personal access tokens give you fine-grained control over what the token holder may do. This is done by assigning "scopes" to tokens. See the GitHub documentation for the details.
Some hints:
- A token without scopes gives only read-only access to public information.
- To get write access and access to private repositories your GitHub account has access to, set the repo scope for the token when you create it.
- To be able to create Gists, also set the gist scope.
For issue and PR repositories, a user name need not be given when token authentication is used, and the "User ID" field in the dialog becomes read-only. For Gists, the user name is still required.
Issues
Queries
GitHub issue task repositories support creating queries that filter by the following fields:
- State (open or closed)
- Milestones
- Mentions
- Assignee
- Labels
Note that when multiple filters are used in the same query the returned issues will match all of the filters. The minimum required for a valid query is at least one status selected and a non-empty title.
Issue Editor
The GitHub issue task editor supports the following:
- Editing the title & description
- Adding a new comment
- Closing & reopening the issue from the Actions section
- Assigning the issue to someone from the People section
- Adding and removing labels from the Attributes section
- Updating the milestone from the Attributes section
Gists
Creating
Gists can be created by selecting text in a editor or files in an explorer and selecting either the GitHub > Create Private Gist or GitHub > Create Public Gist context menu. The Gist will be created in a background job and a notification popup will display with a link to open the newly created Gist.
Queries
Gist queries only support filtering by a specified GitHub login name.
Gist Editor
The task editor for Gists supports the following:
- Editing the description
- Adding a new comment
- Opening the files in a gist in an editor
- Adding new files to the gist
- Replacing the content of a file currently in the gist
- Cloning the gist to a local Eclipse project
Frequently Asked Questions (FAQ)
- Does the connector support GitHub tokens?
- Yes, GitHub personal access tokens (PAT) are supported since version 5.10. See Credentials above.
- Are GitHub API requests made over HTTPS?
- Yes, all requests made through the GitHub API are over HTTPS.