diff --git a/content/actions/learn-github-actions/expressions.md b/content/actions/learn-github-actions/expressions.md index 5bfcf61e63..d13a71110b 100644 --- a/content/actions/learn-github-actions/expressions.md +++ b/content/actions/learn-github-actions/expressions.md @@ -29,7 +29,7 @@ You need to use specific syntax to tell {% data variables.product.prodname_dotco {% data reusables.actions.context-injection-warning %} -#### Example expression in an `if` conditional +### Example expression in an `if` conditional ```yaml steps: @@ -37,7 +37,7 @@ steps: if: {% raw %}${{ }}{% endraw %} ``` -#### Example setting an environment variable +### Example setting an environment variable {% raw %} ```yaml @@ -57,7 +57,7 @@ As part of an expression, you can use `boolean`, `null`, `number`, or `string` d | `number` | Any number format supported by JSON. | | `string` | You don't need to enclose strings in `{% raw %}${{{% endraw %}` and `{% raw %}}}{% endraw %}`. However, if you do, you must use single quotes (`'`) around the string. To use a literal single quote, escape the literal single quote using an additional single quote (`''`). Wrapping with double quotes (`"`) will throw an error. | -#### Example +### Example {% raw %} diff --git a/content/admin/enterprise-management/configuring-clustering/monitoring-cluster-nodes.md b/content/admin/enterprise-management/configuring-clustering/monitoring-cluster-nodes.md index 15dc0e2fa2..d0e268ab30 100644 --- a/content/admin/enterprise-management/configuring-clustering/monitoring-cluster-nodes.md +++ b/content/admin/enterprise-management/configuring-clustering/monitoring-cluster-nodes.md @@ -87,7 +87,8 @@ You can configure [Nagios](https://www.nagios.org/) to monitor {% data variables ``` 6. Create a command definition in your Nagios configuration. - ###### Example definition + + **Example definition** ``` define command { @@ -97,7 +98,7 @@ You can configure [Nagios](https://www.nagios.org/) to monitor {% data variables ``` 7. Add this command to a service definition for a node in the {% data variables.product.prodname_ghe_server %} cluster. - ###### Example definition + **Example definition** ``` define host{ diff --git a/content/admin/enterprise-management/monitoring-your-appliance/monitoring-using-snmp.md b/content/admin/enterprise-management/monitoring-your-appliance/monitoring-using-snmp.md index 9c3f478189..eaac0267e8 100644 --- a/content/admin/enterprise-management/monitoring-your-appliance/monitoring-using-snmp.md +++ b/content/admin/enterprise-management/monitoring-your-appliance/monitoring-using-snmp.md @@ -70,9 +70,9 @@ If you enable SNMP v3, you can take advantage of increased user based security t ![Button to add SNMP v3 user](/assets/images/enterprise/management-console/snmpv3-adduser.png) {% data reusables.enterprise_management_console.save-settings %} -#### Querying SNMP data +### Querying SNMP data -Both hardware and software-level information about your appliance is available with SNMP v3. Due to the lack of encryption and privacy for the `noAuthNoPriv` and `authNoPriv` security levels, we exclude the `hrSWRun` table (1.3.6.1.2.1.25.4) from the resulting SNMP reports. We include this table if you're using the `authPriv` security level. For more information, see the "[OID reference documentation](https://oidref.com/1.3.6.1.2.1.25.4)." +Both hardware and software-level information about your appliance is available with SNMP v3. Due to the lack of encryption and privacy for the `noAuthNoPriv` and `authNoPriv` security levels, we exclude the `hrSWRun` table (1.3.6.1.2.1.25.4) from the resulting SNMP reports. We include this table if you're using the `authPriv` security level. For more information, see the "[OID reference documentation](https://oidref.com/1.3.6.1.2.1.25.4)." With SNMP v2c, only hardware-level information about your appliance is available. The applications and services within {% data variables.product.prodname_enterprise %} do not have OIDs configured to report metrics. Several MIBs are available, which you can see by running `snmpwalk` on a separate workstation with SNMP support in your network: diff --git a/content/developers/apps/building-github-apps/authenticating-with-github-apps.md b/content/developers/apps/building-github-apps/authenticating-with-github-apps.md index 3787123481..a47ecb0655 100644 --- a/content/developers/apps/building-github-apps/authenticating-with-github-apps.md +++ b/content/developers/apps/building-github-apps/authenticating-with-github-apps.md @@ -23,7 +23,7 @@ Authenticating as a {% data variables.product.prodname_github_app %} is required * Retrieve high-level management information about your {% data variables.product.prodname_github_app %}. * Request access tokens for an installation of the app, allowing you to make API calls without a signed-in user. -To authenticate as a {% data variables.product.prodname_github_app %}, [generate a private key](#generating-a-private-key) in PEM format and download it to your local machine. You'll use this key to [sign a JSON Web Token (JWT)](#jwt-payload) and encode it using the `RS256` algorithm. {% data variables.product.product_name %} validates your app's identity by verifying the token with the app's stored public key. You'll exchange this JWT for an installation token, used to authenticate your app as a specific installation. +To authenticate as a {% data variables.product.prodname_github_app %}, [generate a private key](#generating-a-private-key) in PEM format and download it to your local machine. You'll use this key to [sign a JSON Web Token (JWT)](#jwt-payload) and encode it using the `RS256` algorithm. {% data variables.product.product_name %} validates your app's identity by verifying the token with the app's stored public key. You'll exchange this JWT for an installation token, used to authenticate your app as a specific installation. ### Listing the installations for an app @@ -42,7 +42,7 @@ The response will include a list of installations where each installation's `id` Authenticating as an installation lets your app access that organization or user via the API, as well as public resources on {% data variables.product.product_name %}. To authenticate as an installation, you must use an installation access token, which you get by sending a [JWT](#jwt-payload) to {% data variables.product.product_name %} to prove your app's identity. Ensure that you have already installed your GitHub App to at least one organization or user account; it is impossible to create an installation token without an installation. For more information, see "[Installing GitHub Apps](/developers/apps/managing-github-apps/installing-github-apps)." -By default, installation access tokens are scoped to all the repositories that an installation was granted access to. You can further limit the scope of the installation access token to specific repositories by using the `repository_ids` parameter. Installation access tokens have the permissions configured by the {% data variables.product.prodname_github_app %}, and like repository access, can also be scoped down using the `permissions` parameter. For more information, see the [Create an installation access token for an app](/rest/reference/apps#create-an-installation-access-token-for-an-app) endpoint documentation. All installation tokens expire after 1 hour. +By default, installation access tokens are scoped to all the repositories that an installation was granted access to. You can further limit the scope of the installation access token to specific repositories by using the `repository_ids` parameter. Installation access tokens have the permissions configured by the {% data variables.product.prodname_github_app %}, and like repository access, can also be scoped down using the `permissions` parameter. For more information, see the [Create an installation access token for an app](/rest/reference/apps#create-an-installation-access-token-for-an-app) endpoint documentation. All installation tokens expire after 1 hour. To create an installation access token, include the JWT in the Authorization header in the API request, replacing `:installation_id` with the installation's `id`. For more information about generating a JWT, see "[JWT payload](#jwt-payload)." @@ -88,15 +88,15 @@ git clone https://x-access-token:<token>@github.com/owner/repo.git The [JWT](https://jwt.io/) that's used to authenticate your application is made up of several claims, as well as a signature that's used to validate its authenticity. Those claims are: -|Claim | Meaning | Details | +|Claim | Meaning | Details | |---|---|---| |`iat`| Issued At | The time the JWT was created. To protect against clock drift, we recommend you set this 60 seconds in the past. | |`exp`| Expires At | The expiration time of the JWT, after which it can't be used to request an installation token. The `exp` must be no more than 10 minutes into the future. | |`iss`| Issuer | Your application ID, used to find the right public key to verify the signature of the JWT. | -Tokens must be signed using the `RS256` algorithm, with a matching `alg` claim of `RS256`. +Tokens must be signed using the `RS256` algorithm, with a matching `alg` claim of `RS256`. -#### Using Ruby +### Using Ruby Here's a Ruby script you can use to generate a JWT. Note you'll have to run `gem install jwt` before using it. `YOUR_PATH_TO_PEM` and `YOUR_APP_ID` are the values you must replace. Make sure to enclose the values in double quotes. @@ -130,7 +130,7 @@ Here is a similar script for generating a JWT in Python. Note you will have to u ```python{:copy} #!/usr/bin/env python3 import jwt -import time +import time import sys @@ -138,31 +138,31 @@ import sys if len(sys.argv) > 1: pem = sys.argv[1] else: - pem = input("Enter path of private PEM file: ") + pem = input("Enter path of private PEM file: ") # Get the App ID if len(sys.argv) > 2: app_id = sys.argv[2] else: - app_id = input("Enter your APP ID: ") + app_id = input("Enter your APP ID: ") # Open PEM with open(pem, 'rb') as pem_file: signing_key = jwt.jwk_from_pem(pem_file.read()) - + payload = { # Issued at time 'iat': int(time.time()), # JWT expiration time (10 minutes maximum) - 'exp': int(time.time()) + 600, + 'exp': int(time.time()) + 600, # GitHub App's identifier - 'iss': app_id + 'iss': app_id } - + # Create JWT jwt_instance = jwt.JWT() encoded_jwt = jwt_instance.encode(payload, signing_key, alg='RS256') - + print(f"JWT: ", encoded_jwt) ``` @@ -193,7 +193,7 @@ For a list of REST API endpoints you can use to get high-level information about ## Generating a private key -After you create a {% data variables.product.prodname_github_app %}, you'll need to generate one or more private keys in order to make requests to the {% data variables.product.product_name %} API as the application itself. You'll use the private key to sign the [JWTs used to request an installation access token](#jwt-payload). +After you create a {% data variables.product.prodname_github_app %}, you'll need to generate one or more private keys in order to make requests to the {% data variables.product.product_name %} API as the application itself. You'll use the private key to sign the [JWTs used to request an installation access token](#jwt-payload). You can create multiple private keys and rotate them to prevent downtime if a key is compromised or lost. To verify that a private key matches a public key, see [Verifying private keys](#verifying-private-keys). diff --git a/content/developers/github-marketplace/listing-an-app-on-github-marketplace/writing-a-listing-description-for-your-app.md b/content/developers/github-marketplace/listing-an-app-on-github-marketplace/writing-a-listing-description-for-your-app.md index 0725eb52ca..27a8dbf8d5 100644 --- a/content/developers/github-marketplace/listing-an-app-on-github-marketplace/writing-a-listing-description-for-your-app.md +++ b/content/developers/github-marketplace/listing-an-app-on-github-marketplace/writing-a-listing-description-for-your-app.md @@ -24,7 +24,7 @@ Here are guidelines about the fields you'll need to fill out in the **Listing de ### Listing name -Your listing's name will appear on the [{% data variables.product.prodname_marketplace %} homepage](https://github.com/marketplace). The name is limited to 255 characters and can be different from your app's name. Your listing cannot have the same name as an existing account on {% data variables.location.product_location %}, unless the name is your own user or organization name. +Your listing's name will appear on the [{% data variables.product.prodname_marketplace %} homepage](https://github.com/marketplace). The name is limited to 255 characters and can be different from your app's name. Your listing cannot have the same name as an existing account on {% data variables.location.product_location %}, unless the name is your own user or organization name. ### Very short description @@ -110,7 +110,7 @@ A feature card consists of your app's logo, name, and a custom background image As you upload images and select colors, your {% data variables.product.prodname_marketplace %} draft listing will display a preview of your logo and feature card. -#### Guidelines for logos +### Guidelines for logos You must upload a custom image for the logo. For the badge, choose a background color. @@ -120,7 +120,7 @@ You must upload a custom image for the logo. For the badge, choose a background - To give the appearance of a seamless badge, choose a badge background color that matches the background color (or transparency) of your logo image. - Avoid using logo images with words or text in them. Logos with text do not scale well on small screens. -#### Guidelines for feature cards +### Guidelines for feature cards You must upload a custom background image for the feature card. For the app's name, choose a text color. diff --git a/content/developers/overview/managing-deploy-keys.md b/content/developers/overview/managing-deploy-keys.md index 9f838c2051..dc9110071b 100644 --- a/content/developers/overview/managing-deploy-keys.md +++ b/content/developers/overview/managing-deploy-keys.md @@ -23,18 +23,18 @@ You can manage SSH keys on your servers when automating deployment scripts using In many cases, especially in the beginning of a project, SSH agent forwarding is the quickest and simplest method to use. Agent forwarding uses the same SSH keys that your local development computer uses. -#### Pros +### Pros * You do not have to generate or keep track of any new keys. * There is no key management; users have the same permissions on the server that they do locally. * No keys are stored on the server, so in case the server is compromised, you don't need to hunt down and remove the compromised keys. -#### Cons +### Cons * Users **must** SSH in to deploy; automated deploy processes can't be used. * SSH agent forwarding can be troublesome to run for Windows users. -#### Setup +### Setup 1. Turn on agent forwarding locally. See [our guide on SSH agent forwarding][ssh-agent-forwarding] for more information. 2. Set your deploy scripts to use agent forwarding. For example, on a bash script, enabling agent forwarding would look something like this: @@ -44,7 +44,7 @@ In many cases, especially in the beginning of a project, SSH agent forwarding is If you don't want to use SSH keys, you can use HTTPS with OAuth tokens. -#### Pros +### Pros * Anyone with access to the server can deploy the repository. * Users don't have to change their local SSH settings. @@ -54,12 +54,12 @@ If you don't want to use SSH keys, you can use HTTPS with OAuth tokens. * Generating new tokens can be easily scripted using [the OAuth API](/rest/reference/oauth-authorizations#create-a-new-authorization). {% endif %} -#### Cons +### Cons * You must make sure that you configure your token with the correct access scopes. * Tokens are essentially passwords, and must be protected the same way. -#### Setup +### Setup See [our guide on creating a {% data variables.product.pat_generic %}](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). @@ -69,21 +69,21 @@ See [our guide on creating a {% data variables.product.pat_generic %}](/authenti {% data reusables.repositories.deploy-keys-write-access %} -#### Pros +### Pros * Anyone with access to the repository and server has the ability to deploy the project. * Users don't have to change their local SSH settings. * Deploy keys are read-only by default, but you can give them write access when adding them to a repository. -#### Cons +### Cons * Deploy keys only grant access to a single repository. More complex projects may have many repositories to pull to the same server. * Deploy keys are usually not protected by a passphrase, making the key easily accessible if the server is compromised. -#### Setup +### Setup 1. [Run the `ssh-keygen` procedure][generating-ssh-keys] on your server, and remember where you save the generated public and private rsa key pair. -{% data reusables.profile.navigating-to-profile %} +{% data reusables.profile.navigating-to-profile %} ![Navigation to profile](/assets/images/profile-page.png) 1. On your profile page, click **Repositories**, then click the name of your repository. ![Repositories link](/assets/images/repos.png) @@ -93,7 +93,7 @@ See [our guide on creating a {% data variables.product.pat_generic %}](/authenti 5. Select **Allow write access** if you want this key to have write access to the repository. A deploy key with write access lets a deployment push to the repository. 6. Click **Add key**. -#### Using multiple repositories on one server +### Using multiple repositories on one server If you use multiple repositories on one server, you will need to generate a dedicated key pair for each one. You can't reuse a deploy key for multiple repositories. @@ -125,19 +125,19 @@ If your server needs to access repositories across one or more organizations, yo Since GitHub Apps are a first class actor on {% data variables.product.product_name %}, the server-to-server tokens are decoupled from any GitHub user, which makes them comparable to "service tokens". Additionally, server-to-server tokens have dedicated rate limits that scale with the size of the organizations that they act upon. For more information, see [Rate limits for {% data variables.product.prodname_github_apps %}](/developers/apps/rate-limits-for-github-apps). -#### Pros +### Pros - Tightly-scoped tokens with well-defined permission sets and expiration times (1 hour, or less if revoked manually using the API). - Dedicated rate limits that grow with your organization. - Decoupled from GitHub user identities, so they do not consume any licensed seats. - Never granted a password, so cannot be directly signed in to. -#### Cons +### Cons - Additional setup is needed to create the GitHub App. - Server-to-server tokens expire after 1 hour, and so need to be re-generated, typically on-demand using code. -#### Setup +### Setup 1. Determine if your GitHub App should be public or private. If your GitHub App will only act on repositories within your organization, you likely want it private. 1. Determine the permissions your GitHub App requires, such as read-only access to repository contents. @@ -167,18 +167,18 @@ This means that you cannot automate the creation of accounts. But if you want to {% endif %} -#### Pros +### Pros * Anyone with access to the repository and server has the ability to deploy the project. * No (human) users need to change their local SSH settings. * Multiple keys are not needed; one per server is adequate. -#### Cons +### Cons * Only organizations can restrict machine users to read-only access. Personal repositories always grant collaborators read/write access. * Machine user keys, like deploy keys, are usually not protected by a passphrase. -#### Setup +### Setup 1. [Run the `ssh-keygen` procedure][generating-ssh-keys] on your server and attach the public key to the machine user account. 2. Give the machine user account access to the repositories you want to automate. You can do this by adding the account as a [collaborator][collaborator], as an [outside collaborator][outside-collaborator], or to a [team][team] in an organization. diff --git a/content/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization.md b/content/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization.md index 5111b405c9..b88253b136 100644 --- a/content/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization.md +++ b/content/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization.md @@ -89,25 +89,25 @@ You can configure this behavior for an organization using the procedure below. M You can configure required workflows to run in all or selected repositories in an organization where you are an owner. Required workflows are triggered by pull requests and must pass before a pull request can be merged. For more information, see "[Required workflows](/actions/using-workflows/required-workflows)." -#### Prerequisites +### Prerequisites Before configuring a required workflow, note the following prerequisites: {% data reusables.actions.workflows.required-workflow-prerequisites %} -#### Restrictions and behaviors for the source repository +### Restrictions and behaviors for the source repository Note the following restrictions and behaviors for the source repository and workflow: {% data reusables.actions.workflows.required-workflow-source-notes %} -#### Restrictions and behaviors for the target repository +### Restrictions and behaviors for the target repository Note the following restrictions and behaviors for the target repositories: {% data reusables.actions.workflows.required-workflow-target-notes %} -#### Configuring a required workflow for your organization +### Configuring a required workflow for your organization {% data reusables.profile.access_org %} {% data reusables.profile.org_settings %}