GitHub Concepts: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(60 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)=


{{External|https://help.github.com/en/articles/creating-a-pull-request}}
{{External|https://help.github.com/en/articles/creating-a-pull-request}}


Usually, a pull request is initiated from a [[Git-flow#Feature_Branch|feature branch]] and indicates the intent to merge with the [[Git-flow#Develop_Branch|develop branch]]. It is possible to initiate pull requests from a previously cloned repository as well.
<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.
Line 31: Line 47:
Also see [[Git_Concepts#Clone|Git cloning]].
Also see [[Git_Concepts#Clone|Git cloning]].


Also see: {{Internal|GitHub_Procedures#Pull_Request_Procedures|Pull Request Procedures}}
<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}}


{{External|[https://help.github.com/en/articles/enabling-required-reviews-for-pull-requests Required Reviews for Pull Requests]}}
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.


=Code Owners=
2. The branch must be "protected", and have "Require review from Code Owners" enabled.


{{External|[https://help.github.com/en/articles/about-code-owners Code Owners]}}
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=


=Security=
=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==
==Personal Access Token==


Line 54: Line 107:


Operations: {{Internal|GitHub_Procedures#Create_a_Personal_Access_Token_for_Command_Line|Create a Personal Access Token for Command Line}}
Operations: {{Internal|GitHub_Procedures#Create_a_Personal_Access_Token_for_Command_Line|Create a Personal Access Token for Command Line}}
==GitHub App==


==OAuth Support==
==OAuth Support==
Line 70: Line 121:


{{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

https://docs.github.com/en/repositories/creating-and-managing-repositories/about-repositories

The elements fully identifying a repository within GitHub are:

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

https://docs.github.com/en/rest/users/users

Authenticated User

https://docs.github.com/en/rest/users/users#get-the-authenticated-user

Webhooks

https://developer.github.com/webhooks/
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 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)

https://help.github.com/en/articles/creating-a-pull-request

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

Pull Request Procedures

Required Reviews for Pull Requests

Required Reviews for Pull Requests

Programatic PR Access with Python

Programatic PR Access with Python

Status Checks

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

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"

Code Owners (CODEOWNERS)

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, 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

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, when using the CLI, when using the API and when using GitHub Desktop.

Browser Authentication

CLI Authentication

https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-authentication-to-github#authenticating-with-the-command-line
https://cli.github.com/manual/gh_auth_login

API Authentication

GitHub Desktop Authentication

Deploy Key

Personal Access Token

https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line

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:

Create a Personal Access Token for Command Line

OAuth Support

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

https://help.github.com/en/articles/git-automation-with-oauth-tokens

OAuth App

https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/

Privileges

Admin

Write

Read

Query Language

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

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.

OpenOffice Save.png

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

GitHub Apps

https://docs.github.com/en/developers/apps/getting-started-with-apps

GitHub Issues

GitHub Classic Projects

GitHub Classic Projects

GitHub Projects

GitHub Projects

GitHub Flow

GitHub Flow