GitHub Concepts: Difference between revisions
| (84 intermediate revisions by the same user not shown) | |||
| Line 2: | Line 2: | ||
* [[GitHub#Subjects|GitHub]] | * [[GitHub#Subjects|GitHub]] | ||
=Repository= | |||
{{External|https://docs.github.com/en/repositories/creating-and-managing-repositories/about-repositories}} | |||
The elements fully identifying a repository within GitHub are: | |||
[[File:github_owner_repository_name.png]] | |||
==Owner== | |||
The owner can be an organization or an individual user. | |||
==Repository Name== | |||
The repository name may not contain slashes. | |||
=User= | |||
{{External|https://docs.github.com/en/rest/users/users}} | |||
==Authenticated User== | |||
{{External|https://docs.github.com/en/rest/users/users#get-the-authenticated-user}} | |||
=Webhooks= | =Webhooks= | ||
{{External|https://developer.github.com/webhooks/}} | {{External|https://developer.github.com/webhooks/}} | ||
{{External|https://docs.github.com/en/enterprise-server@3.3/developers/webhooks-and-events/webhooks/about-webhooks}} | |||
A webhook is a mechanism that triggers a HTTP POST invocation into the webhook's external URL, every time a specific event occurs. | A webhook is a mechanism that triggers a HTTP POST invocation into the webhook's external URL, every time a specific event occurs. | ||
| Line 17: | Line 33: | ||
[[OpenShift_Build_and_Deploy_a_JEE_Application_with_S2I#Create_the_Application|Used by OpenShift]] for its S2I build strategy. | [[OpenShift_Build_and_Deploy_a_JEE_Application_with_S2I#Create_the_Application|Used by OpenShift]] for its S2I build strategy. | ||
=Pull-Request= | =<span id='Pull-Request'></span>Pull Request (PR)= | ||
Usually, a pull request is initiated from a [[ | {{External|https://help.github.com/en/articles/creating-a-pull-request}} | ||
<span id='Base_Branch_for_PR'></span>Usually, a pull request is initiated from a [[Gitflow_Concepts#Feature_Branch|feature branch]] and indicates the intent to merge into the base branch. Within the context of a pull request, the base branch is the branch the PR changes will be merged into. It is possible to initiate pull requests from a previously cloned repository as well. | |||
The pull requests have to be reviewed, approved and explicitly applied by the owner of the parent repository. | The pull requests have to be reviewed, approved and explicitly applied by the owner of the parent repository. | ||
A '''reviewer''' is a person you want to review your code. It is not necessarily a person responsible for the specific area the PR applies to, or responsible for merging the commit. However it is a good idea to co-opt as reviewer a person who worked with that code before. When assigning a "reviewer", make sure to click the "Request" link at the right of the reviewer's name. | |||
An '''assignee''' is usually the PR opener, who normally is also the person responsible with merging the PR after consent from reviewer(s). | |||
Also see [[Git_Concepts#Clone|Git cloning]]. | Also see [[Git_Concepts#Clone|Git cloning]]. | ||
<span id='PR_States'></span>A pull request can be in an '''open''' or '''closed''' state. A '''merged''' PR is automatically '''closed'''. To figure out programmatically whether a PR was merged, use <code>GET /repos/{owner}/{repo}/pulls/{pull_number}/merge</code>. For more details see: https://docs.github.com/en/rest/pulls/pulls?apiVersion=2022-11-28#check-if-a-pull-request-has-been-merged. | |||
==PR Procedures== | |||
{{Internal|GitHub_Procedures#Pull_Request_Procedures|Pull Request Procedures}} | |||
==Required Reviews for Pull Requests== | ==Required Reviews for Pull Requests== | ||
{{External|[https://help.github.com/en/articles/enabling-required-reviews-for-pull-requests Required Reviews for Pull Requests]}} | |||
==Programatic PR Access with Python== | |||
{{Internal|Python_Package_PyGithub#Pull_Requests_.28PRs.29|Programatic PR Access with Python}} | |||
==Status Checks== | |||
{{External|https://docs.github.com/en/enterprise-server@3.7/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks}} | |||
Status checks are based on '''external''' processes (CI builds) that are triggered by GitHub events. A status check can be "pending", "passing" or "failing". | |||
===Requiring Status Checks Before Merging=== | |||
{{External|https://docs.github.com/en/enterprise-server@3.7/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging}} | |||
Branches → Branch protection rules → Select the branch → Edit → Check "Require status checks to pass before merging" | |||
=<span id='Code_Owners'></span><span id='CODEOWNERS'></span>Code Owners (CODEOWNERS)= | |||
{{External|https://help.github.com/en/articles/about-code-owners}} | |||
For CODEOWNERS mechanism to kick in, and PR reviews to be requested in from code owners: | |||
1. CODEOWNERS must exists in the root, <code>docs/</code> or <code>.github/</code> of the repository, on the branch the PR is made against. Example: | |||
<syntaxhighlight lang='text'> | |||
* @<owner> | |||
</syntaxhighlight> | |||
Where <code>owner</code> can be an individual account or a team. | |||
Teams are identified in the format <code>@org/team-name</code>. Team must have explicit write access to repository. | |||
2. The branch must be "protected", and have "Require review from Code Owners" enabled. | |||
3. The code owners (groups or individuals) must be listed among "Collaborators & teams". Teams must have explicit write access to repository. <font color=darkkhaki>How about individual accounts?</font> | |||
=Protected Branch= | =Protected Branch= | ||
=Personal Access Token= | =Security= | ||
{{External|https://docs.github.com/en/authentication/keeping-your-account-and-data-secure}} | |||
==Authentication== | |||
An user accessing GitHub is in the position to authenticate in the following situations: when using a [[#Browser_Authentication|browser]], when using the [[#CLI_Authentication|CLI]], when using the [[#API_Authentication|API]] and when using [[#GitHub_Desktop_Authentication|GitHub Desktop]]. | |||
===Browser Authentication=== | |||
===CLI Authentication=== | |||
{{External|https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-authentication-to-github#authenticating-with-the-command-line}} | |||
{{External|https://cli.github.com/manual/gh_auth_login}} | |||
===API Authentication=== | |||
===GitHub Desktop Authentication=== | |||
==Deploy Key== | |||
==Personal Access Token== | |||
{{External|https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line}} | {{External|https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line}} | ||
=OAuth Token= | A personal access token is a piece of information that <font color=darkgray>more here... </font>. GitHub grants access to whoever makes a HTTPS invocation and presents this token: it function like an ordinary OAuth access token. It also can be used instead of a password for Git over HTTPS, or can be used to authenticate to the API over Basic Authentication. Git API access is allowed in presence of the tocken. A personal access token is similar to a password, in that they should be protected carefully. They are usually though placed in scripts, when building automated CI/CD pipelines. The advantage of using a token instead of a password is that the tokens can be revoked, can be proactively rotated, and then a lot of them can be created. | ||
The list of already generated tokens can be obtained at https://github.com/settings/tokens (account -> Settings -> Developer settings -> Personal access tokens. | |||
Operations: {{Internal|GitHub_Procedures#Create_a_Personal_Access_Token_for_Command_Line|Create a Personal Access Token for Command Line}} | |||
==OAuth Support== | |||
{{External|https://developer.github.com/v3/oauth_authorizations}} | |||
GitHub's OAuth implementation supports the standard authorization code grant type (https://tools.ietf.org/html/rfc6749#section-4.1). | |||
===OAuth Token=== | |||
{{External|https://help.github.com/en/articles/git-automation-with-oauth-tokens}} | {{External|https://help.github.com/en/articles/git-automation-with-oauth-tokens}} | ||
=OAuth | ===OAuth App=== | ||
{{External|https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/}} | {{External|https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/}} | ||
==Privileges== | |||
===Admin=== | |||
===Write=== | |||
===Read=== | |||
=Query Language= | |||
{{External|https://help.github.com/en/github/searching-for-information-on-github/understanding-the-search-syntax}} | |||
is:pr | |||
author:ovidiuf | |||
PRs merged between a certain date range: | |||
is:pr author:ovidiuf merged:2020-03-16..2020-03-21 | |||
=Organization= | |||
=Actions= | |||
{{Internal|GitHub Actions#Overview|GitHub Actions}} | |||
=Images= | |||
The "natural" width for GitHub Markdown images seems to be 7.65 inches, while saved at 42 pixels/inch. This results in an image 833 pixels wide. | |||
[[File:OpenOffice_Save.png|903px]] | |||
=Text Width= | |||
==Text Width in Markdown Documents== | |||
The optimal code text width is 94. | |||
<font size=-1> | |||
10| 20| 30| 40| 50| 60| 70| 80| 90|94| | |||
1234567890|234567890|234567890|234567890|234567890|234567890|234567890|234567890|234567890|234 | |||
</font> | |||
==Text Width in Code== | |||
148 (normally 160, but the diffs wrap around for 160) | |||
<font size=-1> | |||
# 10| 20| 30| 40| 50| 60| 70| 80| 90| 100| 110| 120| 130| 140| 148 | |||
#234567890|234567890|234567890|234567890|234567890|234567890|234567890|234567890|234567890|234567890|234567890|234567890|234567890|234567890|2345678 | |||
</font> | |||
=<span id='GitHub App'></span>GitHub Apps= | |||
{{External|https://docs.github.com/en/developers/apps/getting-started-with-apps}} | |||
=GitHub Issues= | |||
=GitHub Classic Projects= | |||
{{Internal|GitHub Classic Projects#Overview|GitHub Classic Projects}} | |||
=GitHub Projects= | |||
{{Internal|GitHub Projects#Overview|GitHub Projects}} | |||
=GitHub Flow= | |||
{{Internal|GitHub Flow|GitHub Flow}} | |||
Latest revision as of 01:02, 6 March 2024
Internal
Repository
The elements fully identifying a repository within GitHub are:
Owner
The owner can be an organization or an individual user.
Repository Name
The repository name may not contain slashes.
User
Authenticated User
Webhooks
A webhook is a mechanism that triggers a HTTP POST invocation into the webhook's external URL, every time a specific event occurs.
A webhook can be installed on an organization or on a specific repository. Once installed, it will be triggered each time one or more subscribed events happen in that organization/repository.
Can be set via UI: Repository -> Settings -> Options: Webhooks.
Webhook Secret
Used by OpenShift for its S2I build strategy.
Pull Request (PR)
Usually, a pull request is initiated from a feature branch and indicates the intent to merge into the base branch. Within the context of a pull request, the base branch is the branch the PR changes will be merged into. It is possible to initiate pull requests from a previously cloned repository as well.
The pull requests have to be reviewed, approved and explicitly applied by the owner of the parent repository.
A reviewer is a person you want to review your code. It is not necessarily a person responsible for the specific area the PR applies to, or responsible for merging the commit. However it is a good idea to co-opt as reviewer a person who worked with that code before. When assigning a "reviewer", make sure to click the "Request" link at the right of the reviewer's name.
An assignee is usually the PR opener, who normally is also the person responsible with merging the PR after consent from reviewer(s).
Also see Git cloning.
A pull request can be in an open or closed state. A merged PR is automatically closed. To figure out programmatically whether a PR was merged, use GET /repos/{owner}/{repo}/pulls/{pull_number}/merge. For more details see: https://docs.github.com/en/rest/pulls/pulls?apiVersion=2022-11-28#check-if-a-pull-request-has-been-merged.
PR Procedures
Required Reviews for Pull Requests
Programatic PR Access with Python
Status Checks
Status checks are based on external processes (CI builds) that are triggered by GitHub events. A status check can be "pending", "passing" or "failing".
Requiring Status Checks Before Merging
Branches → Branch protection rules → Select the branch → Edit → Check "Require status checks to pass before merging"
Code Owners (CODEOWNERS)
For CODEOWNERS mechanism to kick in, and PR reviews to be requested in from code owners:
1. CODEOWNERS must exists in the root, docs/ or .github/ of the repository, on the branch the PR is made against. Example:
* @<owner>
Where owner can be an individual account or a team.
Teams are identified in the format @org/team-name. Team must have explicit write access to repository.
2. The branch must be "protected", and have "Require review from Code Owners" enabled.
3. The code owners (groups or individuals) must be listed among "Collaborators & teams". Teams must have explicit write access to repository. How about individual accounts?
Protected Branch
Security
Authentication
An user accessing GitHub is in the position to authenticate in the following situations: when using a browser, when using the CLI, when using the API and when using GitHub Desktop.
Browser Authentication
CLI Authentication
API Authentication
GitHub Desktop Authentication
Deploy Key
Personal Access Token
A personal access token is a piece of information that more here... . GitHub grants access to whoever makes a HTTPS invocation and presents this token: it function like an ordinary OAuth access token. It also can be used instead of a password for Git over HTTPS, or can be used to authenticate to the API over Basic Authentication. Git API access is allowed in presence of the tocken. A personal access token is similar to a password, in that they should be protected carefully. They are usually though placed in scripts, when building automated CI/CD pipelines. The advantage of using a token instead of a password is that the tokens can be revoked, can be proactively rotated, and then a lot of them can be created.
The list of already generated tokens can be obtained at https://github.com/settings/tokens (account -> Settings -> Developer settings -> Personal access tokens.
Operations:
OAuth Support
GitHub's OAuth implementation supports the standard authorization code grant type (https://tools.ietf.org/html/rfc6749#section-4.1).
OAuth Token
OAuth App
Privileges
Admin
Write
Read
Query Language
is:pr
author:ovidiuf
PRs merged between a certain date range:
is:pr author:ovidiuf merged:2020-03-16..2020-03-21
Organization
Actions
Images
The "natural" width for GitHub Markdown images seems to be 7.65 inches, while saved at 42 pixels/inch. This results in an image 833 pixels wide.
Text Width
Text Width in Markdown Documents
The optimal code text width is 94.
10| 20| 30| 40| 50| 60| 70| 80| 90|94| 1234567890|234567890|234567890|234567890|234567890|234567890|234567890|234567890|234567890|234
Text Width in Code
148 (normally 160, but the diffs wrap around for 160)
# 10| 20| 30| 40| 50| 60| 70| 80| 90| 100| 110| 120| 130| 140| 148 #234567890|234567890|234567890|234567890|234567890|234567890|234567890|234567890|234567890|234567890|234567890|234567890|234567890|234567890|2345678