jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-23 03:44:00 -05:00
Code Issues Projects Releases Wiki Activity

Merge branch 'main' into al-cheb/windows-default-shell

Browse Source
This commit is contained in:
Shati Patel
2020-12-02 17:30:08 +00:00
committed by GitHub
parent 66558af51e 1756da83d1
commit 6fbdd1d78e
2592 changed files with 2368675 additions and 140784 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
.github/actions-scripts/enterprise-algolia-label.js vendored Executable file
View File

@@ -0,0 +1,36 @@
#!/usr/bin/env node
const fs = require('fs')
const core = require('@actions/core')
const eventPayload = JSON.parse(fs.readFileSync(process.env.GITHUB_EVENT_PATH, 'utf8'))
// This workflow-run script does the following:
// 1. Gets an array of labels on a PR.
// 2. Finds one with the relevant Algolia text; if none found, exits early.
// 3. Gets the version substring from the label string.
const labelText = 'sync-english-index-for-'
const labelsArray = eventPayload.pull_request.labels
// Exit early if no labels are on this PR
if (!(labelsArray && labelsArray.length)) {
process.exit(0)
}
// Find the relevant label
const algoliaLabel = labelsArray
.map(label => label.name)
.find(label => label.startsWith(labelText))
// Exit early if no relevant label is found
if (!algoliaLabel) {
process.exit(0)
}
// Given: sync-english-index-for-enterprise-server@3.0
// Returns: enterprise-server@3.0
const versionToSync = algoliaLabel.split(labelText)[1]
// Store the version so we can access it later in the workflow
core.setOutput('versionToSync', versionToSync)
process.exit(0)

41
.github/actions-scripts/openapi-schema-branch.js vendored Executable file
View File

@@ -0,0 +1,41 @@
#!/usr/bin/env node
const fs = require('fs')
const path = require('path')
const { execSync } = require('child_process')
const semver = require('semver')
/*
* This script performs two checks to prevent shipping development mode OpenAPI schemas:
* - Ensures the `info.version` property is a semantic version.
* In development mode, the `info.version` property is a string
* containing the `github/github` branch name.
* - Ensures the decorated schema matches the dereferenced schema.
* The workflow that calls this script runs `script/rest/update-files.js`
* with the `--decorate-only` switch then checks to see if files changed.
*
*/
// Check that the `info.version` property is a semantic version
const dereferencedDir = path.join(process.cwd(), 'lib/rest/static/dereferenced')
const schemas = fs.readdirSync(dereferencedDir)
schemas.forEach(filename => {
const schema = require(path.join(dereferencedDir, filename))
if (!semver.valid(schema.info.version)) {
console.log(`🚧⚠️ Your branch contains a development mode OpenAPI schema: ${schema.info.version}. This check is a reminder to not 🚢 OpenAPI files in development mode. 🛑`)
process.exit(1)
}
})
// Check that the decorated schema matches the dereferenced schema
const changedFiles = execSync('git diff --name-only HEAD').toString()
if(changedFiles !== '') {
console.log(`These files were changed:\n${changedFiles}`)
console.log(`🚧⚠️ Your decorated and dereferenced schema files don't match. Ensure you're using decorated and dereferenced schemas from the automatically created pull requests by the 'github-openapi-bot' user. For more information, see 'script/rest/README.md'. 🛑`)
process.exit(1)
}
// All checks pass, ready to ship
console.log('All good 👍')
process.exit(0)

5
.github/allowed-actions.js vendored
View File

@@ -21,13 +21,16 @@ module.exports = [
'juliangruber/approve-pull-request-action@c530832d4d346c597332e20e03605aa94fa150a8', 'juliangruber/approve-pull-request-action@c530832d4d346c597332e20e03605aa94fa150a8',
'juliangruber/find-pull-request-action@64d55773c959748ad30a4184f4dc102af1669f7b', 'juliangruber/find-pull-request-action@64d55773c959748ad30a4184f4dc102af1669f7b',
'juliangruber/read-file-action@e0a316da496006ffd19142f0fd594a1783f3b512', 'juliangruber/read-file-action@e0a316da496006ffd19142f0fd594a1783f3b512',
'lee-dohm/close-matching-issues@22002609b2555fe18f52b8e2e7c07cbf5529e8a8',
'pascalgn/automerge-action@c9bd182', 'pascalgn/automerge-action@c9bd182',
'peter-evans/create-issue-from-file@a04ce672e3acedb1f8e416b46716ddfd09905326', 'peter-evans/create-issue-from-file@a04ce672e3acedb1f8e416b46716ddfd09905326',
'peter-evans/create-or-update-comment@5221bf4aa615e5c6e95bb142f9673a9c791be2cd',
'peter-evans/create-pull-request@938e6aea6f8dbdaced2064e948cb806c77fe87b8', 'peter-evans/create-pull-request@938e6aea6f8dbdaced2064e948cb806c77fe87b8',
'rachmari/actions-add-new-issue-to-column@1a459ef92308ba7c9c9dc2fcdd72f232495574a9', 'rachmari/actions-add-new-issue-to-column@1a459ef92308ba7c9c9dc2fcdd72f232495574a9',
'rachmari/labeler@832d42ec5523f3c6d46e8168de71cd54363e3e2e', 'rachmari/labeler@832d42ec5523f3c6d46e8168de71cd54363e3e2e',
'repo-sync/github-sync@3832fe8e2be32372e1b3970bbae8e7079edeec88', 'repo-sync/github-sync@3832fe8e2be32372e1b3970bbae8e7079edeec88',
'repo-sync/pull-request@33777245b1aace1a58c87a29c90321aa7a74bd7d', 'repo-sync/pull-request@33777245b1aace1a58c87a29c90321aa7a74bd7d',
'rtCamp/action-slack-notify@e17352feaf9aee300bf0ebc1dfbf467d80438815', 'rtCamp/action-slack-notify@e17352feaf9aee300bf0ebc1dfbf467d80438815',
'tjenkinson/gh-action-auto-merge-dependency-updates@cee2ac0' 'tjenkinson/gh-action-auto-merge-dependency-updates@cee2ac0',
'EndBug/add-and-commit@9358097a71ad9fb9e2f9624c6098c89193d83575'
] ]

18
.github/workflows/check-all-english-links.yml vendored
View File

@@ -17,16 +17,32 @@ jobs:
- name: npm run build - name: npm run build
run: npm run build run: npm run build
- name: Run script - name: Run script
run: script/check-english-links.js > broken_links.md run: |
script/check-english-links.js > broken_links.md
- if: ${{ failure() }} - if: ${{ failure() }}
name: Get title for issue name: Get title for issue
id: check id: check
run: echo "::set-output name=title::$(head -1 broken_links.md)" run: echo "::set-output name=title::$(head -1 broken_links.md)"
- if: ${{ failure() }}
name: Close previous report
uses: lee-dohm/close-matching-issues@22002609b2555fe18f52b8e2e7c07cbf5529e8a8
with:
query: 'label:"broken link report"'
token: ${{ secrets.DOCUBOT_FR_PROJECT_BOARD_WORKFLOWS_REPO_ORG_READ_SCOPES }}
- if: ${{ failure() }} - if: ${{ failure() }}
name: Create issue from file name: Create issue from file
id: broken-link-report
uses: peter-evans/create-issue-from-file@a04ce672e3acedb1f8e416b46716ddfd09905326 uses: peter-evans/create-issue-from-file@a04ce672e3acedb1f8e416b46716ddfd09905326
with: with:
token: ${{ secrets.DOCUBOT_FR_PROJECT_BOARD_WORKFLOWS_REPO_ORG_READ_SCOPES }} token: ${{ secrets.DOCUBOT_FR_PROJECT_BOARD_WORKFLOWS_REPO_ORG_READ_SCOPES }}
title: ${{ steps.check.outputs.title }} title: ${{ steps.check.outputs.title }}
content-filepath: ./broken_links.md content-filepath: ./broken_links.md
labels: broken link report labels: broken link report
- if: ${{ failure() }}
name: Add comment to issue
uses: peter-evans/create-or-update-comment@5221bf4aa615e5c6e95bb142f9673a9c791be2cd
with:
body: |
cc @github/docs-content
issue-number: ${{ steps.broken-link-report.outputs.issue-number }}
token: ${{ secrets.DOCUBOT_FR_PROJECT_BOARD_WORKFLOWS_REPO_ORG_READ_SCOPES }}

32
.github/workflows/openapi-decorate.yml vendored Normal file
View File

@@ -0,0 +1,32 @@
name: OpenAPI generate decorated schema files
on:
workflow_dispatch:
pull_request:
types: [opened]
jobs:
generate-decorated-files:
if: github.event.pull_request.user.login == 'github-openapi-bot'
runs-on: ubuntu-latest
steps:
- name: Checkout repository code
uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
- name: Install dependencies
run: npm ci
- name: Decorate the dereferenced OpenAPI schemas
run: script/rest/update-files.js --decorate-only
- name: Check in the decorated files
uses: EndBug/add-and-commit@9358097a71ad9fb9e2f9624c6098c89193d83575
with:
# The arguments for the `git add` command
add: 'lib/rest/static/decorated'
# The message for the commit
message: 'Add decorated OpenAPI schema files'
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Leave this line unchanged

22
.github/workflows/openapi-schema-check.yml vendored Normal file
View File

@@ -0,0 +1,22 @@
name: OpenAPI dev mode check
on:
workflow_dispatch:
push:
jobs:
check-schema-versions:
runs-on: ubuntu-latest
steps:
- name: Checkout repository code
uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
- name: Install dependencies
run: npm ci
# Differences between decorated and dereferenced files indicates a problem
- name: Generate decorated files to check that there are no differences
run: script/rest/update-files.js --decorate-only
- name: Check if deref/decorated schemas are dev mode and that they match
run: .github/actions-scripts/openapi-schema-branch.js

46
.github/workflows/sync-single-english-algolia-index.yml vendored Normal file
View File

@@ -0,0 +1,46 @@
name: Algolia Sync Single English Index
on:
pull_request:
types:
- labeled
- unlabeled
- opened
- reopened
- synchronize
- ready_for_review
- unlocked
# This workflow requires a label in the format `sync-english-index-for-<PLAN@RELEASE>`
jobs:
updateIndices:
name: Update English index for single version based on a label's version
if: github.repository == 'github/docs-internal'
runs-on: ubuntu-latest
steps:
- name: checkout
uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
- uses: actions/setup-node@56899e050abffc08c2b3b61f3ec6a79a9dc3223d
with:
node-version: 14.x
- name: cache node modules
uses: actions/cache@0781355a23dac32fd3bac414512f4b903437991a
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-
- name: npm ci
run: npm ci
- name: Get version from Algolia label if present; only continue if the label is found.
id: getVersion
run: $GITHUB_WORKSPACE/.github/actions-scripts/enterprise-algolia-label.js
- if: ${{ steps.getVersion.outputs.versionToSync }}
name: Sync English index for single version
env:
VERSION: ${{ steps.getVersion.outputs.versionToSync }}
LANGUAGE: 'en'
ALGOLIA_APPLICATION_ID: ${{ secrets.ALGOLIA_APPLICATION_ID }}
ALGOLIA_API_KEY: ${{ secrets.ALGOLIA_API_KEY }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: npm run sync-search

1
CODE_OF_CONDUCT.md
View File

@@ -22,6 +22,7 @@ Examples of unacceptable behavior include:
* Trolling, insulting or derogatory comments, and personal or political attacks * Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment * Public or private harassment
* Publishing others' private information, such as a physical or email address, without their explicit permission * Publishing others' private information, such as a physical or email address, without their explicit permission
* Contacting individual members, contributors, or leaders privately, outside designated community mechanisms, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting * Other conduct which could reasonably be considered inappropriate in a professional setting
## Enforcement Responsibilities ## Enforcement Responsibilities

4
content/actions/creating-actions/about-actions.md
View File

@@ -32,8 +32,8 @@ You can build Docker container and JavaScript actions. Actions require a metadat
| Type | Operating system | | Type | Operating system |
| ---- | ------------------- | | ---- | ------------------- |
| Docker container | Linux | | Docker container | Linux |
| JavaScript | Linux, MacOS, Windows | | JavaScript | Linux, macOS, Windows |
| Composite run steps | Linux, MacOS, Windows | | Composite run steps | Linux, macOS, Windows |
#### Docker container actions #### Docker container actions

80
content/actions/creating-actions/metadata-syntax-for-github-actions.md
View File

@@ -22,19 +22,19 @@ Docker and JavaScript actions require a metadata file. The metadata filename mus
Action metadata files use YAML syntax. If you're new to YAML, you can read "[Learn YAML in five minutes](https://www.codeproject.com/Articles/1214409/Learn-YAML-in-five-minutes)." Action metadata files use YAML syntax. If you're new to YAML, you can read "[Learn YAML in five minutes](https://www.codeproject.com/Articles/1214409/Learn-YAML-in-five-minutes)."
### **`name`** ### `name`
**Required** The name of your action. {% data variables.product.prodname_dotcom %} displays the `name` in the **Actions** tab to help visually identify actions in each job. **Required** The name of your action. {% data variables.product.prodname_dotcom %} displays the `name` in the **Actions** tab to help visually identify actions in each job.
### **`author`** ### `author`
**Optional** The name of the action's author. **Optional** The name of the action's author.
### **`description`** ### `description`
**Required** A short description of the action. **Required** A short description of the action.
### **`inputs`** ### `inputs`
**Optional** Input parameters allow you to specify data that the action expects to use during runtime. {% data variables.product.prodname_dotcom %} stores input parameters as environment variables. Input ids with uppercase letters are converted to lowercase during runtime. We recommended using lowercase input ids. **Optional** Input parameters allow you to specify data that the action expects to use during runtime. {% data variables.product.prodname_dotcom %} stores input parameters as environment variables. Input ids with uppercase letters are converted to lowercase during runtime. We recommended using lowercase input ids.
@@ -57,23 +57,23 @@ When you specify an input to an action in a workflow file or use a default input
For example, if a workflow defined the numOctocats and octocatEyeColor inputs, the action code could read the values of the inputs using the `INPUT_NUMOCTOCATS` and `INPUT_OCTOCATEYECOLOR` environment variables. For example, if a workflow defined the numOctocats and octocatEyeColor inputs, the action code could read the values of the inputs using the `INPUT_NUMOCTOCATS` and `INPUT_OCTOCATEYECOLOR` environment variables.
#### **`inputs.<input_id>`** #### `inputs.<input_id>`
**Required** A `string` identifier to associate with the input. The value of `<input_id>` is a map of the input's metadata. The `<input_id>` must be a unique identifier within the `inputs` object. The `<input_id>` must start with a letter or `_` and contain only alphanumeric characters, `-`, or `_`. **Required** A `string` identifier to associate with the input. The value of `<input_id>` is a map of the input's metadata. The `<input_id>` must be a unique identifier within the `inputs` object. The `<input_id>` must start with a letter or `_` and contain only alphanumeric characters, `-`, or `_`.
#### **`inputs.<input_id>.description`** #### `inputs.<input_id>.description`
**Required** A `string` description of the input parameter. **Required** A `string` description of the input parameter.
#### **`inputs.<input_id>.required`** #### `inputs.<input_id>.required`
**Required** A `boolean` to indicate whether the action requires the input parameter. Set to `true` when the parameter is required. **Required** A `boolean` to indicate whether the action requires the input parameter. Set to `true` when the parameter is required.
#### **`inputs.<input_id>.default`** #### `inputs.<input_id>.default`
**Optional** A `string` representing the default value. The default value is used when an input parameter isn't specified in a workflow file. **Optional** A `string` representing the default value. The default value is used when an input parameter isn't specified in a workflow file.
### **`outputs`** ### `outputs`
**Optional** Output parameters allow you to declare data that an action sets. Actions that run later in a workflow can use the output data set in previously run actions. For example, if you had an action that performed the addition of two inputs (x + y = z), the action could output the sum (z) for other actions to use as an input. **Optional** Output parameters allow you to declare data that an action sets. Actions that run later in a workflow can use the output data set in previously run actions. For example, if you had an action that performed the addition of two inputs (x + y = z), the action could output the sum (z) for other actions to use as an input.
@@ -87,15 +87,15 @@ outputs:
description: 'The sum of the inputs' description: 'The sum of the inputs'
``` ```
#### **`outputs.<output_id>`** #### `outputs.<output_id>`
**Required** A `string` identifier to associate with the output. The value of `<output_id>` is a map of the output's metadata. The `<output_id>` must be a unique identifier within the `outputs` object. The `<output_id>` must start with a letter or `_` and contain only alphanumeric characters, `-`, or `_`. **Required** A `string` identifier to associate with the output. The value of `<output_id>` is a map of the output's metadata. The `<output_id>` must be a unique identifier within the `outputs` object. The `<output_id>` must start with a letter or `_` and contain only alphanumeric characters, `-`, or `_`.
#### **`outputs.<output_id>.description`** #### `outputs.<output_id>.description`
**Required** A `string` description of the output parameter. **Required** A `string` description of the output parameter.
### **`outputs`** for composite run steps actions ### `outputs` for composite run steps actions
**Optional** `outputs` use the same parameters as `outputs.<output_id>` and `outputs.<output_id>.description` (see "[`outputs` for {% data variables.product.prodname_actions %}](/actions/creating-actions/metadata-syntax-for-github-actions#outputs)"), but also includes the `value` token. **Optional** `outputs` use the same parameters as `outputs.<output_id>` and `outputs.<output_id>.description` (see "[`outputs` for {% data variables.product.prodname_actions %}](/actions/creating-actions/metadata-syntax-for-github-actions#outputs)"), but also includes the `value` token.
@@ -116,12 +116,12 @@ runs:
``` ```
{% endraw %} {% endraw %}
#### **`outputs.<output_id.value>`** #### `outputs.<output_id>.value`
**Required** The value that the output parameter will be mapped to. You can set this to a `string` or an expression with context. For example, you can use the `steps` context to set the `value` of an output to the output value of a step. **Required** The value that the output parameter will be mapped to. You can set this to a `string` or an expression with context. For example, you can use the `steps` context to set the `value` of an output to the output value of a step.
For more information on how to use context and expression syntax, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)". For more information on how to use context and expression syntax, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)".
### **`runs`** for JavaScript actions ### `runs` for JavaScript actions
**Required** Configures the path to the action's code and the application used to execute the code. **Required** Configures the path to the action's code and the application used to execute the code.
@@ -133,15 +133,15 @@ runs:
main: 'main.js' main: 'main.js'
``` ```
#### **`runs.using`** #### `runs.using`
**Required** The application used to execute the code specified in [`main`](#runsmain). **Required** The application used to execute the code specified in [`main`](#runsmain).
#### **`runs.main`** #### `runs.main`
**Required** The file that contains your action code. The application specified in [`using`](#runsusing) executes this file. **Required** The file that contains your action code. The application specified in [`using`](#runsusing) executes this file.
#### **`pre`** #### `pre`
**Optional** Allows you to run a script at the start of a job, before the `main:` action begins. For example, you can use `pre:` to run a prerequisite setup script. The application specified with the [`using`](#runsusing) syntax will execute this file. The `pre:` action always runs by default but you can override this using [`pre-if`](#pre-if). **Optional** Allows you to run a script at the start of a job, before the `main:` action begins. For example, you can use `pre:` to run a prerequisite setup script. The application specified with the [`using`](#runsusing) syntax will execute this file. The `pre:` action always runs by default but you can override this using [`pre-if`](#pre-if).
@@ -155,7 +155,7 @@ runs:
post: 'cleanup.js' post: 'cleanup.js'
``` ```
#### **`pre-if`** #### `pre-if`
**Optional** Allows you to define conditions for the `pre:` action execution. The `pre:` action will only run if the conditions in `pre-if` are met. If not set, then `pre-if` defaults to `always()`. **Optional** Allows you to define conditions for the `pre:` action execution. The `pre:` action will only run if the conditions in `pre-if` are met. If not set, then `pre-if` defaults to `always()`.
Note that the `step` context is unavailable, as no steps have run yet. Note that the `step` context is unavailable, as no steps have run yet.
@@ -167,7 +167,7 @@ In this example, `cleanup.js` only runs on Linux-based runners:
pre-if: 'runner.os == linux' pre-if: 'runner.os == linux'
``` ```
#### **`post`** #### `post`
**Optional** Allows you to run a script at the end of a job, once the `main:` action has completed. For example, you can use `post:` to terminate certain processes or remove unneeded files. The application specified with the [`using`](#runsusing) syntax will execute this file. **Optional** Allows you to run a script at the end of a job, once the `main:` action has completed. For example, you can use `post:` to terminate certain processes or remove unneeded files. The application specified with the [`using`](#runsusing) syntax will execute this file.
@@ -182,7 +182,7 @@ runs:
The `post:` action always runs by default but you can override this using `post-if`. The `post:` action always runs by default but you can override this using `post-if`.
#### **`post-if`** #### `post-if`
**Optional** Allows you to define conditions for the `post:` action execution. The `post:` action will only run if the conditions in `post-if` are met. If not set, then `post-if` defaults to `always()`. **Optional** Allows you to define conditions for the `post:` action execution. The `post:` action will only run if the conditions in `post-if` are met. If not set, then `post-if` defaults to `always()`.
@@ -193,19 +193,19 @@ For example, this `cleanup.js` will only run on Linux-based runners:
post-if: 'runner.os == linux' post-if: 'runner.os == linux'
``` ```
### **`runs`** for composite run steps actions ### `runs` for composite run steps actions
**Required** Configures the path to the composite action, and the application used to execute the code. **Required** Configures the path to the composite action, and the application used to execute the code.
#### **`runs.using`** #### `runs.using`
**Required** To use a composite run steps action, set this to `"composite"`. **Required** To use a composite run steps action, set this to `"composite"`.
#### **`runs.steps`** #### `runs.steps`
**Required** The run steps that you plan to run in this action. **Required** The run steps that you plan to run in this action.
##### **`runs.steps.run`** ##### `runs.steps.run`
**Required** The command you want to run. This can be inline or a script in your action repository: **Required** The command you want to run. This can be inline or a script in your action repository:
```yaml ```yaml
@@ -228,27 +228,27 @@ runs:
For more information, see "[`github context`](/actions/reference/context-and-expression-syntax-for-github-actions#github-context)". For more information, see "[`github context`](/actions/reference/context-and-expression-syntax-for-github-actions#github-context)".
##### **`runs.steps.shell`** ##### `runs.steps.shell`
**Required** The shell where you want to run the command. You can use any of the shells listed [here](/actions/reference/workflow-syntax-for-github-actions#using-a-specific-shell). **Required** The shell where you want to run the command. You can use any of the shells listed [here](/actions/reference/workflow-syntax-for-github-actions#using-a-specific-shell).
##### **`runs.steps.name`** ##### `runs.steps.name`
**Optional** The name of the composite run step. **Optional** The name of the composite run step.
##### **`runs.steps.id`** ##### `runs.steps.id`
**Optional** A unique identifier for the step. You can use the `id` to reference the step in contexts. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)". **Optional** A unique identifier for the step. You can use the `id` to reference the step in contexts. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)".
##### **`runs.steps.env`** ##### `runs.steps.env`
**Optional** Sets a `map` of environment variables for only that step. If you want to modify the environment variable stored in the workflow, use {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %}`echo "{name}={value}" >> $GITHUB_ENV`{% else %}`echo "::set-env name={name}::{value}"`{% endif %} in a composite run step. **Optional** Sets a `map` of environment variables for only that step. If you want to modify the environment variable stored in the workflow, use {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %}`echo "{name}={value}" >> $GITHUB_ENV`{% else %}`echo "::set-env name={name}::{value}"`{% endif %} in a composite run step.
##### **`runs.steps.working-directory`** ##### `runs.steps.working-directory`
**Optional** Specifies the working directory where the command is run. **Optional** Specifies the working directory where the command is run.
### **`runs`** for Docker actions ### `runs` for Docker actions
**Required** Configures the image used for the Docker action. **Required** Configures the image used for the Docker action.
@@ -268,11 +268,11 @@ runs:
image: 'docker://debian:stretch-slim' image: 'docker://debian:stretch-slim'
``` ```
#### **`runs.using`** #### `runs.using`
**Required** You must set this value to `'docker'`. **Required** You must set this value to `'docker'`.
#### **`pre-entrypoint`** #### `pre-entrypoint`
**Optional** Allows you to run a script before the `entrypoint` action begins. For example, you can use `pre-entrypoint:` to run a prerequisite setup script. {% data variables.product.prodname_actions %} uses `docker run` to launch this action, and runs the script inside a new container that uses the same base image. This means that the runtime state is different from the main `entrypoint` container, and any states you require must be accessed in either the workspace, `HOME`, or as a `STATE_` variable. The `pre-entrypoint:` action always runs by default but you can override this using [`pre-if`](#pre-if). **Optional** Allows you to run a script before the `entrypoint` action begins. For example, you can use `pre-entrypoint:` to run a prerequisite setup script. {% data variables.product.prodname_actions %} uses `docker run` to launch this action, and runs the script inside a new container that uses the same base image. This means that the runtime state is different from the main `entrypoint` container, and any states you require must be accessed in either the workspace, `HOME`, or as a `STATE_` variable. The `pre-entrypoint:` action always runs by default but you can override this using [`pre-if`](#pre-if).
@@ -290,21 +290,21 @@ runs:
entrypoint: 'main.sh' entrypoint: 'main.sh'
``` ```
#### **`runs.image`** #### `runs.image`
**Required** The Docker image to use as the container to run the action. The value can be the Docker base image name, a local `Dockerfile` in your repository, or a public image in Docker Hub or another registry. To reference a `Dockerfile` local to your repository, use a path relative to your action metadata file. The `docker` application will execute this file. **Required** The Docker image to use as the container to run the action. The value can be the Docker base image name, a local `Dockerfile` in your repository, or a public image in Docker Hub or another registry. To reference a `Dockerfile` local to your repository, use a path relative to your action metadata file. The `docker` application will execute this file.
#### **`runs.env`** #### `runs.env`
**Optional** Specifies a key/value map of environment variables to set in the container environment. **Optional** Specifies a key/value map of environment variables to set in the container environment.
#### **`runs.entrypoint`** #### `runs.entrypoint`
**Optional** Overrides the Docker `ENTRYPOINT` in the `Dockerfile`, or sets it if one wasn't already specified. Use `entrypoint` when the `Dockerfile` does not specify an `ENTRYPOINT` or you want to override the `ENTRYPOINT` instruction. If you omit `entrypoint`, the commands you specify in the Docker `ENTRYPOINT` instruction will execute. The Docker `ENTRYPOINT` instruction has a _shell_ form and _exec_ form. The Docker `ENTRYPOINT` documentation recommends using the _exec_ form of the `ENTRYPOINT` instruction. **Optional** Overrides the Docker `ENTRYPOINT` in the `Dockerfile`, or sets it if one wasn't already specified. Use `entrypoint` when the `Dockerfile` does not specify an `ENTRYPOINT` or you want to override the `ENTRYPOINT` instruction. If you omit `entrypoint`, the commands you specify in the Docker `ENTRYPOINT` instruction will execute. The Docker `ENTRYPOINT` instruction has a _shell_ form and _exec_ form. The Docker `ENTRYPOINT` documentation recommends using the _exec_ form of the `ENTRYPOINT` instruction.
For more information about how the `entrypoint` executes, see "[Dockerfile support for {% data variables.product.prodname_actions %}](/actions/creating-actions/dockerfile-support-for-github-actions/#entrypoint)." For more information about how the `entrypoint` executes, see "[Dockerfile support for {% data variables.product.prodname_actions %}](/actions/creating-actions/dockerfile-support-for-github-actions/#entrypoint)."
#### **`post-entrypoint`** #### `post-entrypoint`
**Optional** Allows you to run a cleanup script once the `runs.entrypoint` action has completed. {% data variables.product.prodname_actions %} uses `docker run` to launch this action. Because {% data variables.product.prodname_actions %} runs the script inside a new container using the same base image, the runtime state is different from the main `entrypoint` container. You can access any state you need in either the workspace, `HOME`, or as a `STATE_` variable. The `post-entrypoint:` action always runs by default but you can override this using [`post-if`](#post-if). **Optional** Allows you to run a cleanup script once the `runs.entrypoint` action has completed. {% data variables.product.prodname_actions %} uses `docker run` to launch this action. Because {% data variables.product.prodname_actions %} runs the script inside a new container using the same base image, the runtime state is different from the main `entrypoint` container. You can access any state you need in either the workspace, `HOME`, or as a `STATE_` variable. The `post-entrypoint:` action always runs by default but you can override this using [`post-if`](#post-if).
@@ -318,7 +318,7 @@ runs:
post-entrypoint: 'cleanup.sh' post-entrypoint: 'cleanup.sh'
``` ```
#### **`runs.args`** #### `runs.args`
**Optional** An array of strings that define the inputs for a Docker container. Inputs can include hardcoded strings. {% data variables.product.prodname_dotcom %} passes the `args` to the container's `ENTRYPOINT` when the container starts up. **Optional** An array of strings that define the inputs for a Docker container. Inputs can include hardcoded strings. {% data variables.product.prodname_dotcom %} passes the `args` to the container's `ENTRYPOINT` when the container starts up.
@@ -344,7 +344,7 @@ runs:
``` ```
{% endraw %} {% endraw %}
### **`branding`** ### `branding`
You can use a color and [Feather](https://feathericons.com/) icon to create a badge to personalize and distinguish your action. Badges are shown next to your action name in [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace?type=actions). You can use a color and [Feather](https://feathericons.com/) icon to create a badge to personalize and distinguish your action. Badges are shown next to your action name in [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace?type=actions).
@@ -356,11 +356,11 @@ branding:
color: 'green' color: 'green'
``` ```
#### **`branding.color`** #### `branding.color`
The background color of the badge. Can be one of: `white`, `yellow`, `blue`, `green`, `orange`, `red`, `purple`, or `gray-dark`. The background color of the badge. Can be one of: `white`, `yellow`, `blue`, `green`, `orange`, `red`, `purple`, or `gray-dark`.
#### **`branding.icon`** #### `branding.icon`
The name of the [Feather](https://feathericons.com/) icon to use. The name of the [Feather](https://feathericons.com/) icon to use.

2
content/actions/guides/building-and-testing-java-with-gradle.md
View File

@@ -91,7 +91,7 @@ steps:
### Caching dependencies ### Caching dependencies
You can cache your dependencies to speed up your workflow runs. After a successful run, your local Gradle package cache will be stored on GitHub Actions infrastructure. In future workflow runs, the cache will be restored so that dependencies don't need to be downloaded from remote package repositories. For more information, see "[Caching dependencies to speed up workflows](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)" and the [`cache` action](https://github.com/marketplace/actions/cache). When using {% data variables.product.prodname_dotcom %}-hosted runners, you can cache your dependencies to speed up your workflow runs. After a successful run, your local Gradle package cache will be stored on GitHub Actions infrastructure. In future workflow runs, the cache will be restored so that dependencies don't need to be downloaded from remote package repositories. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>" and the [`cache` action](https://github.com/marketplace/actions/cache).
{% raw %} {% raw %}
```yaml ```yaml

2
content/actions/guides/building-and-testing-java-with-maven.md
View File

@@ -91,7 +91,7 @@ steps:
### Caching dependencies ### Caching dependencies
You can cache your dependencies to speed up your workflow runs. After a successful run, your local Maven repository will be stored on GitHub Actions infrastructure. In future workflow runs, the cache will be restored so that dependencies don't need to be downloaded from remote Maven repositories. For more information, see "[Caching dependencies to speed up workflows](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)" and the [`cache` action](https://github.com/marketplace/actions/cache). When using {% data variables.product.prodname_dotcom %}-hosted runners, you can cache your dependencies to speed up your workflow runs. After a successful run, your local Maven repository will be stored on GitHub Actions infrastructure. In future workflow runs, the cache will be restored so that dependencies don't need to be downloaded from remote Maven repositories. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>" and the [`cache` action](https://github.com/marketplace/actions/cache).
{% raw %} {% raw %}
```yaml ```yaml

6
content/actions/guides/building-and-testing-nodejs.md
View File

@@ -129,7 +129,7 @@ If you don't specify a Node.js version, {% data variables.product.prodname_dotco
{% data variables.product.prodname_dotcom %}-hosted runners have npm and Yarn dependency managers installed. You can use npm and Yarn to install dependencies in your workflow before building and testing your code. The Windows and Linux {% data variables.product.prodname_dotcom %}-hosted runners also have Grunt, Gulp, and Bower installed. {% data variables.product.prodname_dotcom %}-hosted runners have npm and Yarn dependency managers installed. You can use npm and Yarn to install dependencies in your workflow before building and testing your code. The Windows and Linux {% data variables.product.prodname_dotcom %}-hosted runners also have Grunt, Gulp, and Bower installed.
You can also cache dependencies to speed up your workflow. For more information, see "[Caching dependencies to speed up your workflow](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)." When using {% data variables.product.prodname_dotcom %}-hosted runners, you can also cache dependencies to speed up your workflow. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
#### Example using npm #### Example using npm
@@ -227,7 +227,7 @@ always-auth=true
#### Example caching dependencies #### Example caching dependencies
You can cache dependencies using a unique key, and restore the dependencies when you run future workflows using the `cache` action. For more information, see "[Caching dependencies to speed up workflows](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)" and the [`cache` action](https://github.com/marketplace/actions/cache). When using {% data variables.product.prodname_dotcom %}-hosted runners, you can cache dependencies using a unique key, and restore the dependencies when you run future workflows using the `cache` action. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>" and the [`cache` action](https://github.com/marketplace/actions/cache).
{% raw %} {% raw %}
```yaml ```yaml
@@ -241,7 +241,7 @@ steps:
uses: actions/cache@v2 uses: actions/cache@v2
with: with:
# npm cache files are stored in `~/.npm` on Linux/macOS # npm cache files are stored in `~/.npm` on Linux/macOS
path: ~/.npm path: ~/.npm
key: ${{ runner.OS }}-node-${{ hashFiles('**/package-lock.json') }} key: ${{ runner.OS }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: | restore-keys: |
${{ runner.OS }}-node- ${{ runner.OS }}-node-

10
content/actions/guides/building-and-testing-powershell.md
View File

@@ -30,7 +30,7 @@ We recommend that you have a basic understanding of PowerShell and Pester. For m
### Adding a workflow for Pester ### Adding a workflow for Pester
To automate your testing with PowerShell and Pester, you can add a workflow that runs every time a change is pushed to your repository. In the following example, `Test-Path` is used to check that a file called `resultsfile.log` is present. To automate your testing with PowerShell and Pester, you can add a workflow that runs every time a change is pushed to your repository. In the following example, `Test-Path` is used to check that a file called `resultsfile.log` is present.
This example workflow file must be added to your repository's `.github/workflows/` directory: This example workflow file must be added to your repository's `.github/workflows/` directory:
@@ -57,7 +57,7 @@ jobs:
{% endraw %} {% endraw %}
* `shell: pwsh` - Configures the job to use PowerShell when running the `run` commands. * `shell: pwsh` - Configures the job to use PowerShell when running the `run` commands.
* `run: Test-Path resultsfile.log` - Check whether a file called `resultsfile.log` is present in the repository's root directory. * `run: Test-Path resultsfile.log` - Check whether a file called `resultsfile.log` is present in the repository's root directory.
* `Should -Be $true` - Uses Pester to define an expected result. If the result is unexpected, then {% data variables.product.prodname_actions %} flags this as a failed test. For example: * `Should -Be $true` - Uses Pester to define an expected result. If the result is unexpected, then {% data variables.product.prodname_actions %} flags this as a failed test. For example:
![Failed Pester test](/assets/images/help/repository/actions-failed-pester-test.png) ![Failed Pester test](/assets/images/help/repository/actions-failed-pester-test.png)
@@ -83,7 +83,7 @@ The table below describes the locations for various PowerShell modules in each {
### Installing dependencies ### Installing dependencies
{% data variables.product.prodname_dotcom %}-hosted runners have PowerShell 7 and Pester installed. You can use `Install-Module` to install additional dependencies from the PowerShell Gallery before building and testing your code. {% data variables.product.prodname_dotcom %}-hosted runners have PowerShell 7 and Pester installed. You can use `Install-Module` to install additional dependencies from the PowerShell Gallery before building and testing your code.
{% note %} {% note %}
@@ -91,7 +91,7 @@ The table below describes the locations for various PowerShell modules in each {
{% endnote %} {% endnote %}
You can also cache dependencies to speed up your workflow. For more information, see "[Caching dependencies to speed up your workflow](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)." When using {% data variables.product.prodname_dotcom %}-hosted runners, you can also cache dependencies to speed up your workflow. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
For example, the following job installs the `SqlServer` and `PSScriptAnalyzer` modules: For example, the following job installs the `SqlServer` and `PSScriptAnalyzer` modules:
@@ -119,7 +119,7 @@ jobs:
#### Caching dependencies #### Caching dependencies
You can cache PowerShell dependencies using a unique key, which allows you to restore the dependencies for future workflows with the [`cache`](https://github.com/marketplace/actions/cache) action. For more information, see "[Caching dependencies to speed up workflows](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)." When using {% data variables.product.prodname_dotcom %}-hosted runners, you can cache PowerShell dependencies using a unique key, which allows you to restore the dependencies for future workflows with the [`cache`](https://github.com/marketplace/actions/cache) action. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
PowerShell caches its dependencies in different locations, depending on the runner's operating system. For example, the `path` location used in the following Ubuntu example will be different for a Windows operating system. PowerShell caches its dependencies in different locations, depending on the runner's operating system. For example, the `path` location used in the following Ubuntu example will be different for a Windows operating system.

8
content/actions/guides/building-and-testing-python.md
View File

@@ -141,9 +141,9 @@ jobs:
uses: actions/setup-python@v2 uses: actions/setup-python@v2
with: with:
# Semantic version range syntax or exact version of a Python version # Semantic version range syntax or exact version of a Python version
python-version: '3.x' python-version: '3.x'
# Optional - x64 or x86 architecture, defaults to x64 # Optional - x64 or x86 architecture, defaults to x64
architecture: 'x64' architecture: 'x64'
# You can test your matrix by printing the current Python version # You can test your matrix by printing the current Python version
- name: Display Python version - name: Display Python version
run: python -c "import sys; print(sys.version)" run: python -c "import sys; print(sys.version)"
@@ -192,7 +192,7 @@ We recommend using `setup-python` to configure the version of Python used in you
{% data variables.product.prodname_dotcom %}-hosted runners have the pip package manager installed. You can use pip to install dependencies from the PyPI package registry before building and testing your code. For example, the YAML below installs or upgrades the `pip` package installer and the `setuptools` and `wheel` packages. {% data variables.product.prodname_dotcom %}-hosted runners have the pip package manager installed. You can use pip to install dependencies from the PyPI package registry before building and testing your code. For example, the YAML below installs or upgrades the `pip` package installer and the `setuptools` and `wheel` packages.
You can also cache dependencies to speed up your workflow. For more information, see "[Caching dependencies to speed up your workflow](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)." When using {% data variables.product.prodname_dotcom %}-hosted runners, you can also cache dependencies to speed up your workflow. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
{% raw %} {% raw %}
```yaml ```yaml
@@ -228,7 +228,7 @@ steps:
#### Caching Dependencies #### Caching Dependencies
You can cache pip dependencies using a unique key, and restore the dependencies when you run future workflows using the [`cache`](https://github.com/marketplace/actions/cache) action. For more information, see "[Caching dependencies to speed up workflows](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)." When using {% data variables.product.prodname_dotcom %}-hosted runners, you can cache pip dependencies using a unique key, and restore the dependencies when you run future workflows using the [`cache`](https://github.com/marketplace/actions/cache) action. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
Pip caches dependencies in different locations, depending on the operating system of the runner. The path you'll need to cache may differ from the Ubuntu example below depending on the operating system you use. For more information, see [Python caching examples](https://github.com/actions/cache/blob/main/examples.md#python---pip). Pip caches dependencies in different locations, depending on the operating system of the runner. The path you'll need to cache may differ from the Ubuntu example below depending on the operating system you use. For more information, see [Python caching examples](https://github.com/actions/cache/blob/main/examples.md#python---pip).

4
content/actions/guides/building-and-testing-ruby.md
View File

@@ -148,7 +148,7 @@ steps:
#### Caching dependencies #### Caching dependencies
The `setup-ruby` actions provides a method to automatically handle the caching of your gems between runs. If you are using {% data variables.product.prodname_dotcom %}-hosted runners, the `setup-ruby` actions provides a method to automatically handle the caching of your gems between runs.
To enable caching, set the following. To enable caching, set the following.
@@ -165,7 +165,7 @@ This will configure bundler to install your gems to `vendor/cache`. For each suc
**Caching without setup-ruby** **Caching without setup-ruby**
For greater control over caching, you can use the `actions/cache` Action directly. For more information, see "[Caching dependencies to speed up your workflow](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)." For greater control over caching, if you are using {% data variables.product.prodname_dotcom %}-hosted runners, you can use the `actions/cache` Action directly. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
{% raw %} {% raw %}
```yaml ```yaml

2
content/actions/guides/publishing-nodejs-packages.md
View File

@@ -8,8 +8,6 @@ redirect_from:
versions: versions:
free-pro-team: '*' free-pro-team: '*'
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
authors:
- GitHub
--- ---
{% data reusables.actions.enterprise-beta %} {% data reusables.actions.enterprise-beta %}

2
content/actions/guides/setting-up-continuous-integration-using-workflow-templates.md
View File

@@ -11,8 +11,6 @@ redirect_from:
versions: versions:
free-pro-team: '*' free-pro-team: '*'
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
authors:
- GitHub
--- ---
{% data reusables.actions.enterprise-beta %} {% data reusables.actions.enterprise-beta %}

2
content/actions/guides/storing-workflow-data-as-artifacts.md
View File

@@ -131,7 +131,7 @@ The `retention-days` value cannot exceed the retention limit set by the reposito
During a workflow run, you can use the [`download-artifact`](https://github.com/actions/download-artifact)action to download artifacts that were previously uploaded in the same workflow run. During a workflow run, you can use the [`download-artifact`](https://github.com/actions/download-artifact)action to download artifacts that were previously uploaded in the same workflow run.
After a workflow run has been completed, you can download or delete artifacts on {% data variables.product.prodname_dotcom %} or using the REST API. For more information, see "[Downloading workflow artifacts](/actions/managing-workflow-runs/downloading-workflow-artifacts)," "[Removing workflow artifacts](/actions/managing-workflow-runs/removing-workflow-artifacts)," and the "[Artifacts REST API](/v3/actions/artifacts/)." After a workflow run has been completed, you can download or delete artifacts on {% data variables.product.prodname_dotcom %} or using the REST API. For more information, see "[Downloading workflow artifacts](/actions/managing-workflow-runs/downloading-workflow-artifacts)," "[Removing workflow artifacts](/actions/managing-workflow-runs/removing-workflow-artifacts)," and the "[Artifacts REST API](/rest/reference/actions#artifacts)."
#### Downloading artifacts during a workflow run #### Downloading artifacts during a workflow run

2
content/actions/hosting-your-own-runners/about-self-hosted-runners.md
View File

@@ -87,7 +87,7 @@ The following operating systems are supported for the self-hosted runner applica
- Windows Server 2016 64-bit - Windows Server 2016 64-bit
- Windows Server 2019 64-bit - Windows Server 2019 64-bit
#### MacOS #### macOS
- macOS 10.13 (High Sierra) or later - macOS 10.13 (High Sierra) or later

4
content/actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups.md
View File

@@ -48,7 +48,9 @@ When creating a group, you must choose a policy that defines which repositories
{% warning %} {% warning %}
**Warning** **Warning**
{% indented_data_reference site.data.reusables.github-actions.self-hosted-runner-security spaces=3 %} {% indented_data_reference site.data.reusables.github-actions.self-hosted-runner-security spaces=3 %}
For more information, see "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners#self-hosted-runner-security-with-public-repositories)." For more information, see "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners#self-hosted-runner-security-with-public-repositories)."
{% endwarning %} {% endwarning %}
@@ -78,7 +80,9 @@ When creating a group, you must choose a policy that defines which organizations
{% warning %} {% warning %}
**Warning** **Warning**
{% indented_data_reference site.data.reusables.github-actions.self-hosted-runner-security spaces=3 %} {% indented_data_reference site.data.reusables.github-actions.self-hosted-runner-security spaces=3 %}
For more information, see "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners#self-hosted-runner-security-with-public-repositories)." For more information, see "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners#self-hosted-runner-security-with-public-repositories)."
{% endwarning %} {% endwarning %}

12
content/actions/learn-github-actions/managing-complex-workflows.md
View File

@@ -12,11 +12,11 @@ versions:
### Overview ### Overview
This article describes some of the advanced features of {% data variables.product.prodname_actions %} that help you work create more complex workflows. This article describes some of the advanced features of {% data variables.product.prodname_actions %} that help you work create more complex workflows.
### Storing secrets ### Storing secrets
If your workflows use sensitive data, such as passwords or certificates, you can save these in {% data variables.product.prodname_dotcom %} as _secrets_ and then use them in your workflows as environment variables. This means that you will be able to create and share workflows without having to embed sensitive values directly in the YAML workflow. If your workflows use sensitive data, such as passwords or certificates, you can save these in {% data variables.product.prodname_dotcom %} as _secrets_ and then use them in your workflows as environment variables. This means that you will be able to create and share workflows without having to embed sensitive values directly in the YAML workflow.
This example action demonstrates how to reference an existing secret as an environment variable, and send it as a parameter to an example command. This example action demonstrates how to reference an existing secret as an environment variable, and send it as a parameter to an example command.
@@ -57,7 +57,7 @@ jobs:
needs: build needs: build
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- run: ./test_server.sh - run: ./test_server.sh
``` ```
For more information, see [`jobs.<job_id>.needs`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idneeds). For more information, see [`jobs.<job_id>.needs`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idneeds).
@@ -85,7 +85,7 @@ For more information, see [`jobs.<job_id>.strategy.matrix`](/actions/reference/w
### Caching dependencies ### Caching dependencies
{% data variables.product.prodname_dotcom %}-hosted runners are started as fresh environments for each job, so if your jobs regularly reuse dependencies, you can consider caching these files to help improve performance. Once the cache is created, it is available to all workflows in the same repository. {% data variables.product.prodname_dotcom %}-hosted runners are started as fresh environments for each job, so if your jobs regularly reuse dependencies, you can consider caching these files to help improve performance. Once the cache is created, it is available to all workflows in the same repository.
This example demonstrates how to cache the ` ~/.npm` directory: This example demonstrates how to cache the ` ~/.npm` directory:
@@ -106,7 +106,7 @@ jobs:
``` ```
{% endraw %} {% endraw %}
For more information, see "[Caching dependencies to speed up workflows](/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows)." For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
### Using databases and service containers ### Using databases and service containers
@@ -136,7 +136,7 @@ For more information, see "[Using databases and service containers](/actions/con
### Using labels to route workflows ### Using labels to route workflows
This feature helps you assign jobs to a specific self-hosted runner. If you want to be sure that a particular type of runner will process your job, you can use labels to control where jobs are executed. You can assign labels to a self-hosted runner, and then refer to these labels in your YAML workflow, ensuring that the job is routed in a predictable way. This feature helps you assign jobs to a specific self-hosted runner. If you want to be sure that a particular type of runner will process your job, you can use labels to control where jobs are executed. You can assign labels to a self-hosted runner, and then refer to these labels in your YAML workflow, ensuring that the job is routed in a predictable way.
This example shows how a workflow can use labels to specify the required runner: This example shows how a workflow can use labels to specify the required runner:

2
content/actions/learn-github-actions/migrating-from-circleci-to-github-actions.md
View File

@@ -101,7 +101,7 @@ GitHub Actions
</tr> </tr>
</table> </table>
For more information, see "[Caching dependencies to speed up workflows](/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows)." {% data variables.product.prodname_actions %} caching is only applicable to {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
{% data variables.product.prodname_actions %} does not have an equivalent of CircleCI’s Docker Layer Caching (or DLC). {% data variables.product.prodname_actions %} does not have an equivalent of CircleCI’s Docker Layer Caching (or DLC).

16
content/actions/learn-github-actions/migrating-from-gitlab-cicd-to-github-actions.md
View File

@@ -262,7 +262,7 @@ jobs:
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- run: echo "This job will be run first, in parallel with build_a" - run: echo "This job will be run first, in parallel with build_a"
test_ab: test_ab:
runs-on: ubuntu-latest runs-on: ubuntu-latest
needs: [build_a,build_b] needs: [build_a,build_b]
@@ -346,7 +346,7 @@ jobs:
</tr> </tr>
</table> </table>
For more information, see "[Caching dependencies to speed up workflows](/actions/guides/caching-dependencies-to-speed-up-workflows)." {% data variables.product.prodname_actions %} caching is only applicable to {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
### Artifacts ### Artifacts
@@ -367,7 +367,7 @@ GitLab CI/CD
<td class="d-table-cell v-align-top"> <td class="d-table-cell v-align-top">
{% raw %} {% raw %}
```yaml ```yaml
script: script:
artifacts: artifacts:
paths: paths:
- math-homework.txt - math-homework.txt
@@ -414,7 +414,7 @@ GitLab CI/CD
container-job: container-job:
variables: variables:
POSTGRES_PASSWORD: postgres POSTGRES_PASSWORD: postgres
# The hostname used to communicate with the # The hostname used to communicate with the
# PostgreSQL service container # PostgreSQL service container
POSTGRES_HOST: postgres POSTGRES_HOST: postgres
# The default PostgreSQL port # The default PostgreSQL port
@@ -423,10 +423,10 @@ container-job:
services: services:
- postgres - postgres
script: script:
# Performs a clean installation of all dependencies # Performs a clean installation of all dependencies
# in the `package.json` file # in the `package.json` file
- npm ci - npm ci
# Runs a script that creates a PostgreSQL client, # Runs a script that creates a PostgreSQL client,
# populates the client with data, and retrieves data # populates the client with data, and retrieves data
- node client.js - node client.js
tags: tags:
@@ -452,7 +452,7 @@ jobs:
- name: Check out repository code - name: Check out repository code
uses: actions/checkout@v2 uses: actions/checkout@v2
# Performs a clean installation of all dependencies # Performs a clean installation of all dependencies
# in the `package.json` file # in the `package.json` file
- name: Install dependencies - name: Install dependencies
run: npm ci run: npm ci
@@ -462,7 +462,7 @@ jobs:
# populates the client with data, and retrieves data # populates the client with data, and retrieves data
run: node client.js run: node client.js
env: env:
# The hostname used to communicate with the # The hostname used to communicate with the
# PostgreSQL service container # PostgreSQL service container
POSTGRES_HOST: postgres POSTGRES_HOST: postgres
# The default PostgreSQL port # The default PostgreSQL port

14
content/actions/learn-github-actions/migrating-from-travis-ci-to-github-actions.md
View File

@@ -164,6 +164,12 @@ git:
</tr> </tr>
</table> </table>
#### Using environment variables in a matrix
Travis CI and {% data variables.product.prodname_actions %} can both add custom environment variables to a test matrix, which allows you to refer to the variable in a later step.
In {% data variables.product.prodname_actions %}, you can use the `include` key to add custom environment variables to a matrix. {% data reusables.github-actions.matrix-variable-example %}
### Key features in {% data variables.product.prodname_actions %} ### Key features in {% data variables.product.prodname_actions %}
When migrating from Travis CI, consider the following key features in {% data variables.product.prodname_actions %}: When migrating from Travis CI, consider the following key features in {% data variables.product.prodname_actions %}:
@@ -178,7 +184,7 @@ When migrating from Travis CI, consider the following key features in {% data va
#### Hosting your own runners #### Hosting your own runners
If your jobs require specific hardware or software, {% data variables.product.prodname_actions %} allows you to host your own runners and send your jobs to them for processing. {% data variables.product.prodname_actions %} also lets you use policies to control how these runners are accessed, granting access at the organization or repository level. For more information, see ["Hosting your own runners](/actions/hosting-your-own-runners)." If your jobs require specific hardware or software, {% data variables.product.prodname_actions %} allows you to host your own runners and send your jobs to them for processing. {% data variables.product.prodname_actions %} also lets you use policies to control how these runners are accessed, granting access at the organization or repository level. For more information, see ["Hosting your own runners](/actions/hosting-your-own-runners)."
#### Concurrent jobs and execution time #### Concurrent jobs and execution time
@@ -207,7 +213,7 @@ For example:
shell: bash shell: bash
``` ```
### Error handling in {% data variables.product.prodname_actions %} ### Error handling in {% data variables.product.prodname_actions %}
When migrating to {% data variables.product.prodname_actions %}, there are different approaches to error handling that you might need to be aware of. When migrating to {% data variables.product.prodname_actions %}, there are different approaches to error handling that you might need to be aware of.
@@ -282,7 +288,7 @@ jobs:
### Caching dependencies ### Caching dependencies
Travis CI and {% data variables.product.prodname_actions %} let you manually cache dependencies for later reuse. This example demonstrates the cache syntax for each system. Travis CI and {% data variables.product.prodname_actions %} let you manually cache dependencies for later reuse. This example demonstrates the cache syntax for each system.
<table> <table>
<tr> <tr>
@@ -317,7 +323,7 @@ cache: npm
</tr> </tr>
</table> </table>
For more information, see "[Caching dependencies to speed up workflows](/actions/guides/caching-dependencies-to-speed-up-workflows)." {% data variables.product.prodname_actions %} caching is only applicable to {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
### Examples of common tasks ### Examples of common tasks

2
content/actions/managing-workflow-runs/using-workflow-run-logs.md
View File

@@ -14,7 +14,7 @@ You can see whether a workflow run is in progress or complete from the workflow
If the run is complete, you can see whether the result was a success, failure, canceled, or neutral. If the run failed, you can view and search the build logs to diagnose the failure and re-run the workflow. You can also view billable job execution minutes, or download logs and build artifacts. If the run is complete, you can see whether the result was a success, failure, canceled, or neutral. If the run failed, you can view and search the build logs to diagnose the failure and re-run the workflow. You can also view billable job execution minutes, or download logs and build artifacts.
{% data variables.product.prodname_actions %} use the Checks API to output statuses, results, and logs for a workflow. {% data variables.product.prodname_dotcom %} creates a new check suite for each workflow run. The check suite contains a check run for each job in the workflow, and each job includes steps. {% data variables.product.prodname_actions %} are run as a step in a workflow. For more information about the Checks API, see "[Checks](/v3/checks/)." {% data variables.product.prodname_actions %} use the Checks API to output statuses, results, and logs for a workflow. {% data variables.product.prodname_dotcom %} creates a new check suite for each workflow run. The check suite contains a check run for each job in the workflow, and each job includes steps. {% data variables.product.prodname_actions %} are run as a step in a workflow. For more information about the Checks API, see "[Checks](/rest/reference/checks)."
{% data reusables.github-actions.invalid-workflow-files %} {% data reusables.github-actions.invalid-workflow-files %}

2
content/actions/quickstart.md
View File

@@ -103,7 +103,7 @@ Printing "Hello, World!" is a great way to explore the basic set up and syntax o
# When the event is triggered, GitHub Actions will run the jobs indicated # When the event is triggered, GitHub Actions will run the jobs indicated
jobs: jobs:
say_hello: say_hello:
# Uses a ubuntu-lates runner to complete the requested steps # Uses a ubuntu-latest runner to complete the requested steps
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- run: | - run: |

2
content/actions/reference/authentication-in-a-workflow.md
View File

@@ -79,7 +79,7 @@ You can use the `GITHUB_TOKEN` to make authenticated API calls. This example wor
### Permissions for the `GITHUB_TOKEN` ### Permissions for the `GITHUB_TOKEN`
For information about the API endpoints {% data variables.product.prodname_github_apps %} can access with each permission, see "[{% data variables.product.prodname_github_app %} Permissions](/v3/apps/permissions/)." For information about the API endpoints {% data variables.product.prodname_github_apps %} can access with each permission, see "[{% data variables.product.prodname_github_app %} Permissions](/rest/reference/permissions-required-for-github-apps)."
| Permission | Access type | Access by forked repos | | Permission | Access type | Access by forked repos |
|------------|-------------|--------------------------| |------------|-------------|--------------------------|

12
content/actions/reference/context-and-expression-syntax-for-github-actions.md
View File

@@ -75,7 +75,7 @@ In order to use property dereference syntax, the property name must:
- start with `a-Z` or `_`. - start with `a-Z` or `_`.
- be followed by `a-Z` `0-9` `-` or `_`. - be followed by `a-Z` `0-9` `-` or `_`.
#### **`github` context** #### `github` context
The `github` context contains information about the workflow run and the event that triggered the run. You can read most of the `github` context data in environment variables. For more information about environment variables, see "[Using environment variables](/actions/automating-your-workflow-with-github-actions/using-environment-variables)." The `github` context contains information about the workflow run and the event that triggered the run. You can read most of the `github` context data in environment variables. For more information about environment variables, see "[Using environment variables](/actions/automating-your-workflow-with-github-actions/using-environment-variables)."
@@ -103,7 +103,7 @@ The `github` context contains information about the workflow run and the event t
| `github.workflow` | `string` | The name of the workflow. If the workflow file doesn't specify a `name`, the value of this property is the full path of the workflow file in the repository. | | `github.workflow` | `string` | The name of the workflow. If the workflow file doesn't specify a `name`, the value of this property is the full path of the workflow file in the repository. |
| `github.workspace` | `string` | The default working directory for steps and the default location of your repository when using the [`checkout`](https://github.com/actions/checkout) action. | | `github.workspace` | `string` | The default working directory for steps and the default location of your repository when using the [`checkout`](https://github.com/actions/checkout) action. |
#### **`env` context** #### `env` context
The `env` context contains environment variables that have been set in a workflow, job, or step. For more information about setting environment variables in your workflow, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#env)." The `env` context contains environment variables that have been set in a workflow, job, or step. For more information about setting environment variables in your workflow, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#env)."
@@ -117,7 +117,7 @@ You can only use the `env` context in the value of the `with` and `name` keys, o
| `env.<env name>` | `string` | The value of a specific environment variable. | | `env.<env name>` | `string` | The value of a specific environment variable. |
#### **`job` context** #### `job` context
The `job` context contains information about the currently running job. The `job` context contains information about the currently running job.
@@ -133,7 +133,7 @@ The `job` context contains information about the currently running job.
| `job.services.<service id>.ports` | `object` | The exposed ports of the service container. | | `job.services.<service id>.ports` | `object` | The exposed ports of the service container. |
| `job.status` | `string` | The current status of the job. Possible values are `success`, `failure`, or `cancelled`. | | `job.status` | `string` | The current status of the job. Possible values are `success`, `failure`, or `cancelled`. |
#### **`steps` context** #### `steps` context
The `steps` context contains information about the steps in the current job that have already run. The `steps` context contains information about the steps in the current job that have already run.
@@ -145,7 +145,7 @@ The `steps` context contains information about the steps in the current job that
| `steps.<step id>.outcome` | `string` | The result of a completed step before [`continue-on-error`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepscontinue-on-error) is applied. Possible values are `success`, `failure`, `cancelled`, or `skipped`. When a `continue-on-error` step fails, the `outcome` is `failure`, but the final `conclusion` is `success`. | | `steps.<step id>.outcome` | `string` | The result of a completed step before [`continue-on-error`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepscontinue-on-error) is applied. Possible values are `success`, `failure`, `cancelled`, or `skipped`. When a `continue-on-error` step fails, the `outcome` is `failure`, but the final `conclusion` is `success`. |
| `steps.<step id>.outputs.<output name>` | `string` | The value of a specific output. | | `steps.<step id>.outputs.<output name>` | `string` | The value of a specific output. |
#### **`runner` context** #### `runner` context
The `runner` context contains information about the runner that is executing the current job. The `runner` context contains information about the runner that is executing the current job.
@@ -155,7 +155,7 @@ The `runner` context contains information about the runner that is executing the
| `runner.temp` | `string` | The path of the temporary directory for the runner. This directory is guaranteed to be empty at the start of each job, even on self-hosted runners. | | `runner.temp` | `string` | The path of the temporary directory for the runner. This directory is guaranteed to be empty at the start of each job, even on self-hosted runners. |
| `runner.tool_cache` | `string` | The path of the directory containing some of the preinstalled tools for {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)". | | `runner.tool_cache` | `string` | The path of the directory containing some of the preinstalled tools for {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)". |
#### **`needs` context** #### `needs` context
The `needs` context contains outputs from all jobs that are defined as a dependency of the current job. For more information on defining job dependencies, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idneeds)." The `needs` context contains outputs from all jobs that are defined as a dependency of the current job. For more information on defining job dependencies, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idneeds)."

4
content/actions/reference/encrypted-secrets.md
View File

@@ -43,11 +43,11 @@ You can use and read encrypted secrets in a workflow file if you have access to
{% endwarning %} {% endwarning %}
You can also manage secrets using the REST API. For more information, see "[Secrets](/v3/actions/secrets/)." You can also manage secrets using the REST API. For more information, see "[Secrets](/rest/reference/actions#secrets)."
#### Limiting credential permissions #### Limiting credential permissions
When generating credentials, we recommend that you grant the minimum permissions possible. For example, instead of using personal credentials, use [deploy keys](/v3/guides/managing-deploy-keys/#deploy-keys) or a service account. Consider granting read-only permissions if that's all that is needed, and limit access as much as possible. When generating a personal access token (PAT), select the fewest scopes necessary. When generating credentials, we recommend that you grant the minimum permissions possible. For example, instead of using personal credentials, use [deploy keys](/developers/overview/managing-deploy-keys#deploy-keys) or a service account. Consider granting read-only permissions if that's all that is needed, and limit access as much as possible. When generating a personal access token (PAT), select the fewest scopes necessary.
### Creating encrypted secrets for a repository ### Creating encrypted secrets for a repository

40
content/actions/reference/events-that-trigger-workflows.md
View File

@@ -143,7 +143,7 @@ jobs:
{% data reusables.github-actions.branch-requirement %} {% data reusables.github-actions.branch-requirement %}
You can use the {% data variables.product.product_name %} API to trigger a webhook event called [`repository_dispatch`](/webhooks/event-payloads/#repository_dispatch) when you want to trigger a workflow for activity that happens outside of {% data variables.product.prodname_dotcom %}. For more information, see "[Create a repository dispatch event](/v3/repos/#create-a-repository-dispatch-event)." You can use the {% data variables.product.product_name %} API to trigger a webhook event called [`repository_dispatch`](/webhooks/event-payloads/#repository_dispatch) when you want to trigger a workflow for activity that happens outside of {% data variables.product.prodname_dotcom %}. For more information, see "[Create a repository dispatch event](/rest/reference/repos#create-a-repository-dispatch-event)."
To trigger the custom `repository_dispatch` webhook event, you must send a `POST` request to a {% data variables.product.product_name %} API endpoint and provide an `event_type` name to describe the activity type. To trigger a workflow run, you must also configure your workflow to use the `repository_dispatch` event. To trigger the custom `repository_dispatch` webhook event, you must send a `POST` request to a {% data variables.product.product_name %} API endpoint and provide an `event_type` name to describe the activity type. To trigger a workflow run, you must also configure your workflow to use the `repository_dispatch` event.
@@ -163,7 +163,7 @@ You can configure your workflow to run when webhook events are created on {% dat
#### `check_run` #### `check_run`
Runs your workflow anytime the `check_run` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Check runs](/v3/checks/runs/)." Runs your workflow anytime the `check_run` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Check runs](/rest/reference/checks#runs)."
{% data reusables.github-actions.branch-requirement %} {% data reusables.github-actions.branch-requirement %}
@@ -183,7 +183,7 @@ on:
#### `check_suite` #### `check_suite`
Runs your workflow anytime the `check_suite` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Check suites](/v3/checks/suites/)." Runs your workflow anytime the `check_suite` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Check suites](/rest/reference/checks#suites)."
{% data reusables.github-actions.branch-requirement %} {% data reusables.github-actions.branch-requirement %}
@@ -209,7 +209,7 @@ on:
#### `create` #### `create`
Runs your workflow anytime someone creates a branch or tag, which triggers the `create` event. For information about the REST API, see "[Create a reference](/v3/git/refs/#create-a-reference)." Runs your workflow anytime someone creates a branch or tag, which triggers the `create` event. For information about the REST API, see "[Create a reference](/rest/reference/git#create-a-reference)."
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
@@ -224,7 +224,7 @@ on:
#### `delete` #### `delete`
Runs your workflow anytime someone deletes a branch or tag, which triggers the `delete` event. For information about the REST API, see "[Delete a reference](/v3/git/refs/#delete-a-reference)." Runs your workflow anytime someone deletes a branch or tag, which triggers the `delete` event. For information about the REST API, see "[Delete a reference](/rest/reference/git#delete-a-reference)."
{% data reusables.github-actions.branch-requirement %} {% data reusables.github-actions.branch-requirement %}
@@ -271,7 +271,7 @@ on:
#### `fork` #### `fork`
Runs your workflow anytime when someone forks a repository, which triggers the `fork` event. For information about the REST API, see "[Create a fork](/v3/repos/forks/#create-a-fork)." Runs your workflow anytime when someone forks a repository, which triggers the `fork` event. For information about the REST API, see "[Create a fork](/rest/reference/repos#create-a-fork)."
{% data reusables.github-actions.branch-requirement %} {% data reusables.github-actions.branch-requirement %}
@@ -354,7 +354,7 @@ jobs:
#### `issues` #### `issues`
Runs your workflow anytime the `issues` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Issues](/v3/issues)." Runs your workflow anytime the `issues` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Issues](/rest/reference/issues)."
{% data reusables.github-actions.branch-requirement %} {% data reusables.github-actions.branch-requirement %}
@@ -374,7 +374,7 @@ on:
#### `label` #### `label`
Runs your workflow anytime the `label` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Labels](/v3/issues/labels/)." Runs your workflow anytime the `label` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Labels](/rest/reference/issues#labels)."
{% data reusables.github-actions.branch-requirement %} {% data reusables.github-actions.branch-requirement %}
@@ -394,7 +394,7 @@ on:
#### `milestone` #### `milestone`
Runs your workflow anytime the `milestone` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Milestones](/v3/issues/milestones/)." Runs your workflow anytime the `milestone` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Milestones](/rest/reference/issues#milestones)."
{% data reusables.github-actions.branch-requirement %} {% data reusables.github-actions.branch-requirement %}
@@ -431,7 +431,7 @@ on:
#### `project` #### `project`
Runs your workflow anytime the `project` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Projects](/v3/projects/)." Runs your workflow anytime the `project` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Projects](/rest/reference/projects)."
{% data reusables.github-actions.branch-requirement %} {% data reusables.github-actions.branch-requirement %}
@@ -451,7 +451,7 @@ on:
#### `project_card` #### `project_card`
Runs your workflow anytime the `project_card` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Project cards](/v3/projects/cards)." Runs your workflow anytime the `project_card` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Project cards](/rest/reference/projects#cards)."
{% data reusables.github-actions.branch-requirement %} {% data reusables.github-actions.branch-requirement %}
@@ -471,7 +471,7 @@ on:
#### `project_column` #### `project_column`
Runs your workflow anytime the `project_column` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Project columns](/v3/projects/columns)." Runs your workflow anytime the `project_column` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Project columns](/rest/reference/projects#columns)."
{% data reusables.github-actions.branch-requirement %} {% data reusables.github-actions.branch-requirement %}
@@ -491,7 +491,7 @@ on:
#### `public` #### `public`
Runs your workflow anytime someone makes a private repository public, which triggers the `public` event. For information about the REST API, see "[Edit repositories](/v3/repos/#edit)." Runs your workflow anytime someone makes a private repository public, which triggers the `public` event. For information about the REST API, see "[Edit repositories](/rest/reference/repos#edit)."
{% data reusables.github-actions.branch-requirement %} {% data reusables.github-actions.branch-requirement %}
@@ -508,7 +508,7 @@ on:
#### `pull_request` #### `pull_request`
Runs your workflow anytime the `pull_request` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Pull requests](/v3/pulls)." Runs your workflow anytime the `pull_request` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Pull requests](/rest/reference/pulls)."
{% note %} {% note %}
@@ -534,7 +534,7 @@ on:
#### `pull_request_review` #### `pull_request_review`
Runs your workflow anytime the `pull_request_review` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Pull request reviews](/v3/pulls/reviews)." Runs your workflow anytime the `pull_request_review` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Pull request reviews](/rest/reference/pulls#reviews)."
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
@@ -554,7 +554,7 @@ on:
#### `pull_request_review_comment` #### `pull_request_review_comment`
Runs your workflow anytime a comment on a pull request's unified diff is modified, which triggers the `pull_request_review_comment` event. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see [Review comments](/v3/pulls/comments). Runs your workflow anytime a comment on a pull request's unified diff is modified, which triggers the `pull_request_review_comment` event. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see [Review comments](/rest/reference/pulls#comments).
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
@@ -597,7 +597,7 @@ on: pull_request_target
{% note %} {% note %}
**Note:** The webhook payload available to GitHub Actions does not include the `added`, `removed`, and `modified` attributes in the `commit` object. You can retrieve the full commit object using the REST API. For more information, see "[Get a single commit](/v3/repos/commits/#get-a-single-commit)"". **Note:** The webhook payload available to GitHub Actions does not include the `added`, `removed`, and `modified` attributes in the `commit` object. You can retrieve the full commit object using the REST API. For more information, see "[Get a single commit](/rest/reference/repos#get-a-single-commit)"".
{% endnote %} {% endnote %}
@@ -640,7 +640,7 @@ on:
{% endnote %} {% endnote %}
Runs your workflow anytime the `release` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Releases](/v3/repos/releases/)." Runs your workflow anytime the `release` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Releases](/rest/reference/repos#releases)."
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
@@ -658,7 +658,7 @@ on:
#### `status` #### `status`
Runs your workflow anytime the status of a Git commit changes, which triggers the `status` event. For information about the REST API, see [Statuses](/v3/repos/statuses/). Runs your workflow anytime the status of a Git commit changes, which triggers the `status` event. For information about the REST API, see [Statuses](/rest/reference/repos#statuses).
{% data reusables.github-actions.branch-requirement %} {% data reusables.github-actions.branch-requirement %}
@@ -675,7 +675,7 @@ on:
#### `watch` #### `watch`
Runs your workflow anytime the `watch` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Starring](/v3/activity/starring/)." Runs your workflow anytime the `watch` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Starring](/rest/reference/activity#starring)."
{% data reusables.github-actions.branch-requirement %} {% data reusables.github-actions.branch-requirement %}

4
content/actions/reference/specifications-for-github-hosted-runners.md
View File

@@ -63,8 +63,8 @@ The software tools included in {% data variables.product.prodname_dotcom %}-host
* [Ubuntu 16.04 LTS](https://github.com/actions/virtual-environments/blob/main/images/linux/Ubuntu1604-README.md) * [Ubuntu 16.04 LTS](https://github.com/actions/virtual-environments/blob/main/images/linux/Ubuntu1604-README.md)
* [Windows Server 2019](https://github.com/actions/virtual-environments/blob/main/images/win/Windows2019-Readme.md) * [Windows Server 2019](https://github.com/actions/virtual-environments/blob/main/images/win/Windows2019-Readme.md)
* [Windows Server 2016](https://github.com/actions/virtual-environments/blob/main/images/win/Windows2016-Readme.md) * [Windows Server 2016](https://github.com/actions/virtual-environments/blob/main/images/win/Windows2016-Readme.md)
* [MacOS 10.15](https://github.com/actions/virtual-environments/blob/main/images/macos/macos-10.15-Readme.md) * [macOS 10.15](https://github.com/actions/virtual-environments/blob/main/images/macos/macos-10.15-Readme.md)
* [MacOS 11.0](https://github.com/actions/virtual-environments/blob/main/images/macos/macos-11.0-Readme.md) * [macOS 11.0](https://github.com/actions/virtual-environments/blob/main/images/macos/macos-11.0-Readme.md)
{% data reusables.github-actions.ubuntu-runner-preview %} {% data reusables.github-actions.ubuntu-runner-preview %}
{% data reusables.github-actions.macos-runner-preview %} {% data reusables.github-actions.macos-runner-preview %}

2
content/actions/reference/usage-limits-billing-and-administration.md
View File

@@ -76,6 +76,7 @@ For more information, see:
- "[Disabling or limiting {% data variables.product.prodname_actions %} for your organization](/github/setting-up-and-managing-organizations-and-teams/disabling-or-limiting-github-actions-for-your-organization)"{% if currentVersion == "free-pro-team@latest" %} - "[Disabling or limiting {% data variables.product.prodname_actions %} for your organization](/github/setting-up-and-managing-organizations-and-teams/disabling-or-limiting-github-actions-for-your-organization)"{% if currentVersion == "free-pro-team@latest" %}
- "[Enforcing {% data variables.product.prodname_actions %} policies in your enterprise account](/github/setting-up-and-managing-your-enterprise/enforcing-github-actions-policies-in-your-enterprise-account)" for {% data variables.product.prodname_ghe_cloud %}{% endif %} - "[Enforcing {% data variables.product.prodname_actions %} policies in your enterprise account](/github/setting-up-and-managing-your-enterprise/enforcing-github-actions-policies-in-your-enterprise-account)" for {% data variables.product.prodname_ghe_cloud %}{% endif %}
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %}
### Disabling and enabling workflows ### Disabling and enabling workflows
You can enable and disable individual workflows in your repository on {% data variables.product.prodname_dotcom %}. You can enable and disable individual workflows in your repository on {% data variables.product.prodname_dotcom %}.
@@ -83,3 +84,4 @@ You can enable and disable individual workflows in your repository on {% data va
{% data reusables.actions.scheduled-workflows-disabled %} {% data reusables.actions.scheduled-workflows-disabled %}
For more information, see "[Disabling and enabling a workflow](/actions/managing-workflow-runs/disabling-and-enabling-a-workflow)." For more information, see "[Disabling and enabling a workflow](/actions/managing-workflow-runs/disabling-and-enabling-a-workflow)."
{% endif %}

201
content/actions/reference/workflow-syntax-for-github-actions.md
View File

@@ -21,17 +21,17 @@ Workflow files use YAML syntax, and must have either a `.yml` or `.yaml` file ex
You must store workflow files in the `.github/workflows` directory of your repository. You must store workflow files in the `.github/workflows` directory of your repository.
### **`name`** ### `name`
The name of your workflow. {% data variables.product.prodname_dotcom %} displays the names of your workflows on your repository's actions page. If you omit `name`, {% data variables.product.prodname_dotcom %} sets it to the workflow file path relative to the root of the repository. The name of your workflow. {% data variables.product.prodname_dotcom %} displays the names of your workflows on your repository's actions page. If you omit `name`, {% data variables.product.prodname_dotcom %} sets it to the workflow file path relative to the root of the repository.
### **`on`** ### `on`
**Required** The name of the {% data variables.product.prodname_dotcom %} event that triggers the workflow. You can provide a single event `string`, `array` of events, `array` of event `types`, or an event configuration `map` that schedules a workflow or restricts the execution of a workflow to specific files, tags, or branch changes. For a list of available events, see "[Events that trigger workflows](/articles/events-that-trigger-workflows)." **Required** The name of the {% data variables.product.prodname_dotcom %} event that triggers the workflow. You can provide a single event `string`, `array` of events, `array` of event `types`, or an event configuration `map` that schedules a workflow or restricts the execution of a workflow to specific files, tags, or branch changes. For a list of available events, see "[Events that trigger workflows](/articles/events-that-trigger-workflows)."
{% data reusables.github-actions.actions-on-examples %} {% data reusables.github-actions.actions-on-examples %}
### **`on.<event_name>.types`** ### `on.<event_name>.types`
Selects the types of activity that will trigger a workflow run. Most GitHub events are triggered by more than one type of activity. For example, the event for the release resource is triggered when a release is `published`, `unpublished`, `created`, `edited`, `deleted`, or `prereleased`. The `types` keyword enables you to narrow down activity that causes the workflow to run. When only one activity type triggers a webhook event, the `types` keyword is unnecessary. Selects the types of activity that will trigger a workflow run. Most GitHub events are triggered by more than one type of activity. For example, the event for the release resource is triggered when a release is `published`, `unpublished`, `created`, `edited`, `deleted`, or `prereleased`. The `types` keyword enables you to narrow down activity that causes the workflow to run. When only one activity type triggers a webhook event, the `types` keyword is unnecessary.
@@ -45,7 +45,7 @@ on:
types: [published, created, edited] types: [published, created, edited]
``` ```
### **`on.<push|pull_request>.<branches|tags>`** ### `on.<push|pull_request>.<branches|tags>`
When using the `push` and `pull_request` events, you can configure a workflow to run on specific branches or tags. For a `pull_request` event, only branches and tags on the base are evaluated. If you define only `tags` or only `branches`, the workflow won't run for events affecting the undefined Git ref. When using the `push` and `pull_request` events, you can configure a workflow to run on specific branches or tags. For a `pull_request` event, only branches and tags on the base are evaluated. If you define only `tags` or only `branches`, the workflow won't run for events affecting the undefined Git ref.
@@ -112,7 +112,7 @@ on:
- '!releases/**-alpha' - '!releases/**-alpha'
``` ```
### **`on.<push|pull_request>.paths`** ### `on.<push|pull_request>.paths`
When using the `push` and `pull_request` events, you can configure a workflow to run when at least one file does not match `paths-ignore` or at least one modified file matches the configured `paths`. Path filters are not evaluated for pushes to tags. When using the `push` and `pull_request` events, you can configure a workflow to run when at least one file does not match `paths-ignore` or at least one modified file matches the configured `paths`. Path filters are not evaluated for pushes to tags.
@@ -179,13 +179,13 @@ The filter determines if a workflow should run by evaluating the changed files a
For more information, see "[About comparing branches in pull requests](/articles/about-comparing-branches-in-pull-requests)." For more information, see "[About comparing branches in pull requests](/articles/about-comparing-branches-in-pull-requests)."
### **`on.schedule`** ### `on.schedule`
{% data reusables.repositories.actions-scheduled-workflow-example %} {% data reusables.repositories.actions-scheduled-workflow-example %}
For more information about cron syntax, see "[Events that trigger workflows](/actions/automating-your-workflow-with-github-actions/events-that-trigger-workflows#scheduled-events)." For more information about cron syntax, see "[Events that trigger workflows](/actions/automating-your-workflow-with-github-actions/events-that-trigger-workflows#scheduled-events)."
### **`env`** ### `env`
A `map` of environment variables that are available to all jobs and steps in the workflow. You can also set environment variables that are only available to a job or step. For more information, see [`jobs.<job_id>.env`](#jobsjob_idenv) and [`jobs.<job_id>.steps.env`](#jobsjob_idstepsenv). A `map` of environment variables that are available to all jobs and steps in the workflow. You can also set environment variables that are only available to a job or step. For more information, see [`jobs.<job_id>.env`](#jobsjob_idenv) and [`jobs.<job_id>.steps.env`](#jobsjob_idstepsenv).
@@ -198,13 +198,13 @@ env:
SERVER: production SERVER: production
``` ```
### **`defaults`** ### `defaults`
A `map` of default settings that will apply to all jobs in the workflow. You can also set default settings that are only available to a job. For more information, see [`jobs.<job_id>.defaults`](#jobsjob_iddefaults). A `map` of default settings that will apply to all jobs in the workflow. You can also set default settings that are only available to a job. For more information, see [`jobs.<job_id>.defaults`](#jobsjob_iddefaults).
{% data reusables.github-actions.defaults-override %} {% data reusables.github-actions.defaults-override %}
### **`defaults.run`** ### `defaults.run`
You can provide default `shell` and `working-directory` options for all [`run`](#jobsjob_idstepsrun) steps in a workflow. You can also set default settings for `run` that are only available to a job. For more information, see [`jobs.<job_id>.defaults.run`](#jobsjob_iddefaultsrun). You cannot use contexts or expressions in this keyword. You can provide default `shell` and `working-directory` options for all [`run`](#jobsjob_idstepsrun) steps in a workflow. You can also set default settings for `run` that are only available to a job. For more information, see [`jobs.<job_id>.defaults.run`](#jobsjob_iddefaultsrun). You cannot use contexts or expressions in this keyword.
@@ -219,7 +219,7 @@ defaults:
working-directory: scripts working-directory: scripts
``` ```
### **`jobs`** ### `jobs`
A workflow run is made up of one or more jobs. Jobs run in parallel by default. To run jobs sequentially, you can define dependencies on other jobs using the `jobs.<job_id>.needs` keyword. A workflow run is made up of one or more jobs. Jobs run in parallel by default. To run jobs sequentially, you can define dependencies on other jobs using the `jobs.<job_id>.needs` keyword.
@@ -227,9 +227,9 @@ Each job runs in an environment specified by `runs-on`.
You can run an unlimited number of jobs as long as you are within the workflow usage limits. For more information, see "[Usage limits and billing](/actions/reference/usage-limits-billing-and-administration)" for {% data variables.product.prodname_dotcom %}-hosted runners and "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners/#usage-limits)" for self-hosted runner usage limits. You can run an unlimited number of jobs as long as you are within the workflow usage limits. For more information, see "[Usage limits and billing](/actions/reference/usage-limits-billing-and-administration)" for {% data variables.product.prodname_dotcom %}-hosted runners and "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners/#usage-limits)" for self-hosted runner usage limits.
If you need to find the unique identifier of a job running in a workflow run, you can use the {% data variables.product.prodname_dotcom %} API. For more information, see "[Workflow Jobs](/v3/actions/workflow-jobs)." If you need to find the unique identifier of a job running in a workflow run, you can use the {% data variables.product.prodname_dotcom %} API. For more information, see "[Workflow Jobs](/rest/reference/actions#workflow-jobs)."
### **`jobs.<job_id>`** ### `jobs.<job_id>`
Each job must have an id to associate with the job. The key `job_id` is a string and its value is a map of the job's configuration data. You must replace `<job_id>` with a string that is unique to the `jobs` object. The `<job_id>` must start with a letter or `_` and contain only alphanumeric characters, `-`, or `_`. Each job must have an id to associate with the job. The key `job_id` is a string and its value is a map of the job's configuration data. You must replace `<job_id>` with a string that is unique to the `jobs` object. The `<job_id>` must start with a letter or `_` and contain only alphanumeric characters, `-`, or `_`.
@@ -243,11 +243,11 @@ jobs:
name: My second job name: My second job
``` ```
### **`jobs.<job_id>.name`** ### `jobs.<job_id>.name`
The name of the job displayed on {% data variables.product.prodname_dotcom %}. The name of the job displayed on {% data variables.product.prodname_dotcom %}.
### **`jobs.<job_id>.needs`** ### `jobs.<job_id>.needs`
Identifies any jobs that must complete successfully before this job will run. It can be a string or array of strings. If a job fails, all jobs that need it are skipped unless the jobs use a conditional statement that causes the job to continue. Identifies any jobs that must complete successfully before this job will run. It can be a string or array of strings. If a job fails, all jobs that need it are skipped unless the jobs use a conditional statement that causes the job to continue.
@@ -270,7 +270,7 @@ The jobs in this example run sequentially:
2. `job2` 2. `job2`
3. `job3` 3. `job3`
### **`jobs.<job_id>.runs-on`** ### `jobs.<job_id>.runs-on`
**Required** The type of machine to run the job on. The machine can be either a {% data variables.product.prodname_dotcom %}-hosted runner or a self-hosted runner. **Required** The type of machine to run the job on. The machine can be either a {% data variables.product.prodname_dotcom %}-hosted runner or a self-hosted runner.
@@ -286,7 +286,7 @@ Available {% data variables.product.prodname_dotcom %}-hosted runner types are:
{% data reusables.github-actions.ubuntu-runner-preview %} {% data reusables.github-actions.ubuntu-runner-preview %}
##### **Example** ##### Example
```yaml ```yaml
runs-on: ubuntu-latest runs-on: ubuntu-latest
@@ -298,7 +298,7 @@ For more information, see "[Virtual environments for {% data variables.product.p
{% data reusables.github-actions.self-hosted-runner-labels-runs-on %} {% data reusables.github-actions.self-hosted-runner-labels-runs-on %}
##### **Example** ##### Example
```yaml ```yaml
runs-on: [self-hosted, linux] runs-on: [self-hosted, linux]
@@ -306,7 +306,7 @@ runs-on: [self-hosted, linux]
For more information, see "[About self-hosted runners](/github/automating-your-workflow-with-github-actions/about-self-hosted-runners)" and "[Using self-hosted runners in a workflow](/github/automating-your-workflow-with-github-actions/using-self-hosted-runners-in-a-workflow)." For more information, see "[About self-hosted runners](/github/automating-your-workflow-with-github-actions/about-self-hosted-runners)" and "[Using self-hosted runners in a workflow](/github/automating-your-workflow-with-github-actions/using-self-hosted-runners-in-a-workflow)."
### **`jobs.<job_id>.outputs`** ### `jobs.<job_id>.outputs`
A `map` of outputs for a job. Job outputs are available to all downstream jobs that depend on this job. For more information on defining job dependencies, see [`jobs.<job_id>.needs`](#jobsjob_idneeds). A `map` of outputs for a job. Job outputs are available to all downstream jobs that depend on this job. For more information on defining job dependencies, see [`jobs.<job_id>.needs`](#jobsjob_idneeds).
@@ -314,7 +314,7 @@ Job outputs are strings, and job outputs containing expressions are evaluated on
To use job outputs in a dependent job, you can use the `needs` context. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions#needs-context)." To use job outputs in a dependent job, you can use the `needs` context. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions#needs-context)."
#### **Example** #### Example
{% raw %} {% raw %}
```yaml ```yaml
@@ -338,13 +338,13 @@ jobs:
``` ```
{% endraw %} {% endraw %}
### **`jobs.<job_id>.env`** ### `jobs.<job_id>.env`
A `map` of environment variables that are available to all steps in the job. You can also set environment variables for the entire workflow or an individual step. For more information, see [`env`](#env) and [`jobs.<job_id>.steps.env`](#jobsjob_idstepsenv). A `map` of environment variables that are available to all steps in the job. You can also set environment variables for the entire workflow or an individual step. For more information, see [`env`](#env) and [`jobs.<job_id>.steps.env`](#jobsjob_idstepsenv).
{% data reusables.repositories.actions-env-var-note %} {% data reusables.repositories.actions-env-var-note %}
#### **Example** #### Example
```yaml ```yaml
jobs: jobs:
@@ -353,13 +353,13 @@ jobs:
FIRST_NAME: Mona FIRST_NAME: Mona
``` ```
### **`jobs.<job_id>.defaults`** ### `jobs.<job_id>.defaults`
A `map` of default settings that will apply to all steps in the job. You can also set default settings for the entire workflow. For more information, see [`defaults`](#defaults). A `map` of default settings that will apply to all steps in the job. You can also set default settings for the entire workflow. For more information, see [`defaults`](#defaults).
{% data reusables.github-actions.defaults-override %} {% data reusables.github-actions.defaults-override %}
### **`jobs.<job_id>.defaults.run`** ### `jobs.<job_id>.defaults.run`
Provide default `shell` and `working-directory` to all `run` steps in the job. Context and expression are not allowed in this section. Provide default `shell` and `working-directory` to all `run` steps in the job. Context and expression are not allowed in this section.
@@ -379,13 +379,13 @@ jobs:
working-directory: scripts working-directory: scripts
``` ```
### **`jobs.<job_id>.if`** ### `jobs.<job_id>.if`
You can use the `if` conditional to prevent a job from running unless a condition is met. You can use any supported context and expression to create a conditional. You can use the `if` conditional to prevent a job from running unless a condition is met. You can use any supported context and expression to create a conditional.
{% data reusables.github-actions.expression-syntax-if %} For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)." {% data reusables.github-actions.expression-syntax-if %} For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)."
### **`jobs.<job_id>.steps`** ### `jobs.<job_id>.steps`
A job contains a sequence of tasks called `steps`. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry. Not all steps run actions, but all actions run as a step. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to environment variables are not preserved between steps. {% data variables.product.prodname_dotcom %} provides built-in steps to set up and complete a job. A job contains a sequence of tasks called `steps`. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry. Not all steps run actions, but all actions run as a step. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to environment variables are not preserved between steps. {% data variables.product.prodname_dotcom %} provides built-in steps to set up and complete a job.
@@ -415,17 +415,17 @@ jobs:
``` ```
{% endraw %} {% endraw %}
#### **`jobs.<job_id>.steps.id`** ### `jobs.<job_id>.steps.id`
A unique identifier for the step. You can use the `id` to reference the step in contexts. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)." A unique identifier for the step. You can use the `id` to reference the step in contexts. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)."
#### **`jobs.<job_id>.steps.if`** ### `jobs.<job_id>.steps.if`
You can use the `if` conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional. You can use the `if` conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional.
{% data reusables.github-actions.expression-syntax-if %} For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)." {% data reusables.github-actions.expression-syntax-if %} For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)."
##### Example using contexts #### Example using contexts
This step only runs when the event type is a `pull_request` and the event action is `unassigned`. This step only runs when the event type is a `pull_request` and the event action is `unassigned`.
@@ -436,7 +436,7 @@ steps:
run: echo This event is a pull request that had an assignee removed. run: echo This event is a pull request that had an assignee removed.
``` ```
##### Example using status check functions #### Example using status check functions
The `my backup step` only runs when the previous step of a job fails. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions#job-status-check-functions)." The `my backup step` only runs when the previous step of a job fails. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions#job-status-check-functions)."
@@ -449,11 +449,11 @@ steps:
uses: actions/heroku@1.0.0 uses: actions/heroku@1.0.0
``` ```
#### **`jobs.<job_id>.steps.name`** ### `jobs.<job_id>.steps.name`
A name for your step to display on {% data variables.product.prodname_dotcom %}. A name for your step to display on {% data variables.product.prodname_dotcom %}.
#### **`jobs.<job_id>.steps.uses`** ### `jobs.<job_id>.steps.uses`
Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a [published Docker container image](https://hub.docker.com/). Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a [published Docker container image](https://hub.docker.com/).
@@ -466,7 +466,7 @@ Some actions require inputs that you must set using the [`with`](#jobsjob_idstep
Actions are either JavaScript files or Docker containers. If the action you're using is a Docker container you must run the job in a Linux environment. For more details, see [`runs-on`](#jobsjob_idruns-on). Actions are either JavaScript files or Docker containers. If the action you're using is a Docker container you must run the job in a Linux environment. For more details, see [`runs-on`](#jobsjob_idruns-on).
##### Example using versioned actions #### Example using versioned actions
```yaml ```yaml
steps: steps:
@@ -480,7 +480,7 @@ steps:
- uses: actions/setup-node@main - uses: actions/setup-node@main
``` ```
##### Example using a public action #### Example using a public action
`{owner}/{repo}@{ref}` `{owner}/{repo}@{ref}`
@@ -498,7 +498,7 @@ jobs:
uses: actions/aws@v2.0.1 uses: actions/aws@v2.0.1
``` ```
##### Example using a public action in a subdirectory #### Example using a public action in a subdirectory
`{owner}/{repo}/{path}@{ref}` `{owner}/{repo}/{path}@{ref}`
@@ -512,7 +512,7 @@ jobs:
uses: actions/aws/ec2@main uses: actions/aws/ec2@main
``` ```
##### Example using action in the same repository as the workflow #### Example using action in the same repository as the workflow
`./path/to/dir` `./path/to/dir`
@@ -528,7 +528,7 @@ jobs:
uses: ./.github/actions/my-action uses: ./.github/actions/my-action
``` ```
##### Example using a Docker Hub action #### Example using a Docker Hub action
`docker://{image}:{tag}` `docker://{image}:{tag}`
@@ -542,7 +542,7 @@ jobs:
uses: docker://alpine:3.8 uses: docker://alpine:3.8
``` ```
##### Example using a Docker public registry action #### Example using a Docker public registry action
`docker://{host}/{image}:{tag}` `docker://{host}/{image}:{tag}`
@@ -556,7 +556,7 @@ jobs:
uses: docker://gcr.io/cloud-builders/gradle uses: docker://gcr.io/cloud-builders/gradle
``` ```
#### **`jobs.<job_id>.steps.run`** ### `jobs.<job_id>.steps.run`
Runs command-line programs using the operating system's shell. If you do not provide a `name`, the step name will default to the text specified in the `run` command. Runs command-line programs using the operating system's shell. If you do not provide a `name`, the step name will default to the text specified in the `run` command.
@@ -588,7 +588,7 @@ Using the `working-directory` keyword, you can specify the working directory of
working-directory: ./temp working-directory: ./temp
``` ```
##### Using a specific shell #### Using a specific shell
You can override the default shell settings in the runner's operating system using the `shell` keyword. You can use built-in `shell` keywords, or you can define a custom set of shell options. You can override the default shell settings in the runner's operating system using the `shell` keyword. You can use built-in `shell` keywords, or you can define a custom set of shell options.
@@ -602,7 +602,7 @@ You can override the default shell settings in the runner's operating system usi
| Windows | `pwsh` | This is the default shell used on Windows. The PowerShell Core. {% data variables.product.prodname_dotcom %} appends the extension `.ps1` to your script name. | `pwsh -command ". '{0}'"`. | | Windows | `pwsh` | This is the default shell used on Windows. The PowerShell Core. {% data variables.product.prodname_dotcom %} appends the extension `.ps1` to your script name. | `pwsh -command ". '{0}'"`. |
| Windows | `powershell` | The PowerShell Desktop. {% data variables.product.prodname_dotcom %} appends the extension `.ps1` to your script name. | `powershell -command ". '{0}'"`. | | Windows | `powershell` | The PowerShell Desktop. {% data variables.product.prodname_dotcom %} appends the extension `.ps1` to your script name. | `powershell -command ". '{0}'"`. |
##### Example running a script using bash #### Example running a script using bash
```yaml ```yaml
steps: steps:
@@ -611,7 +611,7 @@ steps:
shell: bash shell: bash
``` ```
##### Example running a script using Windows `cmd` #### Example running a script using Windows `cmd`
```yaml ```yaml
steps: steps:
@@ -620,7 +620,7 @@ steps:
shell: cmd shell: cmd
``` ```
##### Example running a script using PowerShell Core #### Example running a script using PowerShell Core
```yaml ```yaml
steps: steps:
@@ -629,7 +629,7 @@ steps:
shell: pwsh shell: pwsh
``` ```
##### Example running a script using PowerShell Desktop #### Example running a script using PowerShell Desktop
```yaml ```yaml
steps: steps:
@@ -638,7 +638,7 @@ steps:
shell: powershell shell: powershell
``` ```
##### Example running a python script #### Example running a python script
```yaml ```yaml
steps: steps:
@@ -649,11 +649,11 @@ steps:
shell: python shell: python
``` ```
##### Custom shell #### Custom shell
You can set the `shell` value to a template string using `command […options] {0} [..more_options]`. {% data variables.product.prodname_dotcom %} interprets the first whitespace-delimited word of the string as the command, and inserts the file name for the temporary script at `{0}`. You can set the `shell` value to a template string using `command […options] {0} [..more_options]`. {% data variables.product.prodname_dotcom %} interprets the first whitespace-delimited word of the string as the command, and inserts the file name for the temporary script at `{0}`.
##### Exit codes and error action preference #### Exit codes and error action preference
For built-in shell keywords, we provide the following defaults that are executed by {% data variables.product.prodname_dotcom %}-hosted runners. You should use these guidelines when running shell scripts. For built-in shell keywords, we provide the following defaults that are executed by {% data variables.product.prodname_dotcom %}-hosted runners. You should use these guidelines when running shell scripts.
@@ -671,11 +671,11 @@ For built-in shell keywords, we provide the following defaults that are executed
- There doesn't seem to be a way to fully opt into fail-fast behavior other than writing your script to check each error code and respond accordingly. Because we can't actually provide that behavior by default, you need to write this behavior into your script. - There doesn't seem to be a way to fully opt into fail-fast behavior other than writing your script to check each error code and respond accordingly. Because we can't actually provide that behavior by default, you need to write this behavior into your script.
- `cmd.exe` will exit with the error level of the last program it executed, and it will return the error code to the runner. This behavior is internally consistent with the previous `sh` and `pwsh` default behavior and is the `cmd.exe` default, so this behavior remains intact. - `cmd.exe` will exit with the error level of the last program it executed, and it will return the error code to the runner. This behavior is internally consistent with the previous `sh` and `pwsh` default behavior and is the `cmd.exe` default, so this behavior remains intact.
#### **`jobs.<job_id>.steps.with`** ### `jobs.<job_id>.steps.with`
A `map` of the input parameters defined by the action. Each input parameter is a key/value pair. Input parameters are set as environment variables. The variable is prefixed with `INPUT_` and converted to upper case. A `map` of the input parameters defined by the action. Each input parameter is a key/value pair. Input parameters are set as environment variables. The variable is prefixed with `INPUT_` and converted to upper case.
##### Example #### Example
Defines the three input parameters (`first_name`, `middle_name`, and `last_name`) defined by the `hello_world` action. These input variables will be accessible to the `hello-world` action as `INPUT_FIRST_NAME`, `INPUT_MIDDLE_NAME`, and `INPUT_LAST_NAME` environment variables. Defines the three input parameters (`first_name`, `middle_name`, and `last_name`) defined by the `hello_world` action. These input variables will be accessible to the `hello-world` action as `INPUT_FIRST_NAME`, `INPUT_MIDDLE_NAME`, and `INPUT_LAST_NAME` environment variables.
@@ -691,11 +691,11 @@ jobs:
last_name: Octocat last_name: Octocat
``` ```
#### **`jobs.<job_id>.steps.with.args`** ### `jobs.<job_id>.steps.with.args`
A `string` that defines the inputs for a Docker container. {% data variables.product.prodname_dotcom %} passes the `args` to the container's `ENTRYPOINT` when the container starts up. An `array of strings` is not supported by this parameter. A `string` that defines the inputs for a Docker container. {% data variables.product.prodname_dotcom %} passes the `args` to the container's `ENTRYPOINT` when the container starts up. An `array of strings` is not supported by this parameter.
##### Example #### Example
{% raw %} {% raw %}
```yaml ```yaml
@@ -714,11 +714,11 @@ The `args` are used in place of the `CMD` instruction in a `Dockerfile`. If you
1. Use defaults that allow using the action without specifying any `args`. 1. Use defaults that allow using the action without specifying any `args`.
1. If the action exposes a `--help` flag, or something similar, use that as the default to make your action self-documenting. 1. If the action exposes a `--help` flag, or something similar, use that as the default to make your action self-documenting.
#### **`jobs.<job_id>.steps.with.entrypoint`** ### `jobs.<job_id>.steps.with.entrypoint`
Overrides the Docker `ENTRYPOINT` in the `Dockerfile`, or sets it if one wasn't already specified. Unlike the Docker `ENTRYPOINT` instruction which has a shell and exec form, `entrypoint` keyword accepts only a single string defining the executable to be run. Overrides the Docker `ENTRYPOINT` in the `Dockerfile`, or sets it if one wasn't already specified. Unlike the Docker `ENTRYPOINT` instruction which has a shell and exec form, `entrypoint` keyword accepts only a single string defining the executable to be run.
##### Example #### Example
```yaml ```yaml
steps: steps:
@@ -730,7 +730,7 @@ steps:
The `entrypoint` keyword is meant to be used with Docker container actions, but you can also use it with JavaScript actions that don't define any inputs. The `entrypoint` keyword is meant to be used with Docker container actions, but you can also use it with JavaScript actions that don't define any inputs.
#### **`jobs.<job_id>.steps.env`** ### `jobs.<job_id>.steps.env`
Sets environment variables for steps to use in the runner environment. You can also set environment variables for the entire workflow or a job. For more information, see [`env`](#env) and [`jobs.<job_id>.env`](#jobsjob_idenv). Sets environment variables for steps to use in the runner environment. You can also set environment variables for the entire workflow or a job. For more information, see [`env`](#env) and [`jobs.<job_id>.env`](#jobsjob_idenv).
@@ -738,7 +738,7 @@ Sets environment variables for steps to use in the runner environment. You can a
Public actions may specify expected environment variables in the README file. If you are setting a secret in an environment variable, you must set secrets using the `secrets` context. For more information, see "[Using environment variables](/actions/automating-your-workflow-with-github-actions/using-environment-variables)" and "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)." Public actions may specify expected environment variables in the README file. If you are setting a secret in an environment variable, you must set secrets using the `secrets` context. For more information, see "[Using environment variables](/actions/automating-your-workflow-with-github-actions/using-environment-variables)" and "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)."
##### Example #### Example
{% raw %} {% raw %}
```yaml ```yaml
@@ -751,23 +751,23 @@ steps:
``` ```
{% endraw %} {% endraw %}
#### **`jobs.<job_id>.steps.continue-on-error`** ### `jobs.<job_id>.steps.continue-on-error`
Prevents a job from failing when a step fails. Set to `true` to allow a job to pass when this step fails. Prevents a job from failing when a step fails. Set to `true` to allow a job to pass when this step fails.
#### **`jobs.<job_id>.steps.timeout-minutes`** ### `jobs.<job_id>.steps.timeout-minutes`
The maximum number of minutes to run the step before killing the process. The maximum number of minutes to run the step before killing the process.
### **`jobs.<job_id>.timeout-minutes`** ### `jobs.<job_id>.timeout-minutes`
The maximum number of minutes to let a job run before {% data variables.product.prodname_dotcom %} automatically cancels it. Default: 360 The maximum number of minutes to let a job run before {% data variables.product.prodname_dotcom %} automatically cancels it. Default: 360
### **`jobs.<job_id>.strategy`** ### `jobs.<job_id>.strategy`
A strategy creates a build matrix for your jobs. You can define different variations of an environment to run each job in. A strategy creates a build matrix for your jobs. You can define different variations of an environment to run each job in.
#### **`jobs.<job_id>.strategy.matrix`** ### `jobs.<job_id>.strategy.matrix`
You can define a matrix of different job configurations. A matrix allows you to create multiple jobs by performing variable substitution in a single job definition. For example, you can use a matrix to create jobs for more than one supported version of a programming language, operating system, or tool. A matrix reuses the job's configuration and creates a job for each matrix you configure. You can define a matrix of different job configurations. A matrix allows you to create multiple jobs by performing variable substitution in a single job definition. For example, you can use a matrix to create jobs for more than one supported version of a programming language, operating system, or tool. A matrix reuses the job's configuration and creates a job for each matrix you configure.
@@ -777,7 +777,7 @@ Each option you define in the `matrix` has a key and value. The keys you define
The order that you define a `matrix` matters. The first option you define will be the first job that runs in your workflow. The order that you define a `matrix` matters. The first option you define will be the first job that runs in your workflow.
##### Example running with more than one version of Node.js #### Example running with more than one version of Node.js
You can specify a matrix by supplying an array for the configuration options. For example, if the runner supports Node.js versions 6, 8, and 10, you could specify an array of those versions in the `matrix`. You can specify a matrix by supplying an array for the configuration options. For example, if the runner supports Node.js versions 6, 8, and 10, you could specify an array of those versions in the `matrix`.
@@ -799,7 +799,7 @@ steps:
The `setup-node` action is the recommended way to configure a Node.js version when using {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see the [`setup-node`](https://github.com/actions/setup-node) action. The `setup-node` action is the recommended way to configure a Node.js version when using {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see the [`setup-node`](https://github.com/actions/setup-node) action.
##### Example running with more than one operating system #### Example running with more than one operating system
You can create a matrix to run workflows on more than one runner operating system. You can also specify more than one matrix configuration. This example creates a matrix of 6 jobs: You can create a matrix to run workflows on more than one runner operating system. You can also specify more than one matrix configuration. This example creates a matrix of 6 jobs:
@@ -824,7 +824,7 @@ steps:
To find supported configuration options for {% data variables.product.prodname_dotcom %}-hosted runners, see "[Virtual environments for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/automating-your-workflow-with-github-actions/virtual-environments-for-github-hosted-runners)." To find supported configuration options for {% data variables.product.prodname_dotcom %}-hosted runners, see "[Virtual environments for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/automating-your-workflow-with-github-actions/virtual-environments-for-github-hosted-runners)."
##### Example including additional values into combinations #### Example including additional values into combinations
You can add additional configuration options to a build matrix job that already exists. For example, if you want to use a specific version of `npm` when the job that uses `windows-latest` and version 4 of `node` runs, you can use `include` to specify that additional option. You can add additional configuration options to a build matrix job that already exists. For example, if you want to use a specific version of `npm` when the job that uses `windows-latest` and version 4 of `node` runs, you can use `include` to specify that additional option.
@@ -844,7 +844,7 @@ strategy:
``` ```
{% endraw %} {% endraw %}
##### Example including new combinations #### Example including new combinations
You can use `include` to add new jobs to a build matrix. Any unmatched include configurations are added to the matrix. For example, if you want to use `node` version 12 to build on multiple operating systems, but wanted one extra experimental job using node version 13 on Ubuntu, you can use `include` to specify that additional job. You can use `include` to add new jobs to a build matrix. Any unmatched include configurations are added to the matrix. For example, if you want to use `node` version 12 to build on multiple operating systems, but wanted one extra experimental job using node version 13 on Ubuntu, you can use `include` to specify that additional job.
@@ -862,7 +862,7 @@ strategy:
``` ```
{% endraw %} {% endraw %}
##### Example excluding configurations from a matrix #### Example excluding configurations from a matrix
You can remove a specific configurations defined in the build matrix using the `exclude` option. Using `exclude` removes a job defined by the build matrix. The number of jobs is the cross product of the number of operating systems (`os`) included in the arrays you provide, minus any subtractions (`exclude`). You can remove a specific configurations defined in the build matrix using the `exclude` option. Using `exclude` removes a job defined by the build matrix. The number of jobs is the cross product of the number of operating systems (`os`) included in the arrays you provide, minus any subtractions (`exclude`).
@@ -888,40 +888,15 @@ strategy:
##### Using environment variables in a matrix ##### Using environment variables in a matrix
You can add custom environment variables for each test combination by using `include` with `env`. You can then refer to the custom environment variables in a later step. You can add custom environment variables for each test combination by using the `include` key. You can then refer to the custom environment variables in a later step.
In this example, the matrix entries for `node-version` are each configured to use different values for the `site` and `datacenter` environment variables. The `Echo site details` step then uses {% raw %}`env: ${{ matrix.env }}`{% endraw %} to refer to the custom variables: {% data reusables.github-actions.matrix-variable-example %}
{% raw %} ### `jobs.<job_id>.strategy.fail-fast`
```yaml
name: Node.js CI
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
include:
- node-version: 10.x
site: "prod"
datacenter: "site-a"
- node-version: 12.x
site: "dev"
datacenter: "site-b"
steps:
- name: Echo site details
env:
SITE: ${{ matrix.site }}
DATACENTER: ${{ matrix.datacenter }}
run: echo $SITE $DATACENTER
```
{% endraw %}
### **`jobs.<job_id>.strategy.fail-fast`**
When set to `true`, {% data variables.product.prodname_dotcom %} cancels all in-progress jobs if any `matrix` job fails. Default: `true` When set to `true`, {% data variables.product.prodname_dotcom %} cancels all in-progress jobs if any `matrix` job fails. Default: `true`
### **`jobs.<job_id>.strategy.max-parallel`** ### `jobs.<job_id>.strategy.max-parallel`
The maximum number of jobs that can run simultaneously when using a `matrix` job strategy. By default, {% data variables.product.prodname_dotcom %} will maximize the number of jobs run in parallel depending on the available runners on {% data variables.product.prodname_dotcom %}-hosted virtual machines. The maximum number of jobs that can run simultaneously when using a `matrix` job strategy. By default, {% data variables.product.prodname_dotcom %} will maximize the number of jobs run in parallel depending on the available runners on {% data variables.product.prodname_dotcom %}-hosted virtual machines.
@@ -930,7 +905,7 @@ strategy:
max-parallel: 2 max-parallel: 2
``` ```
### **`jobs.<job_id>.continue-on-error`** ### `jobs.<job_id>.continue-on-error`
Prevents a workflow run from failing when a job fails. Set to `true` to allow a workflow run to pass when this job fails. Prevents a workflow run from failing when a job fails. Set to `true` to allow a workflow run to pass when this job fails.
@@ -955,7 +930,7 @@ strategy:
``` ```
{% endraw %} {% endraw %}
### **`jobs.<job_id>.container`** ### `jobs.<job_id>.container`
A container to run any steps in a job that don't already specify a container. If you have steps that use both script and container actions, the container actions will run as sibling containers on the same network with the same volume mounts. A container to run any steps in a job that don't already specify a container. If you have steps that use both script and container actions, the container actions will run as sibling containers on the same network with the same volume mounts.
@@ -985,16 +960,17 @@ jobs:
container: node:10.16-jessie container: node:10.16-jessie
``` ```
#### **`jobs.<job_id>.container.image`** ### `jobs.<job_id>.container.image`
The Docker image to use as the container to run the action. The value can be the Docker Hub image name or a {% if enterpriseServerVersions contains currentVersion and currentVersion ver_lt "enterprise-server@2.23" %}public{% endif %} registry name. The Docker image to use as the container to run the action. The value can be the Docker Hub image name or a {% if enterpriseServerVersions contains currentVersion and currentVersion ver_lt "enterprise-server@2.23" %}public{% endif %} registry name.
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %}
#### **`jobs.<job_id>.container.credentials`**
### `jobs.<job_id>.container.credentials`
{% data reusables.actions.registry-credentials %} {% data reusables.actions.registry-credentials %}
##### Example #### Example
{% raw %} {% raw %}
```yaml ```yaml
@@ -1007,15 +983,15 @@ container:
{% endraw %} {% endraw %}
{% endif %} {% endif %}
#### **`jobs.<job_id>.container.env`** ### `jobs.<job_id>.container.env`
Sets a `map` of environment variables in the container. Sets a `map` of environment variables in the container.
#### **`jobs.<job_id>.container.ports`** ### `jobs.<job_id>.container.ports`
Sets an `array` of ports to expose on the container. Sets an `array` of ports to expose on the container.
#### **`jobs.<job_id>.container.volumes`** ### `jobs.<job_id>.container.volumes`
Sets an `array` of volumes for the container to use. You can use volumes to share data between services or other steps in a job. You can specify named Docker volumes, anonymous Docker volumes, or bind mounts on the host. Sets an `array` of volumes for the container to use. You can use volumes to share data between services or other steps in a job. You can specify named Docker volumes, anonymous Docker volumes, or bind mounts on the host.
@@ -1025,7 +1001,7 @@ To specify a volume, you specify the source and destination path:
The `<source>` is a volume name or an absolute path on the host machine, and `<destinationPath>` is an absolute path in the container. The `<source>` is a volume name or an absolute path on the host machine, and `<destinationPath>` is an absolute path in the container.
##### Example #### Example
```yaml ```yaml
volumes: volumes:
@@ -1034,11 +1010,11 @@ volumes:
- /source/directory:/destination/directory - /source/directory:/destination/directory
``` ```
#### **`jobs.<job_id>.container.options`** ### `jobs.<job_id>.container.options`
Additional Docker container resource options. For a list of options, see "[`docker create` options](https://docs.docker.com/engine/reference/commandline/create/#options)." Additional Docker container resource options. For a list of options, see "[`docker create` options](https://docs.docker.com/engine/reference/commandline/create/#options)."
### **`jobs.<job_id>.services`** ### `jobs.<job_id>.services`
{% data reusables.github-actions.docker-container-os-support %} {% data reusables.github-actions.docker-container-os-support %}
@@ -1068,16 +1044,17 @@ services:
- 6379/tcp - 6379/tcp
``` ```
#### **`jobs.<job_id>.services.<service_id>.image`** ### `jobs.<job_id>.services.<service_id>.image`
The Docker image to use as the service container to run the action. The value can be the Docker Hub image name or a {% if enterpriseServerVersions contains currentVersion and currentVersion ver_lt "enterprise-server@2.23" %}public{% endif %} registry name. The Docker image to use as the service container to run the action. The value can be the Docker Hub image name or a {% if enterpriseServerVersions contains currentVersion and currentVersion ver_lt "enterprise-server@2.23" %}public{% endif %} registry name.
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %}
#### **`jobs.<job_id>.services.<service_id>.credentials`**
### `jobs.<job_id>.services.<service_id>.credentials`
{% data reusables.actions.registry-credentials %} {% data reusables.actions.registry-credentials %}
##### Example #### Example
{% raw %} {% raw %}
```yaml ```yaml
@@ -1096,15 +1073,15 @@ services:
{% endraw %} {% endraw %}
{% endif %} {% endif %}
#### **`jobs.<job_id>.services.<service_id>.env`** ### `jobs.<job_id>.services.<service_id>.env`
Sets a `map` of environment variables in the service container. Sets a `map` of environment variables in the service container.
#### **`jobs.<job_id>.services.<service_id>.ports`** ### `jobs.<job_id>.services.<service_id>.ports`
Sets an `array` of ports to expose on the service container. Sets an `array` of ports to expose on the service container.
#### **`jobs.<job_id>.services.<service_id>.volumes`** ### `jobs.<job_id>.services.<service_id>.volumes`
Sets an `array` of volumes for the service container to use. You can use volumes to share data between services or other steps in a job. You can specify named Docker volumes, anonymous Docker volumes, or bind mounts on the host. Sets an `array` of volumes for the service container to use. You can use volumes to share data between services or other steps in a job. You can specify named Docker volumes, anonymous Docker volumes, or bind mounts on the host.
@@ -1114,7 +1091,7 @@ To specify a volume, you specify the source and destination path:
The `<source>` is a volume name or an absolute path on the host machine, and `<destinationPath>` is an absolute path in the container. The `<source>` is a volume name or an absolute path on the host machine, and `<destinationPath>` is an absolute path in the container.
##### Example #### Example
```yaml ```yaml
volumes: volumes:
@@ -1123,7 +1100,7 @@ volumes:
- /source/directory:/destination/directory - /source/directory:/destination/directory
``` ```
#### **`jobs.<job_id>.services.<service_id>.options`** ### `jobs.<job_id>.services.<service_id>.options`
Additional Docker container resource options. For a list of options, see "[`docker create` options](https://docs.docker.com/engine/reference/commandline/create/#options)." Additional Docker container resource options. For a list of options, see "[`docker create` options](https://docs.docker.com/engine/reference/commandline/create/#options)."

2
content/admin/authentication/changing-authentication-methods.md
View File

@@ -9,7 +9,7 @@ versions:
--- ---
User accounts on {% data variables.product.product_location %} are preserved when you change the authentication method and users will continue to log into the same account as long as their username doesn't change. User accounts on {% data variables.product.product_location %} are preserved when you change the authentication method and users will continue to log into the same account as long as their username doesn't change.
If the new method of authentication changes usernames, new accounts will be created. As an administrator, you can rename users through the site admin settings or by using [the User Administration API](/enterprise/{{currentVersion}}/v3/enterprise-admin/users/#rename-an-existing-user). If the new method of authentication changes usernames, new accounts will be created. As an administrator, you can rename users through the site admin settings or by using [the User Administration API](/rest/reference/enterprise-admin#update-the-username-for-a-user).
Other issues you should take into consideration include: Other issues you should take into consideration include:

2
content/admin/configuration/command-line-utilities.md
View File

@@ -157,7 +157,7 @@ $ ghe-es-index-status -do | column -ts,
#### ghe-legacy-github-services-report #### ghe-legacy-github-services-report
This utility lists repositories on your appliance that use {% data variables.product.prodname_dotcom %} Services, an integration method that will be discontinued on October 1, 2018. Users on your appliance may have set up {% data variables.product.prodname_dotcom %} Services to create notifications for pushes to certain repositories. For more information, see "[Announcing the deprecation of {% data variables.product.prodname_dotcom %} Services](https://developer.github.com/changes/2018-04-25-github-services-deprecation/)" on {% data variables.product.prodname_blog %} or "[Replacing {% data variables.product.prodname_dotcom %} Services](/v3/guides/replacing-github-services/)." For more information about this command or for additional options, use the `-h` flag. This utility lists repositories on your appliance that use {% data variables.product.prodname_dotcom %} Services, an integration method that will be discontinued on October 1, 2018. Users on your appliance may have set up {% data variables.product.prodname_dotcom %} Services to create notifications for pushes to certain repositories. For more information, see "[Announcing the deprecation of {% data variables.product.prodname_dotcom %} Services](https://developer.github.com/changes/2018-04-25-github-services-deprecation/)" on {% data variables.product.prodname_blog %} or "[Replacing {% data variables.product.prodname_dotcom %} Services](/developers/overview/replacing-github-services)." For more information about this command or for additional options, use the `-h` flag.
```shell ```shell
ghe-legacy-github-services-report ghe-legacy-github-services-report

2
content/admin/configuration/connecting-github-enterprise-server-to-github-enterprise-cloud.md
View File

@@ -37,7 +37,7 @@ Enabling {% data variables.product.prodname_github_connect %} also creates a {%
Enabling {% data variables.product.prodname_github_connect %} will not allow {% data variables.product.prodname_dotcom_the_website %} users to make changes to {% data variables.product.prodname_ghe_server %}. Enabling {% data variables.product.prodname_github_connect %} will not allow {% data variables.product.prodname_dotcom_the_website %} users to make changes to {% data variables.product.prodname_ghe_server %}.
For more information about managing enterprise accounts using the GraphQL API, see "[Enterprise accounts](/v4/guides/managing-enterprise-accounts)." For more information about managing enterprise accounts using the GraphQL API, see "[Enterprise accounts](/graphql/guides/managing-enterprise-accounts)."
### Enabling {% data variables.product.prodname_github_connect %} ### Enabling {% data variables.product.prodname_github_connect %}
1. Sign in to {% data variables.product.product_location_enterprise %} and {% data variables.product.prodname_dotcom_the_website %}. 1. Sign in to {% data variables.product.product_location_enterprise %} and {% data variables.product.prodname_dotcom_the_website %}.

6
content/admin/configuration/index.md
View File

@@ -31,9 +31,7 @@ versions:
{% link_in_list /enabling-private-mode %} {% link_in_list /enabling-private-mode %}
{% link_in_list /configuring-email-for-notifications %} {% link_in_list /configuring-email-for-notifications %}
{% link_in_list /configuring-rate-limits %} {% link_in_list /configuring-rate-limits %}
<!-- if currentVersion ver_gt "enterprise-server@2.15" -->
{% link_in_list /configuring-applications %} {% link_in_list /configuring-applications %}
<!-- endif -->
{% link_in_list /troubleshooting-ssl-errors %} {% link_in_list /troubleshooting-ssl-errors %}
{% link_in_list /configuring-time-synchronization %} {% link_in_list /configuring-time-synchronization %}
{% link_in_list /command-line-utilities %} {% link_in_list /command-line-utilities %}
@@ -54,11 +52,7 @@ versions:
{% link_in_list /connecting-github-enterprise-server-to-github-enterprise-cloud %} {% link_in_list /connecting-github-enterprise-server-to-github-enterprise-cloud %}
{% link_in_list /enabling-unified-search-between-github-enterprise-server-and-githubcom %} {% link_in_list /enabling-unified-search-between-github-enterprise-server-and-githubcom %}
{% link_in_list /enabling-unified-contributions-between-github-enterprise-server-and-githubcom %} {% link_in_list /enabling-unified-contributions-between-github-enterprise-server-and-githubcom %}
<!-- if currentVersion ver_gt "enterprise-server@2.16" -->
{% link_in_list /enabling-alerts-for-vulnerable-dependencies-on-github-enterprise-server %} {% link_in_list /enabling-alerts-for-vulnerable-dependencies-on-github-enterprise-server %}
{% link_in_list /enabling-automatic-user-license-sync-between-github-enterprise-server-and-github-enterprise-cloud %} {% link_in_list /enabling-automatic-user-license-sync-between-github-enterprise-server-and-github-enterprise-cloud %}
<!-- endif -->
<!-- if currentVersion ver_gt "enterprise-server@2.21" -->
{% topic_link_in_list /configuring-advanced-security-features %} {% topic_link_in_list /configuring-advanced-security-features %}
{% link_in_list /configuring-code-scanning-for-your-appliance %} {% link_in_list /configuring-code-scanning-for-your-appliance %}
<!-- endif -->

104
content/admin/enterprise-management/configuring-high-availability-replication-for-a-cluster.md
View File

@@ -57,32 +57,36 @@ Before you define a secondary datacenter for your passive nodes, ensure that you
mysql-master = <em>HOSTNAME</em> mysql-master = <em>HOSTNAME</em>
redis-master = <em>HOSTNAME</em> redis-master = <em>HOSTNAME</em>
<strong>primary-datacenter = default</strong> <strong>primary-datacenter = default</strong>
``` ```
- Optionally, change the name of the primary datacenter to something more descriptive or accurate by editing the value of `primary-datacenter`. - Optionally, change the name of the primary datacenter to something more descriptive or accurate by editing the value of `primary-datacenter`.
4. {% data reusables.enterprise_clustering.configuration-file-heading %} Under each node's heading, add a new key-value pair to assign the node to a datacenter. Use the same value as `primary-datacenter` from step 3 above. For example, if you want to use the default name (`default`), add the following key-value pair to the section for each node. 4. {% data reusables.enterprise_clustering.configuration-file-heading %} Under each node's heading, add a new key-value pair to assign the node to a datacenter. Use the same value as `primary-datacenter` from step 3 above. For example, if you want to use the default name (`default`), add the following key-value pair to the section for each node.
datacenter = default ```
datacenter = default
```
When you're done, the section for each node in the cluster configuration file should look like the following example. {% data reusables.enterprise_clustering.key-value-pair-order-irrelevant %} When you're done, the section for each node in the cluster configuration file should look like the following example. {% data reusables.enterprise_clustering.key-value-pair-order-irrelevant %}
```shell ```shell
[cluster "<em>HOSTNAME</em>"] [cluster "<em>HOSTNAME</em>"]
<strong>datacenter = default</strong> <strong>datacenter = default</strong>
hostname = <em>HOSTNAME</em> hostname = <em>HOSTNAME</em>
ipv4 = <em>IP ADDRESS</em> ipv4 = <em>IP ADDRESS</em>
...
... ...
... ```
```
{% note %} {% note %}
**Note**: If you changed the name of the primary datacenter in step 3, find the `consul-datacenter` key-value pair in the section for each node and change the value to the renamed primary datacenter. For example, if you named the primary datacenter `primary`, use the following key-value pair for each node. **Note**: If you changed the name of the primary datacenter in step 3, find the `consul-datacenter` key-value pair in the section for each node and change the value to the renamed primary datacenter. For example, if you named the primary datacenter `primary`, use the following key-value pair for each node.
consul-datacenter = primary ```
consul-datacenter = primary
```
{% endnote %} {% endnote %}
{% data reusables.enterprise_clustering.apply-configuration %} {% data reusables.enterprise_clustering.apply-configuration %}
@@ -103,31 +107,37 @@ For an example configuration, see "[Example configuration](#example-configuratio
1. For each node in your cluster, provision a matching virtual machine with identical specifications, running the same version of {% data variables.product.prodname_ghe_server %}. Note the IPv4 address and hostname for each new cluster node. For more information, see "[Prerequisites](#prerequisites)." 1. For each node in your cluster, provision a matching virtual machine with identical specifications, running the same version of {% data variables.product.prodname_ghe_server %}. Note the IPv4 address and hostname for each new cluster node. For more information, see "[Prerequisites](#prerequisites)."
{% note %} {% note %}
**Note**: If you're reconfiguring high availability after a failover, you can use the old nodes from the primary datacenter instead. **Note**: If you're reconfiguring high availability after a failover, you can use the old nodes from the primary datacenter instead.
{% endnote %} {% endnote %}
{% data reusables.enterprise_clustering.ssh-to-a-node %} {% data reusables.enterprise_clustering.ssh-to-a-node %}
3. Back up your existing cluster configuration. 3. Back up your existing cluster configuration.
cp /data/user/common/cluster.conf ~/$(date +%Y-%m-%d)-cluster.conf.backup ```
cp /data/user/common/cluster.conf ~/$(date +%Y-%m-%d)-cluster.conf.backup
```
4. Create a copy of your existing cluster configuration file in a temporary location, like _/home/admin/cluster-passive.conf_. Delete unique key-value pairs for IP addresses (`ipv*`), UUIDs (`uuid`), and public keys for WireGuard (`wireguard-pubkey`). 4. Create a copy of your existing cluster configuration file in a temporary location, like _/home/admin/cluster-passive.conf_. Delete unique key-value pairs for IP addresses (`ipv*`), UUIDs (`uuid`), and public keys for WireGuard (`wireguard-pubkey`).
grep -Ev "(?:|ipv|uuid|vpn|wireguard\-pubkey)" /data/user/common/cluster.conf > ~/cluster-passive.conf ```
grep -Ev "(?:|ipv|uuid|vpn|wireguard\-pubkey)" /data/user/common/cluster.conf > ~/cluster-passive.conf
```
5. Remove the `[cluster]` section from the temporary cluster configuration file that you copied in the previous step. 5. Remove the `[cluster]` section from the temporary cluster configuration file that you copied in the previous step.
git config -f ~/cluster-passive.conf --remove-section cluster ```
git config -f ~/cluster-passive.conf --remove-section cluster
```
6. Decide on a name for the secondary datacenter where you provisioned your passive nodes, then update the temporary cluster configuration file with the new datacenter name. Replace `SECONDARY` with the name you choose. 6. Decide on a name for the secondary datacenter where you provisioned your passive nodes, then update the temporary cluster configuration file with the new datacenter name. Replace `SECONDARY` with the name you choose.
```shell ```shell
sed -i 's/datacenter = default/datacenter = <em>SECONDARY</em>/g' ~/cluster-passive.conf sed -i 's/datacenter = default/datacenter = <em>SECONDARY</em>/g' ~/cluster-passive.conf
``` ```
7. Decide on a pattern for the passive nodes' hostnames. 7. Decide on a pattern for the passive nodes' hostnames.
@@ -140,7 +150,7 @@ For an example configuration, see "[Example configuration](#example-configuratio
8. Open the temporary cluster configuration file from step 3 in a text editor. For example, you can use Vim. 8. Open the temporary cluster configuration file from step 3 in a text editor. For example, you can use Vim.
```shell ```shell
sudo vim ~/cluster-passive.conf sudo vim ~/cluster-passive.conf
``` ```
9. In each section within the temporary cluster configuration file, update the node's configuration. {% data reusables.enterprise_clustering.configuration-file-heading %} 9. In each section within the temporary cluster configuration file, update the node's configuration. {% data reusables.enterprise_clustering.configuration-file-heading %}
@@ -150,37 +160,37 @@ For an example configuration, see "[Example configuration](#example-configuratio
- Add a new key-value pair, `replica = enabled`. - Add a new key-value pair, `replica = enabled`.
```shell ```shell
[cluster "<em>NEW PASSIVE NODE HOSTNAME</em>"] [cluster "<em>NEW PASSIVE NODE HOSTNAME</em>"]
...
hostname = <em>NEW PASSIVE NODE HOSTNAME</em>
ipv4 = <em>NEW PASSIVE NODE IPV4 ADDRESS</em>
<strong>replica = enabled</strong>
...
... ...
hostname = <em>NEW PASSIVE NODE HOSTNAME</em>
ipv4 = <em>NEW PASSIVE NODE IPV4 ADDRESS</em>
<strong>replica = enabled</strong>
...
...
``` ```
10. Append the contents of the temporary cluster configuration file that you created in step 4 to the active configuration file. 10. Append the contents of the temporary cluster configuration file that you created in step 4 to the active configuration file.
```shell ```shell
cat ~/cluster-passive.conf >> /data/user/common/cluster.conf cat ~/cluster-passive.conf >> /data/user/common/cluster.conf
``` ```
11. Designate the primary MySQL and Redis nodes in the secondary datacenter. Replace `REPLICA MYSQL PRIMARY HOSTNAME` and `REPLICA REDIS PRIMARY HOSTNAME` with the hostnames of the passives node that you provisioned to match your existing MySQL and Redis primaries. 11. Designate the primary MySQL and Redis nodes in the secondary datacenter. Replace `REPLICA MYSQL PRIMARY HOSTNAME` and `REPLICA REDIS PRIMARY HOSTNAME` with the hostnames of the passives node that you provisioned to match your existing MySQL and Redis primaries.
```shell ```shell
git config -f /data/user/common/cluster.conf cluster.mysql-master-replica <em>REPLICA MYSQL PRIMARY HOSTNAME</em> git config -f /data/user/common/cluster.conf cluster.mysql-master-replica <em>REPLICA MYSQL PRIMARY HOSTNAME</em>
git config -f /data/user/common/cluster.conf cluster.redis-master-replica <em>REPLICA REDIS PRIMARY HOSTNAME</em> git config -f /data/user/common/cluster.conf cluster.redis-master-replica <em>REPLICA REDIS PRIMARY HOSTNAME</em>
``` ```
12. Enable MySQL to fail over automatically when you fail over to the passive replica nodes. 12. Enable MySQL to fail over automatically when you fail over to the passive replica nodes.
```shell ```shell
git config -f /data/user/common/cluster.conf cluster.mysql-auto-failover true git config -f /data/user/common/cluster.conf cluster.mysql-auto-failover true
``` ```
{% warning %} {% warning %}
**Warning**: Review your cluster configuration file before proceeding. **Warning**: Review your cluster configuration file before proceeding.
- In the top-level `[cluster]` section, ensure that the values for `mysql-master-replica` and `redis-master-replica` are the correct hostnames for the passive nodes in the secondary datacenter that will serve as the MySQL and Redis primaries after a failover. - In the top-level `[cluster]` section, ensure that the values for `mysql-master-replica` and `redis-master-replica` are the correct hostnames for the passive nodes in the secondary datacenter that will serve as the MySQL and Redis primaries after a failover.
- In each section for an active node named <code>[cluster "<em>ACTIVE NODE HOSTNAME</em>"]</code>, double-check the following key-value pairs. - In each section for an active node named <code>[cluster "<em>ACTIVE NODE HOSTNAME</em>"]</code>, double-check the following key-value pairs.
@@ -194,9 +204,9 @@ For an example configuration, see "[Example configuration](#example-configuratio
- `replica` should be configured as `enabled`. - `replica` should be configured as `enabled`.
- Take the opportunity to remove sections for offline nodes that are no longer in use. - Take the opportunity to remove sections for offline nodes that are no longer in use.
To review an example configuration, see "[Example configuration](#example-configuration)." To review an example configuration, see "[Example configuration](#example-configuration)."
{% endwarning %} {% endwarning %}
13. Initialize the new cluster configuration. {% data reusables.enterprise.use-a-multiplexer %} 13. Initialize the new cluster configuration. {% data reusables.enterprise.use-a-multiplexer %}
@@ -207,7 +217,7 @@ For an example configuration, see "[Example configuration](#example-configuratio
14. After the initialization finishes, {% data variables.product.prodname_ghe_server %} displays the following message. 14. After the initialization finishes, {% data variables.product.prodname_ghe_server %} displays the following message.
```shell ```shell
Finished cluster initialization Finished cluster initialization
``` ```
{% data reusables.enterprise_clustering.apply-configuration %} {% data reusables.enterprise_clustering.apply-configuration %}
@@ -294,19 +304,27 @@ You can monitor the progress on any node in the cluster, using command-line tool
- Monitor replication of databases: - Monitor replication of databases:
/usr/local/share/enterprise/ghe-cluster-status-mysql ```
/usr/local/share/enterprise/ghe-cluster-status-mysql
```
- Monitor replication of repository and Gist data: - Monitor replication of repository and Gist data:
ghe-spokes status ```
ghe-spokes status
```
- Monitor replication of attachment and LFS data: - Monitor replication of attachment and LFS data:
ghe-storage replication-status ```
ghe-storage replication-status
```
- Monitor replication of Pages data: - Monitor replication of Pages data:
ghe-dpages replication-status ```
ghe-dpages replication-status
```
You can use `ghe-cluster-status` to review the overall health of your cluster. For more information, see "[Command-line utilities](/enterprise/admin/configuration/command-line-utilities#ghe-cluster-status)." You can use `ghe-cluster-status` to review the overall health of your cluster. For more information, see "[Command-line utilities](/enterprise/admin/configuration/command-line-utilities#ghe-cluster-status)."

2
content/admin/github-actions/manually-syncing-actions-from-githubcom.md
View File

@@ -24,7 +24,7 @@ The `actions-sync` tool can only download actions from {% data variables.product
### Prerequisites ### Prerequisites
* Before using the the `actions-sync` tool, you must ensure that all destination organizations already exist on your enterprise instance. The following example demonstrates how to sync actions to an organization named `synced-actions` on an enterprise instance. For more information, see "[Creating a new organization from scratch](/github/setting-up-and-managing-organizations-and-teams/creating-a-new-organization-from-scratch)." * Before using the `actions-sync` tool, you must ensure that all destination organizations already exist on your enterprise instance. The following example demonstrates how to sync actions to an organization named `synced-actions` on an enterprise instance. For more information, see "[Creating a new organization from scratch](/github/setting-up-and-managing-organizations-and-teams/creating-a-new-organization-from-scratch)."
* You must create a personal access token (PAT) on your enterprise instance that can create and write to repositories in the destination organizations. For more information, see "[Creating a personal access token](/github/authenticating-to-github/creating-a-personal-access-token)." * You must create a personal access token (PAT) on your enterprise instance that can create and write to repositories in the destination organizations. For more information, see "[Creating a personal access token](/github/authenticating-to-github/creating-a-personal-access-token)."
### Example: Using the `actions-sync` tool ### Example: Using the `actions-sync` tool

2
content/admin/github-actions/setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Setting up the tool cache on self-hosted runners without internet access title: Setting up the tool cache on self-hosted runners without internet access
intro: 'To use the the included `actions/setup` actions on self-hosted runners without internet access, you must first populate the runner''s tool cache for your workflows.' intro: 'To use the included `actions/setup` actions on self-hosted runners without internet access, you must first populate the runner''s tool cache for your workflows.'
redirect_from: redirect_from:
- /enterprise/admin/github-actions/setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access - /enterprise/admin/github-actions/setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access
versions: versions:

50
content/admin/installation/installing-github-enterprise-server-on-google-cloud-platform.md
View File

@@ -27,7 +27,7 @@ Before launching {% data variables.product.product_location %} on Google Cloud P
{% data variables.product.prodname_ghe_server %} is supported on the following Google Compute Engine (GCE) machine types. For more information, see [the Google Cloud Platform machine types article](https://cloud.google.com/compute/docs/machine-types). {% data variables.product.prodname_ghe_server %} is supported on the following Google Compute Engine (GCE) machine types. For more information, see [the Google Cloud Platform machine types article](https://cloud.google.com/compute/docs/machine-types).
| High-memory | | High-memory |
------------- | | ------------- |
| n1-highmem-4 | | n1-highmem-4 |
| n1-highmem-8 | | n1-highmem-8 |
| n1-highmem-16 | | n1-highmem-16 |
@@ -54,7 +54,7 @@ Based on your user license count, we recommend these machine types.
1. Using the [gcloud compute](https://cloud.google.com/compute/docs/gcloud-compute/) command-line tool, list the public {% data variables.product.prodname_ghe_server %} images: 1. Using the [gcloud compute](https://cloud.google.com/compute/docs/gcloud-compute/) command-line tool, list the public {% data variables.product.prodname_ghe_server %} images:
```shell ```shell
$ gcloud compute images list --project github-enterprise-public --no-standard-images $ gcloud compute images list --project github-enterprise-public --no-standard-images
``` ```
2. Take note of the image name for the latest GCE image of {% data variables.product.prodname_ghe_server %}. 2. Take note of the image name for the latest GCE image of {% data variables.product.prodname_ghe_server %}.
@@ -63,18 +63,18 @@ Based on your user license count, we recommend these machine types.
GCE virtual machines are created as a member of a network, which has a firewall. For the network associated with the {% data variables.product.prodname_ghe_server %} VM, you'll need to configure the firewall to allow the required ports listed in the table below. For more information about firewall rules on Google Cloud Platform, see the Google guide "[Firewall Rules Overview](https://cloud.google.com/vpc/docs/firewalls)." GCE virtual machines are created as a member of a network, which has a firewall. For the network associated with the {% data variables.product.prodname_ghe_server %} VM, you'll need to configure the firewall to allow the required ports listed in the table below. For more information about firewall rules on Google Cloud Platform, see the Google guide "[Firewall Rules Overview](https://cloud.google.com/vpc/docs/firewalls)."
1. Using the gcloud compute command-line tool, create the network. For more information, see "[gcloud compute networks create](https://cloud.google.com/sdk/gcloud/reference/compute/networks/create)" in the Google documentation. 1. Using the gcloud compute command-line tool, create the network. For more information, see "[gcloud compute networks create](https://cloud.google.com/sdk/gcloud/reference/compute/networks/create)" in the Google documentation.
```shell ```shell
$ gcloud compute networks create <em>NETWORK-NAME</em> --subnet-mode auto $ gcloud compute networks create <em>NETWORK-NAME</em> --subnet-mode auto
``` ```
2. Create a firewall rule for each of the ports in the table below. For more information, see "[gcloud compute firewall-rules](https://cloud.google.com/sdk/gcloud/reference/compute/firewall-rules/)" in the Google documentation. 2. Create a firewall rule for each of the ports in the table below. For more information, see "[gcloud compute firewall-rules](https://cloud.google.com/sdk/gcloud/reference/compute/firewall-rules/)" in the Google documentation.
```shell ```shell
$ gcloud compute firewall-rules create <em>RULE-NAME</em> \ $ gcloud compute firewall-rules create <em>RULE-NAME</em> \
--network <em>NETWORK-NAME</em> \ --network <em>NETWORK-NAME</em> \
--allow tcp:22,tcp:25,tcp:80,tcp:122,udp:161,tcp:443,udp:1194,tcp:8080,tcp:8443,tcp:9418,icmp --allow tcp:22,tcp:25,tcp:80,tcp:122,udp:161,tcp:443,udp:1194,tcp:8080,tcp:8443,tcp:9418,icmp
``` ```
This table identifies the required ports and what each port is used for. This table identifies the required ports and what each port is used for.
{% data reusables.enterprise_installation.necessary_ports %} {% data reusables.enterprise_installation.necessary_ports %}
### Allocating a static IP and assigning it to the VM ### Allocating a static IP and assigning it to the VM
@@ -87,21 +87,21 @@ In production High Availability configurations, both primary and replica applian
To create the {% data variables.product.prodname_ghe_server %} instance, you'll need to create a GCE instance with your {% data variables.product.prodname_ghe_server %} image and attach an additional storage volume for your instance data. For more information, see "[Hardware considerations](#hardware-considerations)." To create the {% data variables.product.prodname_ghe_server %} instance, you'll need to create a GCE instance with your {% data variables.product.prodname_ghe_server %} image and attach an additional storage volume for your instance data. For more information, see "[Hardware considerations](#hardware-considerations)."
1. Using the gcloud compute command-line tool, create a data disk to use as an attached storage volume for your instance data, and configure the size based on your user license count. For more information, see "[gcloud compute disks create](https://cloud.google.com/sdk/gcloud/reference/compute/disks/create)" in the Google documentation. 1. Using the gcloud compute command-line tool, create a data disk to use as an attached storage volume for your instance data, and configure the size based on your user license count. For more information, see "[gcloud compute disks create](https://cloud.google.com/sdk/gcloud/reference/compute/disks/create)" in the Google documentation.
```shell ```shell
$ gcloud compute disks create <em>DATA-DISK-NAME</em> --size <em>DATA-DISK-SIZE</em> --type <em>DATA-DISK-TYPE</em> --zone <em>ZONE</em> $ gcloud compute disks create <em>DATA-DISK-NAME</em> --size <em>DATA-DISK-SIZE</em> --type <em>DATA-DISK-TYPE</em> --zone <em>ZONE</em>
``` ```
2. Then create an instance using the name of the {% data variables.product.prodname_ghe_server %} image you selected, and attach the data disk. For more information, see "[gcloud compute instances create](https://cloud.google.com/sdk/gcloud/reference/compute/instances/create)" in the Google documentation. 2. Then create an instance using the name of the {% data variables.product.prodname_ghe_server %} image you selected, and attach the data disk. For more information, see "[gcloud compute instances create](https://cloud.google.com/sdk/gcloud/reference/compute/instances/create)" in the Google documentation.
```shell ```shell
$ gcloud compute instances create <em>INSTANCE-NAME</em> \ $ gcloud compute instances create <em>INSTANCE-NAME</em> \
--machine-type n1-standard-8 \ --machine-type n1-standard-8 \
--image <em>GITHUB-ENTERPRISE-IMAGE-NAME</em> \ --image <em>GITHUB-ENTERPRISE-IMAGE-NAME</em> \
--disk name=<em>DATA-DISK-NAME</em> \ --disk name=<em>DATA-DISK-NAME</em> \
--metadata serial-port-enable=1 \ --metadata serial-port-enable=1 \
--zone <em>ZONE</em> \ --zone <em>ZONE</em> \
--network <em>NETWORK-NAME</em> \ --network <em>NETWORK-NAME</em> \
--image-project github-enterprise-public --image-project github-enterprise-public
``` ```
### Configuring the instance ### Configuring the instance

4
content/admin/overview/about-the-github-enterprise-api.md
View File

@@ -19,6 +19,6 @@ With the APIs, you can automate many administrative tasks. Some examples include
- Perform changes to the {% data variables.enterprise.management_console %}. For more information, see "[{% data variables.enterprise.management_console %}](/enterprise/{{ currentVersion }}/user/rest/reference/enterprise-admin#management-console)." - Perform changes to the {% data variables.enterprise.management_console %}. For more information, see "[{% data variables.enterprise.management_console %}](/enterprise/{{ currentVersion }}/user/rest/reference/enterprise-admin#management-console)."
- Configure LDAP sync. For more information, see "[LDAP](/enterprise/{{ currentVersion }}/user/rest/reference/enterprise-admin#ldap)."{% endif %} - Configure LDAP sync. For more information, see "[LDAP](/enterprise/{{ currentVersion }}/user/rest/reference/enterprise-admin#ldap)."{% endif %}
- Collect statistics about your enterprise. For more information, see "[Admin stats](/rest/reference/enterprise-admin#admin-stats)." - Collect statistics about your enterprise. For more information, see "[Admin stats](/rest/reference/enterprise-admin#admin-stats)."
- Manage your enterprise account. For more information, see "[Enterprise accounts](/v4/guides/managing-enterprise-accounts)." - Manage your enterprise account. For more information, see "[Enterprise accounts](/graphql/guides/managing-enterprise-accounts)."
For the complete documentation for {% data variables.product.prodname_enterprise_api %}, see [{% data variables.product.prodname_dotcom %} REST API](/rest) and [{% data variables.product.prodname_dotcom%} GraphQL API](/graphql). For the complete documentation for {% data variables.product.prodname_enterprise_api %}, see [{% data variables.product.prodname_dotcom %} REST API](/rest) and [{% data variables.product.prodname_dotcom%} GraphQL API](/graphql).

36
content/admin/policies/creating-a-pre-receive-hook-environment.md
View File

@@ -21,10 +21,10 @@ You can use a Linux container management tool to build a pre-receive hook enviro
{% data reusables.linux.ensure-docker %} {% data reusables.linux.ensure-docker %}
2. Create the file `Dockerfile.alpine-3.3` that contains this information: 2. Create the file `Dockerfile.alpine-3.3` that contains this information:
``` ```
FROM gliderlabs/alpine:3.3 FROM gliderlabs/alpine:3.3
RUN apk add --no-cache git bash RUN apk add --no-cache git bash
``` ```
3. From the working directory that contains `Dockerfile.alpine-3.3`, build an image: 3. From the working directory that contains `Dockerfile.alpine-3.3`, build an image:
```shell ```shell
@@ -36,37 +36,37 @@ You can use a Linux container management tool to build a pre-receive hook enviro
> ---> Using cache > ---> Using cache
> ---> 0250ab3be9c5 > ---> 0250ab3be9c5
> Successfully built 0250ab3be9c5 > Successfully built 0250ab3be9c5
``` ```
4. Create a container: 4. Create a container:
```shell ```shell
$ docker create --name pre-receive.alpine-3.3 pre-receive.alpine-3.3 /bin/true $ docker create --name pre-receive.alpine-3.3 pre-receive.alpine-3.3 /bin/true
``` ```
5. Export the Docker container to a `gzip` compressed `tar` file: 5. Export the Docker container to a `gzip` compressed `tar` file:
```shell ```shell
$ docker export pre-receive.alpine-3.3 | gzip > alpine-3.3.tar.gz $ docker export pre-receive.alpine-3.3 | gzip > alpine-3.3.tar.gz
``` ```
This file `alpine-3.3.tar.gz` is ready to be uploaded to the {% data variables.product.prodname_ghe_server %} appliance. This file `alpine-3.3.tar.gz` is ready to be uploaded to the {% data variables.product.prodname_ghe_server %} appliance.
### Creating a pre-receive hook environment using chroot ### Creating a pre-receive hook environment using chroot
1. Create a Linux `chroot` environment. 1. Create a Linux `chroot` environment.
2. Create a `gzip` compressed `tar` file of the `chroot` directory. 2. Create a `gzip` compressed `tar` file of the `chroot` directory.
```shell ```shell
$ cd /path/to/chroot $ cd /path/to/chroot
$ tar -czf /path/to/pre-receive-environment.tar.gz . $ tar -czf /path/to/pre-receive-environment.tar.gz .
``` ```
{% note %} {% note %}
**Notes:** **Notes:**
- Do not include leading directory paths of files within the tar archive, such as `/path/to/chroot`. - Do not include leading directory paths of files within the tar archive, such as `/path/to/chroot`.
- `/bin/sh` must exist and be executable, as the entry point into the chroot environment. - `/bin/sh` must exist and be executable, as the entry point into the chroot environment.
- Unlike traditional chroots, the `dev` directory is not required by the chroot environment for pre-receive hooks. - Unlike traditional chroots, the `dev` directory is not required by the chroot environment for pre-receive hooks.
{% endnote %} {% endnote %}
For more information about creating a chroot environment see "[Chroot](https://wiki.debian.org/chroot)" from the *Debian Wiki*, "[BasicChroot](https://help.ubuntu.com/community/BasicChroot)" from the *Ubuntu Community Help Wiki*, or "[Installing Alpine Linux in a chroot](http://wiki.alpinelinux.org/wiki/Installing_Alpine_Linux_in_a_chroot)" from the *Alpine Linux Wiki*. For more information about creating a chroot environment see "[Chroot](https://wiki.debian.org/chroot)" from the *Debian Wiki*, "[BasicChroot](https://help.ubuntu.com/community/BasicChroot)" from the *Ubuntu Community Help Wiki*, or "[Installing Alpine Linux in a chroot](http://wiki.alpinelinux.org/wiki/Installing_Alpine_Linux_in_a_chroot)" from the *Alpine Linux Wiki*.
@@ -94,4 +94,4 @@ For more information about creating a chroot environment see "[Chroot](https://w
```shell ```shell
admin@ghe-host:~$ ghe-hook-env-create AlpineTestEnv /home/admin/alpine-3.3.tar.gz admin@ghe-host:~$ ghe-hook-env-create AlpineTestEnv /home/admin/alpine-3.3.tar.gz
> Pre-receive hook environment 'AlpineTestEnv' (2) has been created. > Pre-receive hook environment 'AlpineTestEnv' (2) has been created.
``` ```

72
content/admin/policies/creating-a-pre-receive-hook-script.md
View File

@@ -71,19 +71,19 @@ We recommend consolidating hooks to a single repository. If the consolidated hoo
```shell ```shell
$ sudo chmod +x <em>SCRIPT_FILE.sh</em> $ sudo chmod +x <em>SCRIPT_FILE.sh</em>
``` ```
For Windows users, ensure the scripts have execute permissions: For Windows users, ensure the scripts have execute permissions:
```shell ```shell
git update-index --chmod=+x <em>SCRIPT_FILE.sh</em> git update-index --chmod=+x <em>SCRIPT_FILE.sh</em>
``` ```
2. Commit and push to your designated pre-receive hooks repository on the {% data variables.product.prodname_ghe_server %} instance. 2. Commit and push to your designated pre-receive hooks repository on the {% data variables.product.prodname_ghe_server %} instance.
```shell ```shell
$ git commit -m "<em>YOUR COMMIT MESSAGE</em>" $ git commit -m "<em>YOUR COMMIT MESSAGE</em>"
$ git push $ git push
``` ```
3. [Create the pre-receive hook](/enterprise/{{ currentVersion }}/admin/guides/developer-workflow/managing-pre-receive-hooks-on-the-github-enterprise-server-appliance/#creating-pre-receive-hooks) on the {% data variables.product.prodname_ghe_server %} instance. 3. [Create the pre-receive hook](/enterprise/{{ currentVersion }}/admin/guides/developer-workflow/managing-pre-receive-hooks-on-the-github-enterprise-server-appliance/#creating-pre-receive-hooks) on the {% data variables.product.prodname_ghe_server %} instance.
@@ -94,40 +94,40 @@ You can test a pre-receive hook script locally before you create or update it on
2. Create a file called `Dockerfile.dev` containing: 2. Create a file called `Dockerfile.dev` containing:
``` ```
FROM gliderlabs/alpine:3.3 FROM gliderlabs/alpine:3.3
RUN \ RUN \
apk add --no-cache git openssh bash && \ apk add --no-cache git openssh bash && \
ssh-keygen -A && \ ssh-keygen -A && \
sed -i "s/#AuthorizedKeysFile/AuthorizedKeysFile/g" /etc/ssh/sshd_config && \ sed -i "s/#AuthorizedKeysFile/AuthorizedKeysFile/g" /etc/ssh/sshd_config && \
adduser git -D -G root -h /home/git -s /bin/bash && \ adduser git -D -G root -h /home/git -s /bin/bash && \
passwd -d git && \ passwd -d git && \
su git -c "mkdir /home/git/.ssh && \ su git -c "mkdir /home/git/.ssh && \
ssh-keygen -t ed25519 -f /home/git/.ssh/id_ed25519 -P '' && \ ssh-keygen -t ed25519 -f /home/git/.ssh/id_ed25519 -P '' && \
mv /home/git/.ssh/id_ed25519.pub /home/git/.ssh/authorized_keys && \ mv /home/git/.ssh/id_ed25519.pub /home/git/.ssh/authorized_keys && \
mkdir /home/git/test.git && \ mkdir /home/git/test.git && \
git --bare init /home/git/test.git" git --bare init /home/git/test.git"
VOLUME ["/home/git/.ssh", "/home/git/test.git/hooks"] VOLUME ["/home/git/.ssh", "/home/git/test.git/hooks"]
WORKDIR /home/git WORKDIR /home/git
CMD ["/usr/sbin/sshd", "-D"] CMD ["/usr/sbin/sshd", "-D"]
``` ```
3. Create a test pre-receive script called `always_reject.sh`. This example script will reject all pushes, which is useful for locking a repository: 3. Create a test pre-receive script called `always_reject.sh`. This example script will reject all pushes, which is useful for locking a repository:
``` ```
#!/usr/bin/env bash #!/usr/bin/env bash
echo "error: rejecting all pushes" echo "error: rejecting all pushes"
exit 1 exit 1
``` ```
4. Ensure the `always_reject.sh` scripts has execute permissions: 4. Ensure the `always_reject.sh` scripts has execute permissions:
```shell ```shell
$ chmod +x always_reject.sh $ chmod +x always_reject.sh
``` ```
5. From the directory containing `Dockerfile.dev`, build an image: 5. From the directory containing `Dockerfile.dev`, build an image:
@@ -150,32 +150,32 @@ You can test a pre-receive hook script locally before you create or update it on
....truncated output.... ....truncated output....
> Initialized empty Git repository in /home/git/test.git/ > Initialized empty Git repository in /home/git/test.git/
> Successfully built dd8610c24f82 > Successfully built dd8610c24f82
``` ```
6. Run a data container that contains a generated SSH key: 6. Run a data container that contains a generated SSH key:
```shell ```shell
$ docker run --name data pre-receive.dev /bin/true $ docker run --name data pre-receive.dev /bin/true
``` ```
7. Copy the test pre-receive hook `always_reject.sh` into the data container: 7. Copy the test pre-receive hook `always_reject.sh` into the data container:
```shell ```shell
$ docker cp always_reject.sh data:/home/git/test.git/hooks/pre-receive $ docker cp always_reject.sh data:/home/git/test.git/hooks/pre-receive
``` ```
8. Run an application container that runs `sshd` and executes the hook. Take note of the container id that is returned: 8. Run an application container that runs `sshd` and executes the hook. Take note of the container id that is returned:
```shell ```shell
$ docker run -d -p 52311:22 --volumes-from data pre-receive.dev $ docker run -d -p 52311:22 --volumes-from data pre-receive.dev
> 7f888bc700b8d23405dbcaf039e6c71d486793cad7d8ae4dd184f4a47000bc58 > 7f888bc700b8d23405dbcaf039e6c71d486793cad7d8ae4dd184f4a47000bc58
``` ```
9. Copy the generated SSH key from the data container to the local machine: 9. Copy the generated SSH key from the data container to the local machine:
```shell ```shell
$ docker cp data:/home/git/.ssh/id_ed25519 . $ docker cp data:/home/git/.ssh/id_ed25519 .
``` ```
10. Modify the remote of a test repository and push to the `test.git` repo within the Docker container. This example uses `git@github.com:octocat/Hello-World.git` but you can use any repo you want. This example assumes your local machine (127.0.0.1) is binding port 52311, but you can use a different IP address if docker is running on a remote machine. 10. Modify the remote of a test repository and push to the `test.git` repo within the Docker container. This example uses `git@github.com:octocat/Hello-World.git` but you can use any repo you want. This example assumes your local machine (127.0.0.1) is binding port 52311, but you can use a different IP address if docker is running on a remote machine.
@@ -194,9 +194,9 @@ You can test a pre-receive hook script locally before you create or update it on
> To git@192.168.99.100:test.git > To git@192.168.99.100:test.git
> ! [remote rejected] main -> main (pre-receive hook declined) > ! [remote rejected] main -> main (pre-receive hook declined)
> error: failed to push some refs to 'git@192.168.99.100:test.git' > error: failed to push some refs to 'git@192.168.99.100:test.git'
``` ```
Notice that the push was rejected after executing the pre-receive hook and echoing the output from the script. Notice that the push was rejected after executing the pre-receive hook and echoing the output from the script.
### Further reading ### Further reading
- "[Customizing Git - An Example Git-Enforced Policy](https://git-scm.com/book/en/v2/Customizing-Git-An-Example-Git-Enforced-Policy)" from the *Pro Git website* - "[Customizing Git - An Example Git-Enforced Policy](https://git-scm.com/book/en/v2/Customizing-Git-An-Example-Git-Enforced-Policy)" from the *Pro Git website*

2
content/admin/user-management/audited-actions.md
View File

@@ -27,7 +27,7 @@ Name | Description
[add key]: /articles/adding-a-new-ssh-key-to-your-github-account [add key]: /articles/adding-a-new-ssh-key-to-your-github-account
[deploy key]: /guides/managing-deploy-keys/#deploy-keys [deploy key]: /guides/managing-deploy-keys/#deploy-keys
[generate token]: /articles/creating-an-access-token-for-command-line-use [generate token]: /articles/creating-an-access-token-for-command-line-use
[OAuth access token]: /v3/oauth/ [OAuth access token]: /developers/apps/authorizing-oauth-apps
[OAuth application]: /guides/basics-of-authentication/#registering-your-app [OAuth application]: /guides/basics-of-authentication/#registering-your-app
[2fa]: /articles/about-two-factor-authentication [2fa]: /articles/about-two-factor-authentication

4
content/admin/user-management/exporting-migration-data-from-githubcom.md
View File

@@ -27,7 +27,7 @@ versions:
To export repository data from {% data variables.product.prodname_dotcom_the_website %}, use <a href="/rest/reference/migrations" class="dotcom-only">the Migrations API</a>. To export repository data from {% data variables.product.prodname_dotcom_the_website %}, use <a href="/rest/reference/migrations" class="dotcom-only">the Migrations API</a>.
The Migrations API is currently in a preview period, which means that the endpoints and parameters may change in the future. To access the Migrations API, you must provide a custom [media type](/v3/media) in the `Accept` header: `application/vnd.github.wyandotte-preview+json`. The examples below include the custom media type. The Migrations API is currently in a preview period, which means that the endpoints and parameters may change in the future. To access the Migrations API, you must provide a custom [media type](/rest/overview/media-types) in the `Accept` header: `application/vnd.github.wyandotte-preview+json`. The examples below include the custom media type.
### Generating a migration archive ### Generating a migration archive
@@ -37,7 +37,7 @@ The Migrations API is currently in a preview period, which means that the endpoi
2. Start a migration by `POST`ing to <a href="/rest/reference/migrations#start-an-organization-migration" class="dotcom-only">the migration endpoint</a>. You'll need: 2. Start a migration by `POST`ing to <a href="/rest/reference/migrations#start-an-organization-migration" class="dotcom-only">the migration endpoint</a>. You'll need:
* Your access token for authentication. * Your access token for authentication.
* A [list of the repositories](/v3/repos/#list-organization-repositories) you want to migrate: * A [list of the repositories](/rest/reference/repos#list-organization-repositories) you want to migrate:
```shell ```shell
curl -H "Authorization: token <em>GITHUB_ACCESS_TOKEN</em>" -X POST \ curl -H "Authorization: token <em>GITHUB_ACCESS_TOKEN</em>" -X POST \
-H "Accept: application/vnd.github.wyandotte-preview+json" \ -H "Accept: application/vnd.github.wyandotte-preview+json" \

2
content/admin/user-management/migrating-data-to-your-enterprise.md
View File

@@ -131,7 +131,7 @@ curl -H "Authorization: token <em>GITHUB_ACCESS_TOKEN</em>" -X DELETE \
#### Deleting repositories from an organization on {% data variables.product.prodname_dotcom_the_website %} #### Deleting repositories from an organization on {% data variables.product.prodname_dotcom_the_website %}
After unlocking the {% data variables.product.prodname_dotcom_the_website %} organization's repositories, you should delete every repository you previously migrated using [the repository delete endpoint](/enterprise/{{ currentVersion }}/v3/repos/#delete-a-repository). You'll need your access token for authentication: After unlocking the {% data variables.product.prodname_dotcom_the_website %} organization's repositories, you should delete every repository you previously migrated using [the repository delete endpoint](/rest/reference/repos/#delete-a-repository). You'll need your access token for authentication:
```shell ```shell
curl -H "Authorization: token <em>GITHUB_ACCESS_TOKEN</em>" -X DELETE \ curl -H "Authorization: token <em>GITHUB_ACCESS_TOKEN</em>" -X DELETE \
https://api.github.com/repos/<em>orgname</em>/<em>repo_name</em> https://api.github.com/repos/<em>orgname</em>/<em>repo_name</em>

2
content/admin/user-management/suspending-and-unsuspending-users.md
View File

@@ -92,4 +92,4 @@ You can create a custom message that suspended users will see when attempting to
``` ```
### Further reading ### Further reading
- "[Suspend a user](/enterprise/{{ currentVersion }}/v3/enterprise-admin/users/#suspend-a-user)" - "[Suspend a user](/rest/reference/enterprise-admin#suspend-a-user)"

4
content/developers/apps/about-apps.md
View File

@@ -67,13 +67,13 @@ Keep these ideas in mind when creating {% data variables.product.prodname_oauth_
* Don't build an {% data variables.product.prodname_oauth_app %} to act as an application for your team or company. {% data variables.product.prodname_oauth_app %}s authenticate as a single user, so if one person creates an {% data variables.product.prodname_oauth_app %} for a company to use, and then they leave the company, no one else will have access to it.{% if currentVersion == "free-pro-team@latest" %} * Don't build an {% data variables.product.prodname_oauth_app %} to act as an application for your team or company. {% data variables.product.prodname_oauth_app %}s authenticate as a single user, so if one person creates an {% data variables.product.prodname_oauth_app %} for a company to use, and then they leave the company, no one else will have access to it.{% if currentVersion == "free-pro-team@latest" %}
* {% data reusables.apps.oauth-apps-restrictions %}{% endif %} * {% data reusables.apps.oauth-apps-restrictions %}{% endif %}
For more on {% data variables.product.prodname_oauth_app %}s, see "[Creating an {% data variables.product.prodname_oauth_app %}](/apps/building-oauth-apps/creating-an-oauth-app/)" and "[Registering your app](/v3/guides/basics-of-authentication/#registering-your-app)." For more on {% data variables.product.prodname_oauth_app %}s, see "[Creating an {% data variables.product.prodname_oauth_app %}](/apps/building-oauth-apps/creating-an-oauth-app/)" and "[Registering your app](/rest/guides/basics-of-authentication#registering-your-app)."
### Personal access tokens ### Personal access tokens
A [personal access token](/articles/creating-a-personal-access-token-for-the-command-line/) is a string of characters that functions similarly to an [OAuth token](/apps/building-oauth-apps/authorizing-oauth-apps/) in that you can specify its permissions via [scopes](/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/). A personal access token is also similar to a password, but you can have many of them and you can revoke access to each one at any time. A [personal access token](/articles/creating-a-personal-access-token-for-the-command-line/) is a string of characters that functions similarly to an [OAuth token](/apps/building-oauth-apps/authorizing-oauth-apps/) in that you can specify its permissions via [scopes](/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/). A personal access token is also similar to a password, but you can have many of them and you can revoke access to each one at any time.
As an example, you can enable a personal access token to write to your repositories. If then you run a cURL command or write a script that [creates an issue](/v3/issues/#create-an-issue) in your repository, you would pass the personal access token to authenticate. You can store the personal access token as an environment variable to avoid typing it every time you use it. As an example, you can enable a personal access token to write to your repositories. If then you run a cURL command or write a script that [creates an issue](/rest/reference/issues#create-an-issue) in your repository, you would pass the personal access token to authenticate. You can store the personal access token as an environment variable to avoid typing it every time you use it.
Keep these ideas in mind when using personal access tokens: Keep these ideas in mind when using personal access tokens:

10
content/developers/apps/authenticating-with-github-apps.md
View File

@@ -120,13 +120,13 @@ You'll need to create a new JWT after the time expires.
### Accessing API endpoints as a {% data variables.product.prodname_github_app %} ### Accessing API endpoints as a {% data variables.product.prodname_github_app %}
For a list of REST API endpoints you can use to get high-level information about a {% data variables.product.prodname_github_app %}, see "[GitHub Apps](/v3/apps/)." For a list of REST API endpoints you can use to get high-level information about a {% data variables.product.prodname_github_app %}, see "[GitHub Apps](/rest/reference/apps)."
### Authenticating as an installation ### Authenticating as an installation
Authenticating as an installation lets you perform actions in the API for that installation. Before authenticating as an installation, you must create an installation access token. These installation access tokens are used by {% data variables.product.prodname_github_app %}s to authenticate. Authenticating as an installation lets you perform actions in the API for that installation. Before authenticating as an installation, you must create an installation access token. These installation access tokens are used by {% data variables.product.prodname_github_app %}s to authenticate.
By default, installation access tokens are scoped to all the repositories that an installation can access. You can limit the scope of the installation access token to specific repositories by using the `repository_ids` parameter. See the [Create an installation access token for an app](/v3/apps/#create-an-installation-access-token-for-an-app) endpoint for more details. Installation access tokens have the permissions configured by the {% data variables.product.prodname_github_app %} and expire after one hour. By default, installation access tokens are scoped to all the repositories that an installation can access. You can limit the scope of the installation access token to specific repositories by using the `repository_ids` parameter. See the [Create an installation access token for an app](/rest/reference/apps#create-an-installation-access-token-for-an-app) endpoint for more details. Installation access tokens have the permissions configured by the {% data variables.product.prodname_github_app %} and expire after one hour.
To create an installation access token, include the JWT [generated above](#jwt-payload) in the Authorization header in the API request: To create an installation access token, include the JWT [generated above](#jwt-payload) in the Authorization header in the API request:
@@ -146,7 +146,7 @@ $ curl -i -X POST \
``` ```
{% endif %} {% endif %}
The response will include your installation access token, the expiration date, the token's permissions, and the repositories that the token can access. For more information about the response format, see the [Create an installation access token for an app](/v3/apps/#create-an-installation-access-token-for-an-app) endpoint. The response will include your installation access token, the expiration date, the token's permissions, and the repositories that the token can access. For more information about the response format, see the [Create an installation access token for an app](/rest/reference/apps#create-an-installation-access-token-for-an-app) endpoint.
To authenticate with an installation access token, include it in the Authorization header in the API request: To authenticate with an installation access token, include it in the Authorization header in the API request:
@@ -170,9 +170,9 @@ $ curl -i \
### Accessing API endpoints as an installation ### Accessing API endpoints as an installation
For a list of REST API endpoints that are available for use by {% data variables.product.prodname_github_app %}s using an installation access token, see "[Available Endpoints](/v3/apps/available-endpoints/)." For a list of REST API endpoints that are available for use by {% data variables.product.prodname_github_app %}s using an installation access token, see "[Available Endpoints](/rest/overview/endpoints-available-for-github-apps)."
For a list of endpoints related to installations, see "[Installations](/v3/apps/installations/)." For a list of endpoints related to installations, see "[Installations](/rest/reference/apps#installations)."
### HTTP-based Git access by an installation ### HTTP-based Git access by an installation

6
content/developers/apps/authorizing-oauth-apps.md
View File

@@ -236,13 +236,13 @@ For more information, see the "[OAuth 2.0 Device Authorization Grant](https://to
### Non-Web application flow ### Non-Web application flow
Non-web authentication is available for limited situations like testing. If you need to, you can use [Basic Authentication](/v3/auth#basic-authentication) to create a personal access token using your [Personal access tokens settings page](/articles/creating-an-access-token-for-command-line-use). This technique enables the user to revoke access at any time. Non-web authentication is available for limited situations like testing. If you need to, you can use [Basic Authentication](/rest/overview/other-authentication-methods#basic-authentication) to create a personal access token using your [Personal access tokens settings page](/articles/creating-an-access-token-for-command-line-use). This technique enables the user to revoke access at any time.
{% if currentVersion == "free-pro-team@latest" or enterpriseServerVersions contains currentVersion %} {% if currentVersion == "free-pro-team@latest" or enterpriseServerVersions contains currentVersion %}
{% note %} {% note %}
**Note:** When using the non-web application flow to create an OAuth2 token, make sure to understand how to [work with **Note:** When using the non-web application flow to create an OAuth2 token, make sure to understand how to [work with
two-factor authentication](/v3/auth/#working-with-two-factor-authentication) if two-factor authentication](/rest/overview/other-authentication-methods#working-with-two-factor-authentication) if
you or your users have two-factor authentication enabled. you or your users have two-factor authentication enabled.
{% endnote %} {% endnote %}
@@ -296,7 +296,7 @@ To build this link, you'll need your OAuth Apps `client_id` that you received fr
{% tip %} {% tip %}
**Tip:** To learn more about the resources that your OAuth App can access for a user, see "[Discovering resources for a user](/v3/guides/discovering-resources-for-a-user/)." **Tip:** To learn more about the resources that your OAuth App can access for a user, see "[Discovering resources for a user](/rest/guides/discovering-resources-for-a-user)."
{% endtip %} {% endtip %}

10
content/developers/apps/creating-a-github-app-from-a-manifest.md
View File

@@ -61,7 +61,7 @@ The person creating the app will be redirected to a GitHub page with an input fi
`description` | `string` | A description of the GitHub App. `description` | `string` | A description of the GitHub App.
`public` | `boolean` | Set to `true` when your GitHub App is available to the public or `false` when it is only accessible to the owner of the app. `public` | `boolean` | Set to `true` when your GitHub App is available to the public or `false` when it is only accessible to the owner of the app.
`default_events` | `array` | The list of [events](/webhooks/event-payloads) the GitHub App subscribes to. `default_events` | `array` | The list of [events](/webhooks/event-payloads) the GitHub App subscribes to.
`default_permissions` | `object` | The set of [permissions](/v3/apps/permissions/) needed by the GitHub App. The format of the object uses the permission name for the key (for example, `issues`) and the access type for the value (for example, `write`). `default_permissions` | `object` | The set of [permissions](/rest/reference/permissions-required-for-github-apps) needed by the GitHub App. The format of the object uses the permission name for the key (for example, `issues`) and the access type for the value (for example, `write`).
The `hook_attributes` object has the following key: The `hook_attributes` object has the following key:
@@ -153,13 +153,13 @@ If you provided a `state` parameter, you will also see that parameter in the `re
#### 3. You exchange the temporary code to retrieve the app configuration #### 3. You exchange the temporary code to retrieve the app configuration
To complete the handshake, send the temporary `code` in a `POST` request to the [Create a GitHub App from a manifest](/v3/apps/#create-a-github-app-from-a-manifest) endpoint. The response will include the `id` (GitHub App ID), `pem` (private key), and `webhook_secret`. GitHub creates a webhook secret for the app automatically. You can store these values in environment variables on the app's server. For example, if your app uses [dotenv](https://github.com/bkeepers/dotenv) to store environment variables, you would store the variables in your app's `.env` file. To complete the handshake, send the temporary `code` in a `POST` request to the [Create a GitHub App from a manifest](/rest/reference/apps#create-a-github-app-from-a-manifest) endpoint. The response will include the `id` (GitHub App ID), `pem` (private key), and `webhook_secret`. GitHub creates a webhook secret for the app automatically. You can store these values in environment variables on the app's server. For example, if your app uses [dotenv](https://github.com/bkeepers/dotenv) to store environment variables, you would store the variables in your app's `.env` file.
You must complete this step of the GitHub App Manifest flow within one hour. You must complete this step of the GitHub App Manifest flow within one hour.
{% note %} {% note %}
**Note:** This endpoint is rate limited. See [Rate limits](/v3/rate_limit/) to learn how to get your current rate limit status. **Note:** This endpoint is rate limited. See [Rate limits](/rest/reference/rate-limit) to learn how to get your current rate limit status.
{% endnote %} {% endnote %}
@@ -170,7 +170,7 @@ You must complete this step of the GitHub App Manifest flow within one hour.
POST /app-manifests/:code/conversions POST /app-manifests/:code/conversions
For more information about the endpoint's response, see [Create a GitHub App from a manifest](/v3/apps/#create-a-github-app-from-a-manifest). For more information about the endpoint's response, see [Create a GitHub App from a manifest](/rest/reference/apps#create-a-github-app-from-a-manifest).
When the final step in the manifest flow is completed, the person creating the app from the flow will be an owner of a registered GitHub App that they can install on any of their personal repositories. They can choose to extend the app using the GitHub APIs, transfer ownership to someone else, or delete it at any time. When the final step in the manifest flow is completed, the person creating the app from the flow will be an owner of a registered GitHub App that they can install on any of their personal repositories. They can choose to extend the app using the GitHub APIs, transfer ownership to someone else, or delete it at any time.
@@ -191,4 +191,4 @@ Using [dotenv](https://github.com/bkeepers/dotenv), Probot creates a `.env` file
#### Hosting your app with Glitch #### Hosting your app with Glitch
You can see an [example Probot app](https://glitch.com/~auspicious-aardwolf) that uses [Glitch](https://glitch.com/) to host and share the app. The example uses the [Checks API](/v3/checks/) and selects the necessary Checks API events and permissions in the `app.yml` file. Glitch is a tool that allows you to "Remix your own" apps. Remixing an app creates a copy of the app that Glitch hosts and deploys. See "[About Glitch](https://glitch.com/about/)" to learn about remixing Glitch apps. You can see an [example Probot app](https://glitch.com/~auspicious-aardwolf) that uses [Glitch](https://glitch.com/) to host and share the app. The example uses the [Checks API](/rest/reference/checks) and selects the necessary Checks API events and permissions in the `app.yml` file. Glitch is a tool that allows you to "Remix your own" apps. Remixing an app creates a copy of the app that Glitch hosts and deploys. See "[About Glitch](https://glitch.com/about/)" to learn about remixing Glitch apps.

38
content/developers/apps/creating-a-github-app-using-url-parameters.md
View File

@@ -52,32 +52,32 @@ You can select permissions in a query string using the permission name in the fo
Permission | Description Permission | Description
---------- | ----------- ---------- | -----------
[`administration`](/rest/reference/permissions-required-for-github-apps/#permission-on-administration) | Grants access to various endpoints for organization and repository administration. Can be one of: `none`, `read`, or `write`.{% if currentVersion == "free-pro-team@latest" %} [`administration`](/rest/reference/permissions-required-for-github-apps/#permission-on-administration) | Grants access to various endpoints for organization and repository administration. Can be one of: `none`, `read`, or `write`.{% if currentVersion == "free-pro-team@latest" %}
[`blocking`](/rest/reference/permissions-required-for-github-apps/#permission-on-blocking) | Grants access to the [Blocking Users API](/v3/users/blocking/). Can be one of: `none`, `read`, or `write`.{% endif %} [`blocking`](/rest/reference/permissions-required-for-github-apps/#permission-on-blocking) | Grants access to the [Blocking Users API](/rest/reference/users#blocking). Can be one of: `none`, `read`, or `write`.{% endif %}
[`checks`](/rest/reference/permissions-required-for-github-apps/#permission-on-checks) | Grants access to the [Checks API](/v3/checks/). Can be one of: `none`, `read`, or `write`. [`checks`](/rest/reference/permissions-required-for-github-apps/#permission-on-checks) | Grants access to the [Checks API](/rest/reference/checks). Can be one of: `none`, `read`, or `write`.
`content_references` | Grants access to the "[Create a content attachment](/v3/apps/installations/#create-a-content-attachment)" endpoint. Can be one of: `none`, `read`, or `write`. `content_references` | Grants access to the "[Create a content attachment](/rest/reference/apps#create-a-content-attachment)" endpoint. Can be one of: `none`, `read`, or `write`.
[`contents`](/rest/reference/permissions-required-for-github-apps/#permission-on-contents) | Grants access to various endpoints that allow you to modify repository contents. Can be one of: `none`, `read`, or `write`. [`contents`](/rest/reference/permissions-required-for-github-apps/#permission-on-contents) | Grants access to various endpoints that allow you to modify repository contents. Can be one of: `none`, `read`, or `write`.
[`deployments`](/rest/reference/permissions-required-for-github-apps/#permission-on-deployments) | Grants access to the [Deployments API](/rest/reference/repos#deployments). Can be one of: `none`, `read`, or `write`.{% if currentVersion == "free-pro-team@latest" or enterpriseServerVersions contains currentVersion %} [`deployments`](/rest/reference/permissions-required-for-github-apps/#permission-on-deployments) | Grants access to the [Deployments API](/rest/reference/repos#deployments). Can be one of: `none`, `read`, or `write`.{% if currentVersion == "free-pro-team@latest" or enterpriseServerVersions contains currentVersion %}
[`emails`](/rest/reference/permissions-required-for-github-apps/#permission-on-emails) | Grants access to the [Emails API](/v3/users/emails/). Can be one of: `none`, `read`, or `write`.{% endif %} [`emails`](/rest/reference/permissions-required-for-github-apps/#permission-on-emails) | Grants access to the [Emails API](/rest/reference/users#emails). Can be one of: `none`, `read`, or `write`.{% endif %}
[`followers`](/rest/reference/permissions-required-for-github-apps/#permission-on-followers) | Grants access to the [Followers API](/v3/users/followers/). Can be one of: `none`, `read`, or `write`. [`followers`](/rest/reference/permissions-required-for-github-apps/#permission-on-followers) | Grants access to the [Followers API](/rest/reference/users#followers). Can be one of: `none`, `read`, or `write`.
[`gpg_keys`](/rest/reference/permissions-required-for-github-apps/#permission-on-gpg-keys) | Grants access to the [GPG Keys API](/v3/users/gpg_keys/). Can be one of: `none`, `read`, or `write`. [`gpg_keys`](/rest/reference/permissions-required-for-github-apps/#permission-on-gpg-keys) | Grants access to the [GPG Keys API](/rest/reference/users#gpg-keys). Can be one of: `none`, `read`, or `write`.
[`issues`](/rest/reference/permissions-required-for-github-apps/#permission-on-issues) | Grants access to the [Issues API](/v3/issues/). Can be one of: `none`, `read`, or `write`. [`issues`](/rest/reference/permissions-required-for-github-apps/#permission-on-issues) | Grants access to the [Issues API](/rest/reference/issues). Can be one of: `none`, `read`, or `write`.
[`keys`](/rest/reference/permissions-required-for-github-apps/#permission-on-keys) | Grants access to the [Public Keys API](/v3/users/keys/). Can be one of: `none`, `read`, or `write`. [`keys`](/rest/reference/permissions-required-for-github-apps/#permission-on-keys) | Grants access to the [Public Keys API](/rest/reference/users#keys). Can be one of: `none`, `read`, or `write`.
[`members`](/rest/reference/permissions-required-for-github-apps/#permission-on-members) | Grants access to manage an organization's members. Can be one of: `none`, `read`, or `write`.{% if currentVersion == "free-pro-team@latest" %} [`members`](/rest/reference/permissions-required-for-github-apps/#permission-on-members) | Grants access to manage an organization's members. Can be one of: `none`, `read`, or `write`.{% if currentVersion == "free-pro-team@latest" %}
[`metadata`](/rest/reference/permissions-required-for-github-apps/#metadata-permissions) | Grants access to read-only endpoints that do not leak sensitive data. Can be `read` or `none`. Defaults to `read` when you set any permission, or defaults to `none` when you don't specify any permissions for the {% data variables.product.prodname_github_app %}. [`metadata`](/rest/reference/permissions-required-for-github-apps/#metadata-permissions) | Grants access to read-only endpoints that do not leak sensitive data. Can be `read` or `none`. Defaults to `read` when you set any permission, or defaults to `none` when you don't specify any permissions for the {% data variables.product.prodname_github_app %}.
[`organization_administration`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-administration) | Grants access to "[Update an organization](/v3/orgs/#update-an-organization)" endpoint and the [Organization Interaction Restrictions API](/v3/interactions/orgs/#set-interaction-restrictions-for-an-organization). Can be one of: `none`, `read`, or `write`.{% endif %} [`organization_administration`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-administration) | Grants access to "[Update an organization](/rest/reference/orgs#update-an-organization)" endpoint and the [Organization Interaction Restrictions API](/rest/reference/interactions#set-interaction-restrictions-for-an-organization). Can be one of: `none`, `read`, or `write`.{% endif %}
[`organization_hooks`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-hooks) | Grants access to the [Organization Webhooks API](/rest/reference/orgs#webhooks/). Can be one of: `none`, `read`, or `write`. [`organization_hooks`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-hooks) | Grants access to the [Organization Webhooks API](/rest/reference/orgs#webhooks/). Can be one of: `none`, `read`, or `write`.
`organization_plan` | Grants access to get information about an organization's plan using the "[Get an organization](/v3/orgs/#get-an-organization)" endpoint. Can be one of: `none` or `read`. `organization_plan` | Grants access to get information about an organization's plan using the "[Get an organization](/rest/reference/orgs#get-an-organization)" endpoint. Can be one of: `none` or `read`.
[`organization_projects`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-projects) | Grants access to the [Projects API](/v3/projects/). Can be one of: `none`, `read`, `write`, or `admin`.{% if currentVersion == "free-pro-team@latest" %} [`organization_projects`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-projects) | Grants access to the [Projects API](/rest/reference/projects). Can be one of: `none`, `read`, `write`, or `admin`.{% if currentVersion == "free-pro-team@latest" %}
[`organization_user_blocking`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-projects) | Grants access to the [Blocking Organization Users API](/v3/orgs/blocking/). Can be one of: `none`, `read`, or `write`.{% endif %} [`organization_user_blocking`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-projects) | Grants access to the [Blocking Organization Users API](/rest/reference/orgs#blocking). Can be one of: `none`, `read`, or `write`.{% endif %}
[`pages`](/rest/reference/permissions-required-for-github-apps/#permission-on-pages) | Grants access to the [Pages API](/rest/reference/repos#pages). Can be one of: `none`, `read`, or `write`. [`pages`](/rest/reference/permissions-required-for-github-apps/#permission-on-pages) | Grants access to the [Pages API](/rest/reference/repos#pages). Can be one of: `none`, `read`, or `write`.
`plan` | Grants access to get information about a user's GitHub plan using the "[Get a user](/v3/users/#get-a-user)" endpoint. Can be one of: `none` or `read`. `plan` | Grants access to get information about a user's GitHub plan using the "[Get a user](/rest/reference/users#get-a-user)" endpoint. Can be one of: `none` or `read`.
[`pull_requests`](/rest/reference/permissions-required-for-github-apps/#permission-on-pull-requests) | Grants access to various pull request endpoints. Can be one of: `none`, `read`, or `write`. [`pull_requests`](/rest/reference/permissions-required-for-github-apps/#permission-on-pull-requests) | Grants access to various pull request endpoints. Can be one of: `none`, `read`, or `write`.
[`repository_hooks`](/rest/reference/permissions-required-for-github-apps/#permission-on-repository-hooks) | Grants access to the [Repository Webhooks API](/v3/repos/hooks/). Can be one of: `none`, `read`, or `write`. [`repository_hooks`](/rest/reference/permissions-required-for-github-apps/#permission-on-repository-hooks) | Grants access to the [Repository Webhooks API](/rest/reference/repos#hooks). Can be one of: `none`, `read`, or `write`.
[`repository_projects`](/rest/reference/permissions-required-for-github-apps/#permission-on-repository-projects) | Grants access to the [Projects API](/v3/projects/). Can be one of: `none`, `read`, `write`, or `admin`. [`repository_projects`](/rest/reference/permissions-required-for-github-apps/#permission-on-repository-projects) | Grants access to the [Projects API](/rest/reference/projects). Can be one of: `none`, `read`, `write`, or `admin`.
[`single_file`](/rest/reference/permissions-required-for-github-apps/#permission-on-single-file) | Grants access to the [Contents API](/v3/repos/contents/). Can be one of: `none`, `read`, or `write`. [`single_file`](/rest/reference/permissions-required-for-github-apps/#permission-on-single-file) | Grants access to the [Contents API](/rest/reference/repos#contents). Can be one of: `none`, `read`, or `write`.
[`starring`](/rest/reference/permissions-required-for-github-apps/#permission-on-starring) | Grants access to the [Starring API](/v3/activity/starring/). Can be one of: `none`, `read`, or `write`. [`starring`](/rest/reference/permissions-required-for-github-apps/#permission-on-starring) | Grants access to the [Starring API](/rest/reference/activity#starring). Can be one of: `none`, `read`, or `write`.
[`statuses`](/rest/reference/permissions-required-for-github-apps/#permission-on-statuses) | Grants access to the [Statuses API](/v3/repos/statuses/). Can be one of: `none`, `read`, or `write`. [`statuses`](/rest/reference/permissions-required-for-github-apps/#permission-on-statuses) | Grants access to the [Statuses API](/rest/reference/repos#statuses). Can be one of: `none`, `read`, or `write`.
[`team_discussions`](/rest/reference/permissions-required-for-github-apps/#permission-on-team-discussions) | Grants access to the [Team Discussions API](/v3/teams/discussions/) and the [Team Discussion Comments API](/v3/teams/discussion_comments/). Can be one of: `none`, `read`, or `write`. [`team_discussions`](/rest/reference/permissions-required-for-github-apps/#permission-on-team-discussions) | Grants access to the [Team Discussions API](/rest/reference/teams#discussions) and the [Team Discussion Comments API](/rest/reference/teams#discussion-comments). Can be one of: `none`, `read`, or `write`.
`vulnerability_alerts`| Grants access to receive security alerts for vulnerable dependencies in a repository. See "[About security alerts for vulnerable dependencies](/articles/about-security-alerts-for-vulnerable-dependencies)" to learn more. Can be one of: `none` or `read`. `vulnerability_alerts`| Grants access to receive security alerts for vulnerable dependencies in a repository. See "[About security alerts for vulnerable dependencies](/articles/about-security-alerts-for-vulnerable-dependencies)" to learn more. Can be one of: `none` or `read`.
`watching` | Grants access to list and change repositories a user is subscribed to. Can be one of: `none`, `read`, or `write`. `watching` | Grants access to list and change repositories a user is subscribed to. Can be one of: `none`, `read`, or `write`.

40
content/developers/apps/creating-ci-tests-with-the-checks-api.md
View File

@@ -12,7 +12,7 @@ versions:
### Introduction ### Introduction
This guide will introduce you to [Github Apps](/apps/) and the [Checks API](/v3/checks/), which you'll use to build a continuous integration (CI) server that runs tests. This guide will introduce you to [Github Apps](/apps/) and the [Checks API](/rest/reference/checks), which you'll use to build a continuous integration (CI) server that runs tests.
CI is a software practice that requires frequently committing code to a shared repository. Committing code more often raises errors sooner and reduces the amount of code a developer needs to debug when finding the source of an error. Frequent code updates also make it easier to merge changes from different members of a software development team. This is great for developers, who can spend more time writing code and less time debugging errors or resolving merge conflicts. 🙌 CI is a software practice that requires frequently committing code to a shared repository. Committing code more often raises errors sooner and reduces the amount of code a developer needs to debug when finding the source of an error. Frequent code updates also make it easier to merge changes from different members of a software development team. This is great for developers, who can spend more time writing code and less time debugging errors or resolving merge conflicts. 🙌
@@ -22,15 +22,15 @@ A CI server hosts code that runs CI tests such as code linters (which check styl
#### Checks API overview #### Checks API overview
The [Checks API](/v3/checks/) allows you to set up CI tests that are automatically run against each code commit in a repository. The Checks API reports detailed information about each check on GitHub in the pull request's **Checks** tab. With the Checks API, you can create annotations with additional details for specific lines of code. Annotations are visible in the **Checks** tab. When you create an annotation for a file that is part of the pull request, the annotations are also shown in the **Files changed** tab. The [Checks API](/rest/reference/checks) allows you to set up CI tests that are automatically run against each code commit in a repository. The Checks API reports detailed information about each check on GitHub in the pull request's **Checks** tab. With the Checks API, you can create annotations with additional details for specific lines of code. Annotations are visible in the **Checks** tab. When you create an annotation for a file that is part of the pull request, the annotations are also shown in the **Files changed** tab.
A _check suite_ is a group of _check runs_ (individual CI tests). Both the suite and the runs contain _statuses_ that are visible in a pull request on GitHub. You can use statuses to determine when a code commit introduces errors. Using these statuses with [protected branches](/v3/repos/branches/) can prevent people from merging pull requests prematurely. See "[Enabling required status checks](/articles/enabling-required-status-checks/)" for more details. A _check suite_ is a group of _check runs_ (individual CI tests). Both the suite and the runs contain _statuses_ that are visible in a pull request on GitHub. You can use statuses to determine when a code commit introduces errors. Using these statuses with [protected branches](/rest/reference/repos#branches) can prevent people from merging pull requests prematurely. See "[Enabling required status checks](/articles/enabling-required-status-checks/)" for more details.
The Checks API sends the [`check_suite` webhook event](/webhooks/event-payloads/#check_suite) to all GitHub Apps installed on a repository each time new code is pushed to the repository. To receive all Checks API event actions, the app must have the `checks:write` permission. GitHub automatically creates `check_suite` events for new code commits in a repository using the default flow, although [Update repository preferences for check suites](/v3/checks/suites/#update-repository-preferences-for-check-suites) if you'd like. Here's how the default flow works: The Checks API sends the [`check_suite` webhook event](/webhooks/event-payloads/#check_suite) to all GitHub Apps installed on a repository each time new code is pushed to the repository. To receive all Checks API event actions, the app must have the `checks:write` permission. GitHub automatically creates `check_suite` events for new code commits in a repository using the default flow, although [Update repository preferences for check suites](/rest/reference/checks#update-repository-preferences-for-check-suites) if you'd like. Here's how the default flow works:
1. Whenever someone pushes code to the repository, GitHub sends the `check_suite` event with an action of `requested` to all GitHub Apps installed on the repository that have the `checks:write` permission. This event lets the apps know that code was pushed and that GitHub has automatically created a new check suite. 1. Whenever someone pushes code to the repository, GitHub sends the `check_suite` event with an action of `requested` to all GitHub Apps installed on the repository that have the `checks:write` permission. This event lets the apps know that code was pushed and that GitHub has automatically created a new check suite.
1. When your app receives this event, it can [add check runs](/v3/checks/runs/#create-a-check-run) to that suite. 1. When your app receives this event, it can [add check runs](/rest/reference/checks#create-a-check-run) to that suite.
1. Your check runs can include [annotations](/v3/checks/runs/#annotations-object) that are displayed on specific lines of code. 1. Your check runs can include [annotations](/rest/reference/checks#annotations-object) that are displayed on specific lines of code.
**In this guide, you’ll learn how to:** **In this guide, you’ll learn how to:**
@@ -49,7 +49,7 @@ To get an idea of what your Checks API CI server will do when you've completed t
### Prerequisites ### Prerequisites
Before you get started, you may want to familiarize yourself with [Github Apps](/apps/), [Webhooks](/webhooks), and the [Checks API](/v3/checks/), if you're not already. You'll find more APIs in the [REST API docs](/v3/). The Checks API is also available to use in [GraphQL](/v4/), but this quickstart focuses on REST. See the GraphQL [Checks Suite](/v4/object/checksuite/) and [Check Run](/v4/object/checkrun/) objects for more details. Before you get started, you may want to familiarize yourself with [Github Apps](/apps/), [Webhooks](/webhooks), and the [Checks API](/rest/reference/checks), if you're not already. You'll find more APIs in the [REST API docs](/rest). The Checks API is also available to use in [GraphQL](/graphql), but this quickstart focuses on REST. See the GraphQL [Checks Suite](/graphql/reference/objects#checksuite) and [Check Run](/graphql/reference/objects#checkrun) objects for more details.
You'll use the [Ruby programming language](https://www.ruby-lang.org/en/), the [Smee](https://smee.io/) webhook payload delivery service, the [Octokit.rb Ruby library](http://octokit.github.io/octokit.rb/) for the GitHub REST API, and the [Sinatra web framework](http://sinatrarb.com/) to create your Checks API CI server app. You'll use the [Ruby programming language](https://www.ruby-lang.org/en/), the [Smee](https://smee.io/) webhook payload delivery service, the [Octokit.rb Ruby library](http://octokit.github.io/octokit.rb/) for the GitHub REST API, and the [Sinatra web framework](http://sinatrarb.com/) to create your Checks API CI server app.
@@ -140,7 +140,7 @@ You'll add this new method as a [Sinatra helper](https://github.com/sinatra/sina
def create_check_run def create_check_run
# # At the time of writing, Octokit does not support the Checks API yet, but # # At the time of writing, Octokit does not support the Checks API yet, but
# it does provide generic HTTP methods you can use: # it does provide generic HTTP methods you can use:
# /v3/checks/runs/#create-a-check-run # /rest/reference/checks#create-a-check-run
check_run = @installation_client.post( check_run = @installation_client.post(
"repos/#{@payload['repository']['full_name']}/check-runs", "repos/#{@payload['repository']['full_name']}/check-runs",
{ {
@@ -159,7 +159,7 @@ end
def create_check_run def create_check_run
# # At the time of writing, Octokit does not support the Checks API yet, but # # At the time of writing, Octokit does not support the Checks API yet, but
# it does provide generic HTTP methods you can use: # it does provide generic HTTP methods you can use:
# /v3/checks/runs/#create-a-check-run # /rest/reference/checks#create-a-check-run
check_run = @installation_client.post( check_run = @installation_client.post(
"repos/#{@payload['repository']['full_name']}/check-runs", "repos/#{@payload['repository']['full_name']}/check-runs",
{ {
@@ -175,7 +175,7 @@ end
``` ```
{% endif %} {% endif %}
This code calls the "[Create a check run](/v3/checks/runs/#create-a-check-run)" endpoint using the generic [HTTP `POST` method](http://octokit.github.io/octokit.rb/Octokit/Connection.html#post-instance_method). This method takes two parameters: the URL of the endpoint and the input parameters to the method. This code calls the "[Create a check run](/rest/reference/checks#create-a-check-run)" endpoint using the generic [HTTP `POST` method](http://octokit.github.io/octokit.rb/Octokit/Connection.html#post-instance_method). This method takes two parameters: the URL of the endpoint and the input parameters to the method.
To create a check run, only two input parameters are required: `name` and `head_sha`. We will use [Rubocop](https://rubocop.readthedocs.io/en/latest/) to implement the CI test later in this quickstart, which is why the name "Octo Rubocop" is used here, but you can choose any name you'd like for the check run. To create a check run, only two input parameters are required: `name` and `head_sha`. We will use [Rubocop](https://rubocop.readthedocs.io/en/latest/) to implement the CI test later in this quickstart, which is why the name "Octo Rubocop" is used here, but you can choose any name you'd like for the check run.
@@ -240,7 +240,7 @@ def initiate_check_run
# Octokit doesn't yet support the Checks API, but it does provide generic # Octokit doesn't yet support the Checks API, but it does provide generic
# HTTP methods you can use: # HTTP methods you can use:
# /v3/checks/runs/#update-a-check-run # /rest/reference/checks#update-a-check-run
updated_check_run = @installation_client.patch( updated_check_run = @installation_client.patch(
"repos/#{@payload['repository']['full_name']}/check-runs/#{@payload['check_run']['id']}", "repos/#{@payload['repository']['full_name']}/check-runs/#{@payload['check_run']['id']}",
{ {
@@ -276,7 +276,7 @@ def initiate_check_run
# Octokit doesn't yet support the Checks API, but it does provide generic # Octokit doesn't yet support the Checks API, but it does provide generic
# HTTP methods you can use: # HTTP methods you can use:
# /v3/checks/runs/#update-a-check-run # /rest/reference/checks#update-a-check-run
updated_check_run = @installation_client.patch( updated_check_run = @installation_client.patch(
"repos/#{@payload['repository']['full_name']}/check-runs/#{@payload['check_run']['id']}", "repos/#{@payload['repository']['full_name']}/check-runs/#{@payload['check_run']['id']}",
{ {
@@ -305,11 +305,11 @@ end
``` ```
{% endif %} {% endif %}
The code above calls the "[Update a check run](/v3/checks/runs/#update-a-check-run)" API endpoint using the generic [`patch` HTTP method](http://octokit.github.io/octokit.rb/Octokit/Connection.html#patch-instance_method) to update the check run that you already created. The code above calls the "[Update a check run](/rest/reference/checks#update-a-check-run)" API endpoint using the generic [`patch` HTTP method](http://octokit.github.io/octokit.rb/Octokit/Connection.html#patch-instance_method) to update the check run that you already created.
Here's what this code is doing. First, it updates the check run's status to `in_progress` and sets the `started_at` time to the current time. In [Part 2](#part-2-creating-the-octo-rubocop-ci-test) of this quickstart, you'll add code that kicks off a real CI test under `***** RUN A CI TEST *****`. For now, you'll leave that section as a placeholder, so the code that follows it will just simulate that the CI process succeeds and all tests pass. Finally, the code updates the status of the check run again to `completed`. Here's what this code is doing. First, it updates the check run's status to `in_progress` and sets the `started_at` time to the current time. In [Part 2](#part-2-creating-the-octo-rubocop-ci-test) of this quickstart, you'll add code that kicks off a real CI test under `***** RUN A CI TEST *****`. For now, you'll leave that section as a placeholder, so the code that follows it will just simulate that the CI process succeeds and all tests pass. Finally, the code updates the status of the check run again to `completed`.
You'll notice in the "[Update a check run](/v3/checks/runs/#update-a-check-run)" docs that when you provide a status of `completed`, the `conclusion` and `completed_at` parameters are required. The `conclusion` summarizes the outcome of a check run and can be `success`, `failure`, `neutral`, `cancelled`, `timed_out`, or `action_required`. You'll set the conclusion to `success`, the `completed_at` time to the current time, and the status to `completed`. You'll notice in the "[Update a check run](/rest/reference/checks#update-a-check-run)" docs that when you provide a status of `completed`, the `conclusion` and `completed_at` parameters are required. The `conclusion` summarizes the outcome of a check run and can be `success`, `failure`, `neutral`, `cancelled`, `timed_out`, or `action_required`. You'll set the conclusion to `success`, the `completed_at` time to the current time, and the status to `completed`.
You could also provide more details about what your check is doing, but you'll get to that in the next section. Let's test this code again by re-running `template_server.rb`: You could also provide more details about what your check is doing, but you'll get to that in the next section. Let's test this code again by re-running `template_server.rb`:
@@ -435,7 +435,7 @@ The code above gets the full repository name and the head SHA of the commit from
### Step 2.3. Running RuboCop ### Step 2.3. Running RuboCop
Great! You're cloning the repository and creating check runs using your CI server. Now you'll get into the nitty gritty details of the [RuboCop linter](https://rubocop.readthedocs.io/en/latest/basic_usage/#rubocop-as-a-code-style-checker) and [Checks API annotations](/v3/checks/runs/#create-a-check-run). Great! You're cloning the repository and creating check runs using your CI server. Now you'll get into the nitty gritty details of the [RuboCop linter](https://rubocop.readthedocs.io/en/latest/basic_usage/#rubocop-as-a-code-style-checker) and [Checks API annotations](/rest/reference/checks#create-a-check-run).
The following code runs RuboCop and saves the style code errors in JSON format. Add this code below the call to `clone_repository` you added in the [previous step](#step-22-cloning-the-repository) and above the code that updates the check run to complete. The following code runs RuboCop and saves the style code errors in JSON format. Add this code below the call to `clone_repository` you added in the [previous step](#step-22-cloning-the-repository) and above the code that updates the check run to complete.
@@ -523,11 +523,11 @@ You should see the linting errors in the debug output, although they aren't prin
The `@output` variable contains the parsed JSON results of the RuboCop report. As shown above, the results contain a `summary` section that your code can use to quickly determine if there are any errors. The following code will set the check run conclusion to `success` when there are no reported errors. RuboCop reports errors for each file in the `files` array, so if there are errors, you'll need to extract some data from the file object. The `@output` variable contains the parsed JSON results of the RuboCop report. As shown above, the results contain a `summary` section that your code can use to quickly determine if there are any errors. The following code will set the check run conclusion to `success` when there are no reported errors. RuboCop reports errors for each file in the `files` array, so if there are errors, you'll need to extract some data from the file object.
The Checks API allows you to create annotations for specific lines of code. When you create or update a check run, you can add annotations. In this quickstart you are [updating the check run](/v3/checks/runs/#update-a-check-run) with annotations. The Checks API allows you to create annotations for specific lines of code. When you create or update a check run, you can add annotations. In this quickstart you are [updating the check run](/rest/reference/checks#update-a-check-run) with annotations.
The Checks API limits the number of annotations to a maximum of 50 per API request. To create more than 50 annotations, you have to make multiple requests to the [Update a check run](/v3/checks/runs/#update-a-check-run) endpoint. For example, to create 105 annotations you'd need to call the [Update a check run](/v3/checks/runs/#update-a-check-run) endpoint three times. The first two requests would each have 50 annotations, and the third request would include the five remaining annotations. Each time you update the check run, annotations are appended to the list of annotations that already exist for the check run. The Checks API limits the number of annotations to a maximum of 50 per API request. To create more than 50 annotations, you have to make multiple requests to the [Update a check run](/rest/reference/checks#update-a-check-run) endpoint. For example, to create 105 annotations you'd need to call the [Update a check run](/rest/reference/checks#update-a-check-run) endpoint three times. The first two requests would each have 50 annotations, and the third request would include the five remaining annotations. Each time you update the check run, annotations are appended to the list of annotations that already exist for the check run.
A check run expects annotations as an array of objects. Each annotation object must include the `path`, `start_line`, `end_line`, `annotation_level`, and `message`. RuboCop provides the `start_column` and `end_column` too, so you can include those optional parameters in the annotation. Annotations only support `start_column` and `end_column` on the same line. See the [`annotations` object](/v3/checks/runs/#annotations-object-1) reference documentation for details. A check run expects annotations as an array of objects. Each annotation object must include the `path`, `start_line`, `end_line`, `annotation_level`, and `message`. RuboCop provides the `start_column` and `end_column` too, so you can include those optional parameters in the annotation. Annotations only support `start_column` and `end_column` on the same line. See the [`annotations` object](/rest/reference/checks#annotations-object-1) reference documentation for details.
You'll extract the required information from RuboCop needed to create each annotation. Append the following code to the code you added in the [previous section](#step-23-running-rubocop): You'll extract the required information from RuboCop needed to create each annotation. Append the following code to the code you added in the [previous section](#step-23-running-rubocop):
@@ -536,7 +536,7 @@ annotations = []
# You can create a maximum of 50 annotations per request to the Checks # You can create a maximum of 50 annotations per request to the Checks
# API. To add more than 50 annotations, use the "Update a check run" API # API. To add more than 50 annotations, use the "Update a check run" API
# endpoint. This example code limits the number of annotations to 50. # endpoint. This example code limits the number of annotations to 50.
# See /v3/checks/runs/#update-a-check-run # See /rest/reference/checks#update-a-check-run
# for details. # for details.
max_annotations = 50 max_annotations = 50
@@ -869,4 +869,4 @@ After walking through this guide, you've learned the basics of using the Checks
Here are some ideas for what you can do next: Here are some ideas for what you can do next:
* Currently, the "Fix this" button is always displayed. Update the code you wrote to display the "Fix this" button only when RuboCop finds errors. * Currently, the "Fix this" button is always displayed. Update the code you wrote to display the "Fix this" button only when RuboCop finds errors.
* If you'd prefer that RuboCop doesn't commit files directly to the head branch, you can update the code to [create a pull request](/v3/pulls/#create-a-pull-request) with a new branch based on the head branch. * If you'd prefer that RuboCop doesn't commit files directly to the head branch, you can update the code to [create a pull request](/rest/reference/pulls#create-a-pull-request) with a new branch based on the head branch.

2
content/developers/apps/differences-between-github-apps-and-oauth-apps.md
View File

@@ -92,7 +92,7 @@ Unlike OAuth apps, GitHub Apps have targeted permissions that allow them to requ
| GitHub Apps | OAuth Apps | | GitHub Apps | OAuth Apps |
| ----- | ----------- | | ----- | ----------- |
| GitHub Apps ask for repository contents permission and use your installation token to authenticate via [HTTP-based Git](/apps/building-github-apps/authenticating-with-github-apps/#http-based-git-access-by-an-installation). | OAuth Apps ask for `write:public_key` scope and [Create a deploy key](/v3/repos/keys/#create-a-deploy-key) via the API. You can then use that key to perform Git commands. | | GitHub Apps ask for repository contents permission and use your installation token to authenticate via [HTTP-based Git](/apps/building-github-apps/authenticating-with-github-apps/#http-based-git-access-by-an-installation). | OAuth Apps ask for `write:public_key` scope and [Create a deploy key](/rest/reference/repos#create-a-deploy-key) via the API. You can then use that key to perform Git commands. |
| The token is used as the HTTP password. | The token is used as the HTTP username. | | The token is used as the HTTP password. | The token is used as the HTTP username. |
### Machine vs. bot accounts ### Machine vs. bot accounts

828
content/developers/apps/identifying-and-authorizing-users-for-github-apps.md
View File

File diff suppressed because it is too large Load Diff

12
content/developers/apps/migrating-oauth-apps-to-github-apps.md
View File

@@ -23,7 +23,7 @@ This article provides guidelines for existing integrators who are considering mi
- Built-in support for OAuth is still available to GitHub Apps using [user-to-server endpoints](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/). - Built-in support for OAuth is still available to GitHub Apps using [user-to-server endpoints](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/).
- Dedicated [API rate limits](/apps/building-github-apps/understanding-rate-limits-for-github-apps/) for bot accounts scale with your integration. - Dedicated [API rate limits](/apps/building-github-apps/understanding-rate-limits-for-github-apps/) for bot accounts scale with your integration.
- Repository owners can [install GitHub Apps](/apps/differences-between-apps/#who-can-install-github-apps-and-authorize-oauth-apps) on organization repositories. If a GitHub App's configuration has permissions that request an organization's resources, the org owner must approve the installation. - Repository owners can [install GitHub Apps](/apps/differences-between-apps/#who-can-install-github-apps-and-authorize-oauth-apps) on organization repositories. If a GitHub App's configuration has permissions that request an organization's resources, the org owner must approve the installation.
- Open Source community support is available through [Octokit libraries](/v3/libraries/) and other frameworks such as [Probot](https://probot.github.io/). - Open Source community support is available through [Octokit libraries](/rest/overview/libraries) and other frameworks such as [Probot](https://probot.github.io/).
- Integrators building GitHub Apps have opportunities to adopt earlier access to APIs. - Integrators building GitHub Apps have opportunities to adopt earlier access to APIs.
### Converting an OAuth App to a GitHub App ### Converting an OAuth App to a GitHub App
@@ -42,13 +42,13 @@ These guidelines assume that you have a registered OAuth App{% if currentVersion
#### Review the available API endpoints for GitHub Apps #### Review the available API endpoints for GitHub Apps
While the majority of [REST API](/v3) endpoints and [GraphQL](/v4) queries are available to GitHub Apps today, we are still in the process of enabling some endpoints. Review the [available REST endpoints](/v3/apps/available-endpoints/) to ensure that the endpoints you need are compatible with GitHub Apps. Note that some of the API endpoints enabled for GitHub Apps allow the app to act on behalf of the user. See "[User-to-server requests](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/#user-to-server-requests)" for a list of endpoints that allow a GitHub App to authenticate as a user. While the majority of [REST API](/rest) endpoints and [GraphQL](/graphql) queries are available to GitHub Apps today, we are still in the process of enabling some endpoints. Review the [available REST endpoints](/rest/overview/endpoints-available-for-github-apps) to ensure that the endpoints you need are compatible with GitHub Apps. Note that some of the API endpoints enabled for GitHub Apps allow the app to act on behalf of the user. See "[User-to-server requests](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/#user-to-server-requests)" for a list of endpoints that allow a GitHub App to authenticate as a user.
We recommend reviewing the list of API endpoints you need as early as possible. Please let Support know if there is an endpoint you require that is not yet enabled for {% data variables.product.prodname_github_app %}s. We recommend reviewing the list of API endpoints you need as early as possible. Please let Support know if there is an endpoint you require that is not yet enabled for {% data variables.product.prodname_github_app %}s.
#### Design to stay within API rate limits #### Design to stay within API rate limits
GitHub Apps use [sliding rules for rate limits](/apps/building-github-apps/understanding-rate-limits-for-github-apps/), which can increase based on the number of repositories and users in the organization. A GitHub App can also make use of [conditional requests](/v3/#conditional-requests) or consolidate requests by using the [GraphQL API V4](/v4/). GitHub Apps use [sliding rules for rate limits](/apps/building-github-apps/understanding-rate-limits-for-github-apps/), which can increase based on the number of repositories and users in the organization. A GitHub App can also make use of [conditional requests](/rest#conditional-requests) or consolidate requests by using the [GraphQL API V4](/graphql).
#### Register a new GitHub App #### Register a new GitHub App
@@ -56,7 +56,7 @@ Once you've decided to make the switch to Github Apps, you'll need to [create a
#### Determine the permissions your app requires #### Determine the permissions your app requires
When registering your GitHub App, you'll need to select the permissions required by each endpoint used in your app's code. See "[GitHub App permissions](/v3/apps/permissions/)" for a list of the permissions needed for each endpoint available to GitHub Apps. When registering your GitHub App, you'll need to select the permissions required by each endpoint used in your app's code. See "[GitHub App permissions](/rest/reference/permissions-required-for-github-apps)" for a list of the permissions needed for each endpoint available to GitHub Apps.
In your GitHub App's settings, you can specify whether your app needs `No Access`, `Read-only`, or `Read & Write` access for each permission type. The fine-grained permissions allow your app to gain targeted access to the subset of data you need. We recommend specifying the smallest set of permissions possible that provides the desired functionality. In your GitHub App's settings, you can specify whether your app needs `No Access`, `Read-only`, or `Read & Write` access for each permission type. The fine-grained permissions allow your app to gain targeted access to the subset of data you need. We recommend specifying the smallest set of permissions possible that provides the desired functionality.
@@ -90,11 +90,11 @@ Once you've made the transition from an OAuth App to a GitHub App, you will need
https://github.com/apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID https://github.com/apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID
``` ```
You'll need to replace `YOUR_APP_NAME` with the name of your GitHub App, `ID_OF_USER_OR_ORG` with the ID of your target user or organization, and include up to 100 repository IDs (`REPO_A_ID` and `REPO_B_ID`). To get a list of repositories your OAuth App has access to, use the [List repositories for the authenticated user](/v3/repos/#list-repositories-for-the-authenticated-user) and [List organization repositories](/v3/repos/#list-organization-repositories) endpoints. You'll need to replace `YOUR_APP_NAME` with the name of your GitHub App, `ID_OF_USER_OR_ORG` with the ID of your target user or organization, and include up to 100 repository IDs (`REPO_A_ID` and `REPO_B_ID`). To get a list of repositories your OAuth App has access to, use the [List repositories for the authenticated user](/rest/reference/repos#list-repositories-for-the-authenticated-user) and [List organization repositories](/rest/reference/repos#list-organization-repositories) endpoints.
#### Remove any unnecessary repository hooks #### Remove any unnecessary repository hooks
Once your GitHub App has been installed on a repository, you should remove any unnecessary webhooks that were created by your legacy OAuth App. If both apps are installed on a repository, they may duplicate functionality for the user. To remove webhooks, you can listen for the [`installation_repositories` webhook](/webhooks/event-payloads/#installation_repositories) with the `repositories_added` action and [Delete a repository webhook](/v3/repos/hooks/#delete-a-repository-webhook) on those repositories that were created by your OAuth App. Once your GitHub App has been installed on a repository, you should remove any unnecessary webhooks that were created by your legacy OAuth App. If both apps are installed on a repository, they may duplicate functionality for the user. To remove webhooks, you can listen for the [`installation_repositories` webhook](/webhooks/event-payloads/#installation_repositories) with the `repositories_added` action and [Delete a repository webhook](/rest/reference/repos#delete-a-repository-webhook) on those repositories that were created by your OAuth App.
#### Encourage users to revoke access to your OAuth app #### Encourage users to revoke access to your OAuth app

2
content/developers/apps/refreshing-user-to-server-access-tokens.md
View File

@@ -25,7 +25,7 @@ To renew an expiring user-to-server access token, you can exchange the `refresh_
`POST https://github.com/login/oauth/access_token` `POST https://github.com/login/oauth/access_token`
This callback request will send you a new access token and a new refresh token. This callback request is similar to the OAuth request you would use to exchange a temporary `code` for an access token. For more information, see "[Identifying and authorizing users for GitHub Apps](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/#2-users-are-redirected-back-to-your-site-by-github)" and "[Basics of authentication](/v3/guides/basics-of-authentication/#providing-a-callback)." This callback request will send you a new access token and a new refresh token. This callback request is similar to the OAuth request you would use to exchange a temporary `code` for an access token. For more information, see "[Identifying and authorizing users for GitHub Apps](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/#2-users-are-redirected-back-to-your-site-by-github)" and "[Basics of authentication](/rest/guides/basics-of-authentication#providing-a-callback)."
#### Parameters #### Parameters

6
content/developers/apps/scopes-for-oauth-apps.md
View File

@@ -40,13 +40,13 @@ X-Accepted-OAuth-Scopes: user
Name | Description Name | Description
-----|-----------| -----|-----------|
**`(no scope)`** | Grants read-only access to public information (includes public user profile info, public repository info, and gists){% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %} **`(no scope)`** | Grants read-only access to public information (includes public user profile info, public repository info, and gists){% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %}
**`site_admin`** | Grants site administrators access to [{% data variables.product.prodname_ghe_server %} Administration API endpoints](/v3/enterprise-admin).{% endif %} **`site_admin`** | Grants site administrators access to [{% data variables.product.prodname_ghe_server %} Administration API endpoints](/rest/reference/enterprise-admin).{% endif %}
**`repo`** | Grants full access to private and public repositories. That includes read/write access to code, commit statuses, repository and organization projects, invitations, collaborators, adding team memberships, deployment statuses, and repository webhooks for public and private repositories and organizations. Also grants ability to manage user projects. **`repo`** | Grants full access to private and public repositories. That includes read/write access to code, commit statuses, repository and organization projects, invitations, collaborators, adding team memberships, deployment statuses, and repository webhooks for public and private repositories and organizations. Also grants ability to manage user projects.
&emsp;`repo:status`| Grants read/write access to public and private repository commit statuses. This scope is only necessary to grant other users or services access to private repository commit statuses *without* granting access to the code. &emsp;`repo:status`| Grants read/write access to public and private repository commit statuses. This scope is only necessary to grant other users or services access to private repository commit statuses *without* granting access to the code.
&emsp;`repo_deployment`| Grants access to [deployment statuses](/v3/repos/deployments) for public and private repositories. This scope is only necessary to grant other users or services access to deployment statuses, *without* granting access to the code. &emsp;`repo_deployment`| Grants access to [deployment statuses](/rest/reference/repos#deployments) for public and private repositories. This scope is only necessary to grant other users or services access to deployment statuses, *without* granting access to the code.
&emsp;`public_repo`| Limits access to public repositories. That includes read/write access to code, commit statuses, repository projects, collaborators, and deployment statuses for public repositories and organizations. Also required for starring public repositories. &emsp;`public_repo`| Limits access to public repositories. That includes read/write access to code, commit statuses, repository projects, collaborators, and deployment statuses for public repositories and organizations. Also required for starring public repositories.
&emsp;`repo:invite` | Grants accept/decline abilities for invitations to collaborate on a repository. This scope is only necessary to grant other users or services access to invites *without* granting access to the code.{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" or currentVersion == "github-ae@latest"%} &emsp;`repo:invite` | Grants accept/decline abilities for invitations to collaborate on a repository. This scope is only necessary to grant other users or services access to invites *without* granting access to the code.{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" or currentVersion == "github-ae@latest"%}
&emsp;`security_events` | Grants read and write access to security events in the [{% data variables.product.prodname_code_scanning %} API](/v3/code-scanning).{% endif %} &emsp;`security_events` | Grants read and write access to security events in the [{% data variables.product.prodname_code_scanning %} API](/rest/reference/code-scanning).{% endif %}
**`admin:repo_hook`** | Grants read, write, ping, and delete access to repository hooks in public and private repositories. The `repo` and `public_repo` scopes grants full access to repositories, including repository hooks. Use the `admin:repo_hook` scope to limit access to only repository hooks. **`admin:repo_hook`** | Grants read, write, ping, and delete access to repository hooks in public and private repositories. The `repo` and `public_repo` scopes grants full access to repositories, including repository hooks. Use the `admin:repo_hook` scope to limit access to only repository hooks.
&emsp;`write:repo_hook` | Grants read, write, and ping access to hooks in public or private repositories. &emsp;`write:repo_hook` | Grants read, write, and ping access to hooks in public or private repositories.
&emsp;`read:repo_hook`| Grants read and ping access to hooks in public or private repositories. &emsp;`read:repo_hook`| Grants read and ping access to hooks in public or private repositories.

2
content/developers/apps/setting-permissions-for-github-apps.md
View File

@@ -17,4 +17,4 @@ When you create a GitHub App, you can select the permissions it needs to access
By default, GitHub Apps have `Read-only` access to metadata endpoints. Metadata is a collection of read-only endpoints that provide general information about resources that the authorized installation can access. By default, GitHub Apps have `Read-only` access to metadata endpoints. Metadata is a collection of read-only endpoints that provide general information about resources that the authorized installation can access.
{% data reusables.apps.metadata-permissions %} For a list of metadata endpoints, see "[Metadata permissions](/v3/apps/permissions/#metadata-permissions)." {% data reusables.apps.metadata-permissions %} For a list of metadata endpoints, see "[Metadata permissions](/rest/reference/permissions-required-for-github-apps#metadata-permissions)."

6
content/developers/apps/setting-up-your-development-environment-to-create-a-github-app.md
View File

@@ -37,7 +37,7 @@ You may find it helpful to have a basic understanding of the following:
* [GitHub Apps](/apps/about-apps) * [GitHub Apps](/apps/about-apps)
* [Webhooks](/webhooks) * [Webhooks](/webhooks)
* [The Ruby programming language](https://www.ruby-lang.org/en/) * [The Ruby programming language](https://www.ruby-lang.org/en/)
* [REST APIs](/v3) * [REST APIs](/rest)
* [Sinatra](http://sinatrarb.com/) * [Sinatra](http://sinatrarb.com/)
But you can follow along at any experience level. We'll link out to information you need along the way! But you can follow along at any experience level. We'll link out to information you need along the way!
@@ -220,7 +220,7 @@ end
#### Define a route handler #### Define a route handler
An empty route is included in the template code. This code handles all `POST` requests to the `/event_handler` route. You'll won't write this event handler in this quickstart, but see the other [quickstart guides](/apps/quickstart-guides/) for examples of how to extend this template app. An empty route is included in the template code. This code handles all `POST` requests to the `/event_handler` route. You won't write this event handler in this quickstart, but see the other [quickstart guides](/apps/quickstart-guides/) for examples of how to extend this template app.
``` ruby ``` ruby
post '/event_handler' do post '/event_handler' do
@@ -422,7 +422,7 @@ Here are a few common problems and some suggested solutions. If you run into any
**A:** You may not be running the Smee client, or you may not have the correct Smee domain in your GitHub App settings. First check to make sure the Smee client is running in a Terminal tab. If that's not the problem, visit your [app settings page](https://github.com/settings/apps) and check the fields shown in "[Step 2. Register a new GitHub App](#step-2-register-a-new-github-app)." Make sure the domain in those fields matches the domain you used in your `smee -u <unique_channel>` command in "[Step 1. Start a new Smee channel](#step-1-start-a-new-smee-channel)." **A:** You may not be running the Smee client, or you may not have the correct Smee domain in your GitHub App settings. First check to make sure the Smee client is running in a Terminal tab. If that's not the problem, visit your [app settings page](https://github.com/settings/apps) and check the fields shown in "[Step 2. Register a new GitHub App](#step-2-register-a-new-github-app)." Make sure the domain in those fields matches the domain you used in your `smee -u <unique_channel>` command in "[Step 1. Start a new Smee channel](#step-1-start-a-new-smee-channel)."
* **Q:** I'm getting seeing an `Octokit::NotFound` 404 error in my debug output: * **Q:** I'm getting an `Octokit::NotFound` 404 error in my debug output:
``` ```
2018-12-06 15:00:56 - Octokit::NotFound - POST https://api.github.com/app/installations/500991/access_tokens: 404 - Not Found // See: /v3/apps/#create-a-new-installation-token: 2018-12-06 15:00:56 - Octokit::NotFound - POST https://api.github.com/app/installations/500991/access_tokens: 404 - Not Found // See: /v3/apps/#create-a-new-installation-token:
``` ```

4
content/developers/apps/using-content-attachments.md
View File

@@ -55,7 +55,7 @@ The content attachment flow shows you the relationship between the URL in the is
} }
``` ```
**Step 4.** The app uses the `content_reference` `id`, to [Create a content attachment](/v3/apps/installations/#create-a-content-attachment) using the REST API. You'll also need the `installation` `id` to authenticate as a [GitHub App installation](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-an-installation). **Step 4.** The app uses the `content_reference` `id`, to [Create a content attachment](/rest/reference/apps#create-a-content-attachment) using the REST API. You'll also need the `installation` `id` to authenticate as a [GitHub App installation](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-an-installation).
{% data reusables.pre-release-program.corsair-preview %} {% data reusables.pre-release-program.corsair-preview %}
{% data reusables.pre-release-program.api-preview-warning %} {% data reusables.pre-release-program.api-preview-warning %}
@@ -116,7 +116,7 @@ curl -X "POST" "https://api.github.com/graphql" \
}' }'
``` ```
For more information on `node_id`, see "[Using Global Node IDs](/v4/guides/using-global-node-ids/)." For more information on `node_id`, see "[Using Global Node IDs](/graphql/guides/using-global-node-ids)."
### Example using Probot and GitHub App Manifests ### Example using Probot and GitHub App Manifests

6
content/developers/apps/using-the-github-api-in-your-app.md
View File

@@ -31,7 +31,7 @@ You may find it helpful to have a basic understanding of the following:
* [GitHub Apps](/apps/about-apps) * [GitHub Apps](/apps/about-apps)
* [Webhooks](/webhooks) * [Webhooks](/webhooks)
* [The Ruby programming language](https://www.ruby-lang.org/en/) * [The Ruby programming language](https://www.ruby-lang.org/en/)
* [REST APIs](/v3) * [REST APIs](/rest)
* [Sinatra](http://sinatrarb.com/) * [Sinatra](http://sinatrarb.com/)
But you can follow along at any experience level. We'll link out to information you need along the way! But you can follow along at any experience level. We'll link out to information you need along the way!
@@ -143,11 +143,11 @@ Before the label can be _added_ anywhere, you'll need to _create_ the custom lab
{% tip %} {% tip %}
**Tip**: Wouldn't it be great if your app could create the label programmatically? [It can](/v3/issues/labels/#create-a-label)! Try adding the code to do that on your own after you finish the steps in this guide. **Tip**: Wouldn't it be great if your app could create the label programmatically? [It can](/rest/reference/issues#create-a-label)! Try adding the code to do that on your own after you finish the steps in this guide.
{% endtip %} {% endtip %}
Now that the label exists, you can program your app to use the REST API to [add the label to any newly opened issue](/v3/issues/labels/#add-labels-to-an-issue). Now that the label exists, you can program your app to use the REST API to [add the label to any newly opened issue](/rest/reference/issues#add-labels-to-an-issue).
### Step 4. Add label handling ### Step 4. Add label handling

2
content/developers/github-marketplace/billing-customers.md
View File

@@ -25,7 +25,7 @@ Customers must be able to perform the following actions from your app's website:
Follow these guidelines for upgrades, downgrades, and cancellations to maintain a clear and consistent billing process. For more detailed instructions about the {% data variables.product.prodname_marketplace %} purchase events, see "[Billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows)." Follow these guidelines for upgrades, downgrades, and cancellations to maintain a clear and consistent billing process. For more detailed instructions about the {% data variables.product.prodname_marketplace %} purchase events, see "[Billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows)."
You can use the `marketplace_purchase` webhook's `effective_date` key to determine when a plan change will occur and periodically synchronize the [List accounts for a plan](/v3/apps/marketplace/#list-accounts-for-a-plan). You can use the `marketplace_purchase` webhook's `effective_date` key to determine when a plan change will occur and periodically synchronize the [List accounts for a plan](/rest/reference/apps#list-accounts-for-a-plan).
#### Upgrades #### Upgrades

4
content/developers/github-marketplace/handling-new-purchases-and-free-trials.md
View File

@@ -68,7 +68,7 @@ After the customer completes the authorization, your app receives an OAuth acces
### Step 4. Provisioning customer accounts ### Step 4. Provisioning customer accounts
Your app must provision a customer account for all new purchases. Using the access token you received for the customer in [Step 3. Authorization](#step-3-authorization), call the "[List subscriptions for the authenticated user](/v3/apps/marketplace/#list-subscriptions-for-the-authenticated-user)" endpoint. The response will include the customer's `account` information and show whether they are on a free trial (`on_free_trial`). Use this information to complete setup and provisioning. Your app must provision a customer account for all new purchases. Using the access token you received for the customer in [Step 3. Authorization](#step-3-authorization), call the "[List subscriptions for the authenticated user](/rest/reference/apps#list-subscriptions-for-the-authenticated-user)" endpoint. The response will include the customer's `account` information and show whether they are on a free trial (`on_free_trial`). Use this information to complete setup and provisioning.
{% data reusables.marketplace.marketplace-double-purchases %} {% data reusables.marketplace.marketplace-double-purchases %}
@@ -76,6 +76,6 @@ If the purchase is for an organization and per-user, you can prompt the customer
You can customize the way that organization members receive access to your app. Here are a few suggestions: You can customize the way that organization members receive access to your app. Here are a few suggestions:
**Flat-rate pricing:** If the purchase is made for an organization using flat-rate pricing, your app can [get all the organization’s members](/v3/orgs/members/#list-organization-members) via the API and prompt the organization admin to choose which members will have paid users on the integrator side. **Flat-rate pricing:** If the purchase is made for an organization using flat-rate pricing, your app can [get all the organization’s members](/rest/reference/orgs#list-organization-members) via the API and prompt the organization admin to choose which members will have paid users on the integrator side.
**Per-unit pricing:** One method of provisioning per-unit seats is to allow users to occupy a seat as they log in to the app. Once the customer hits the seat count threshold, your app can alert the user that they need to upgrade through {% data variables.product.prodname_marketplace %}. **Per-unit pricing:** One method of provisioning per-unit seats is to allow users to occupy a seat as they log in to the app. Once the customer hits the seat count threshold, your app can alert the user that they need to upgrade through {% data variables.product.prodname_marketplace %}.

2
content/developers/github-marketplace/handling-plan-cancellations.md
View File

@@ -28,6 +28,6 @@ When a customer cancels a free or paid plan, your app must perform these steps t
{% note %} {% note %}
**Note:** We recommend using the [`marketplace_purchase`](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/) webhook's `effective_date` to determine when a plan change will occur and periodically synchronizing the [List accounts for a plan](/v3/apps/marketplace/#list-accounts-for-a-plan). For more information on webhooks, see "[{% data variables.product.prodname_marketplace %} webhook events](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/)." **Note:** We recommend using the [`marketplace_purchase`](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/) webhook's `effective_date` to determine when a plan change will occur and periodically synchronizing the [List accounts for a plan](/rest/reference/apps#list-accounts-for-a-plan). For more information on webhooks, see "[{% data variables.product.prodname_marketplace %} webhook events](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/)."
{% endnote %} {% endnote %}

2
content/developers/github-marketplace/handling-plan-changes.md
View File

@@ -54,7 +54,7 @@ https://www.github.com/marketplace/<LISTING_NAME>/upgrade/<LISTING_PLAN_NUMBER>/
For example, if you notice that a customer is on a 5 person plan and needs to move to a 10 person plan, you could display a button in your app's UI that says "Here's how to upgrade" or show a banner with a link to the upgrade URL. The upgrade URL takes the customer to your listing plan's upgrade confirmation page. For example, if you notice that a customer is on a 5 person plan and needs to move to a 10 person plan, you could display a button in your app's UI that says "Here's how to upgrade" or show a banner with a link to the upgrade URL. The upgrade URL takes the customer to your listing plan's upgrade confirmation page.
Use the `LISTING_PLAN_NUMBER` for the plan the customer would like to purchase. When you create new pricing plans they receive a `LISTING_PLAN_NUMBER`, which is unique to each plan across your listing, and a `LISTING_PLAN_ID`, which is unique to each plan in the {% data variables.product.prodname_marketplace %}. You can find these numbers when you [List plans](/v3/apps/marketplace/#list-plans), which identifies your listing's pricing plans. Use the `LISTING_PLAN_ID` and the "[List accounts for a plan](/v3/apps/marketplace/#list-accounts-for-a-plan)" endpoint to get the `CUSTOMER_ACCOUNT_ID`. Use the `LISTING_PLAN_NUMBER` for the plan the customer would like to purchase. When you create new pricing plans they receive a `LISTING_PLAN_NUMBER`, which is unique to each plan across your listing, and a `LISTING_PLAN_ID`, which is unique to each plan in the {% data variables.product.prodname_marketplace %}. You can find these numbers when you [List plans](/rest/reference/apps#list-plans), which identifies your listing's pricing plans. Use the `LISTING_PLAN_ID` and the "[List accounts for a plan](/rest/reference/apps#list-accounts-for-a-plan)" endpoint to get the `CUSTOMER_ACCOUNT_ID`.
{% note %} {% note %}

10
content/developers/github-marketplace/rest-endpoints-for-the-github-marketplace-api.md
View File

@@ -13,10 +13,10 @@ versions:
Here are some useful endpoints available for Marketplace listings: Here are some useful endpoints available for Marketplace listings:
* [List plans](/v3/apps/marketplace/#list-plans) * [List plans](/rest/reference/apps#list-plans)
* [List accounts for a plan](/v3/apps/marketplace/#list-accounts-for-a-plan) * [List accounts for a plan](/rest/reference/apps#list-accounts-for-a-plan)
* [Get a subscription plan for an account](/v3/apps/marketplace/#get-a-subscription-plan-for-an-account) * [Get a subscription plan for an account](/rest/reference/apps#get-a-subscription-plan-for-an-account)
* [List subscriptions for the authenticated user](/v3/apps/marketplace/#list-subscriptions-for-the-authenticated-user) * [List subscriptions for the authenticated user](/rest/reference/apps#list-subscriptions-for-the-authenticated-user)
See these pages for details on how to authenticate when using the {% data variables.product.prodname_marketplace %} API: See these pages for details on how to authenticate when using the {% data variables.product.prodname_marketplace %} API:
@@ -25,6 +25,6 @@ See these pages for details on how to authenticate when using the {% data variab
{% note %} {% note %}
**Note:** [Rate limits for the REST API](/v3/#rate-limiting) apply to all {% data variables.product.prodname_marketplace %} API endpoints. **Note:** [Rate limits for the REST API](/rest#rate-limiting) apply to all {% data variables.product.prodname_marketplace %} API endpoints.
{% endnote %} {% endnote %}

2
content/developers/github-marketplace/testing-your-app.md
View File

@@ -37,7 +37,7 @@ Your testing scenarios may require setting up listing plans that offer free tria
### Testing APIs ### Testing APIs
For most {% data variables.product.prodname_marketplace %} API endpoints, we also provide stubbed API endpoints that return hard-coded, fake data you can use for testing. To receive stubbed data, you must specify stubbed URLs, which include `/stubbed` in the route (for example, `/user/marketplace_purchases/stubbed`). For a list of endpoints that support this stubbed-data approach, see [{% data variables.product.prodname_marketplace %} endpoints](/v3/apps/marketplace/#github-marketplace). For most {% data variables.product.prodname_marketplace %} API endpoints, we also provide stubbed API endpoints that return hard-coded, fake data you can use for testing. To receive stubbed data, you must specify stubbed URLs, which include `/stubbed` in the route (for example, `/user/marketplace_purchases/stubbed`). For a list of endpoints that support this stubbed-data approach, see [{% data variables.product.prodname_marketplace %} endpoints](/rest/reference/apps#github-marketplace).
### Testing webhooks ### Testing webhooks

2
content/developers/github-marketplace/webhook-events-for-the-github-marketplace-api.md
View File

@@ -33,7 +33,7 @@ The `marketplace_purchase` object has the following keys:
Key | Type | Description Key | Type | Description
----|------|------------- ----|------|-------------
`account` | `object` | The `organization` or `user` account associated with the subscription. Organization accounts will include `organization_billing_email`, which is the organization's administrative email address. To find email addresses for personal accounts, you can use the [Get the authenticated user](/v3/users/#get-the-authenticated-user) endpoint. `account` | `object` | The `organization` or `user` account associated with the subscription. Organization accounts will include `organization_billing_email`, which is the organization's administrative email address. To find email addresses for personal accounts, you can use the [Get the authenticated user](/rest/reference/users#get-the-authenticated-user) endpoint.
`billing_cycle` | `string` | Can be `yearly` or `monthly`. When the `account` owner has a free GitHub plan and has purchased a free {% data variables.product.prodname_marketplace %} plan, `billing_cycle` will be `nil`. `billing_cycle` | `string` | Can be `yearly` or `monthly`. When the `account` owner has a free GitHub plan and has purchased a free {% data variables.product.prodname_marketplace %} plan, `billing_cycle` will be `nil`.
`unit_count` | `integer` | Number of units purchased. `unit_count` | `integer` | Number of units purchased.
`on_free_trial` | `boolean` | `true` when the `account` is on a free trial. `on_free_trial` | `boolean` | `true` when the `account` is on a free trial.

6
content/developers/overview/about-githubs-apis.md
View File

@@ -9,11 +9,11 @@ versions:
github-ae: '*' github-ae: '*'
--- ---
There are two stable versions of the GitHub API: the [REST API](/v3/) and the [GraphQL API](/v4/). There are two stable versions of the GitHub API: the [REST API](/rest) and the [GraphQL API](/graphql).
When using the REST API, we encourage you to [request v3 via the `Accept` header](/v3/media/#request-specific-version). When using the REST API, we encourage you to [request v3 via the `Accept` header](/rest/overview/media-types#request-specific-version).
For information on using the GraphQL API, see the [v4 docs](/v4/). For information on using the GraphQL API, see the [v4 docs](/graphql).
## Deprecated versions ## Deprecated versions

2
content/developers/webhooks-and-events/about-webhooks.md
View File

@@ -31,4 +31,4 @@ See "[Webhook event payloads](/webhooks/event-payloads)" for the list of availab
For more information about the `ping` event webhook payload, see the [`ping`](/webhooks/event-payloads/#ping) event. For more information about the `ping` event webhook payload, see the [`ping`](/webhooks/event-payloads/#ping) event.
[org-hooks]: /rest/reference/orgs#webhooks/ [org-hooks]: /rest/reference/orgs#webhooks/
[repo-hooks]: /v3/repos/hooks/ [repo-hooks]: /rest/reference/repos#hooks

2
content/developers/webhooks-and-events/creating-webhooks.md
View File

@@ -65,5 +65,5 @@ When you're finished, click **Add webhook**. Phew! Now that you created the webh
To configure a webhook for all events, use the wildcard (`*`) character to specify the webhook events. When you add the wildcard event, we'll replace any existing events you have configured with the wildcard event and send you payloads for all supported events. You'll also automatically get any new events we might add in the future. To configure a webhook for all events, use the wildcard (`*`) character to specify the webhook events. When you add the wildcard event, we'll replace any existing events you have configured with the wildcard event and send you payloads for all supported events. You'll also automatically get any new events we might add in the future.
[webhooks-overview]: /webhooks/ [webhooks-overview]: /webhooks/
[webhook-api]: /v3/repos/hooks/ [webhook-api]: /rest/reference/repos#hooks
[hooks-api]: /webhooks/#events [hooks-api]: /webhooks/#events

6
content/developers/webhooks-and-events/github-event-types.md
View File

@@ -40,7 +40,7 @@ The event objects returned from the Events API endpoints have the same structure
#### Example WatchEvent event object #### Example WatchEvent event object
This example shows the format of the [WatchEvent](#watchevent) response when using the [Events API](/v3/activity/events). This example shows the format of the [WatchEvent](#watchevent) response when using the [Events API](/rest/reference/activity#events).
``` ```
Status: 200 OK Status: 200 OK
@@ -203,10 +203,10 @@ Key | Type | Description
`push_id` | `integer` | Unique identifier for the push. `push_id` | `integer` | Unique identifier for the push.
`size`|`integer` | The number of commits in the push. `size`|`integer` | The number of commits in the push.
`distinct_size`|`integer` | The number of distinct commits in the push. `distinct_size`|`integer` | The number of distinct commits in the push.
`ref`|`string` | The full [`git ref`](/v3/git/refs/) that was pushed. Example: `refs/heads/main`. `ref`|`string` | The full [`git ref`](/rest/reference/git#refs) that was pushed. Example: `refs/heads/main`.
`head`|`string` | The SHA of the most recent commit on `ref` after the push. `head`|`string` | The SHA of the most recent commit on `ref` after the push.
`before`|`string` | The SHA of the most recent commit on `ref` before the push. `before`|`string` | The SHA of the most recent commit on `ref` before the push.
`commits`|`array` | An array of commit objects describing the pushed commits. (The array includes a maximum of 20 commits. If necessary, you can use the [Commits API](/v3/repos/commits/) to fetch additional commits. This limit is applied to timeline events only and isn't applied to webhook deliveries.) `commits`|`array` | An array of commit objects describing the pushed commits. (The array includes a maximum of 20 commits. If necessary, you can use the [Commits API](/rest/reference/repos#commits) to fetch additional commits. This limit is applied to timeline events only and isn't applied to webhook deliveries.)
`commits[][sha]`|`string` | The SHA of the commit. `commits[][sha]`|`string` | The SHA of the commit.
`commits[][message]`|`string` | The commit message. `commits[][message]`|`string` | The commit message.
`commits[][author]`|`object` | The git author of the commit. `commits[][author]`|`object` | The git author of the commit.

10
content/developers/webhooks-and-events/issue-event-types.md
View File

@@ -10,7 +10,7 @@ versions:
--- ---
Issue events are triggered by activity in issues and pull requests and are available in the [Issue Events API](/v3/issues/events) and the [Timeline Events API](/v3/issues/timeline). Each event type specifies whether the event is available in the Issue Events or Timeline Events APIs. Issue events are triggered by activity in issues and pull requests and are available in the [Issue Events API](/rest/reference/issues#events) and the [Timeline Events API](/rest/reference/issues#timeline). Each event type specifies whether the event is available in the Issue Events or Timeline Events APIs.
GitHub's REST API considers every pull request to be an issue, but not every issue is a pull request. For this reason, the Issue Events and Timeline Events endpoints may return both issues and pull requests in the response. Pull requests have a `pull_request` property in the `issue` object. Because pull requests are issues, issue and pull request numbers do not overlap in a repository. For example, if you open your first issue in a repository, the number will be 1. If you then open a pull request, the number will be 2. Each event type specifies if the event occurs in pull request, issues, or both. GitHub's REST API considers every pull request to be an issue, but not every issue is a pull request. For this reason, the Issue Events and Timeline Events endpoints may return both issues and pull requests in the response. Pull requests have a `pull_request` property in the `issue` object. Because pull requests are issues, issue and pull request numbers do not overlap in a repository. For example, if you open your first issue in a repository, the number will be 1. If you then open a pull request, the number will be 2. Each event type specifies if the event occurs in pull request, issues, or both.
@@ -129,7 +129,7 @@ Name | Type | Description
`html_url` | `string` | The HTML URL of the issue comment. `html_url` | `string` | The HTML URL of the issue comment.
`issue_url` | `string` | The HTML URL of the issue. `issue_url` | `string` | The HTML URL of the issue.
`id` | `integer` | The unique identifier of the event. `id` | `integer` | The unique identifier of the event.
`node_id` | `string` | The [Global Node ID](/v4/guides/using-global-node-ids) of the event. `node_id` | `string` | The [Global Node ID](/graphql/guides/using-global-node-ids) of the event.
`user` | `object` | The person who commented on the issue. `user` | `object` | The person who commented on the issue.
`created_at` | `string` | The timestamp indicating when the comment was added. `created_at` | `string` | The timestamp indicating when the comment was added.
`updated_at` | `string` | The timestamp indicating when the comment was updated or created, if the comment is never updated. `updated_at` | `string` | The timestamp indicating when the comment was updated or created, if the comment is never updated.
@@ -155,7 +155,7 @@ A commit was added to the pull request's `HEAD` branch.
Name | Type | Description Name | Type | Description
-----|------|-------------- -----|------|--------------
`sha` | `string` | The SHA of the commit in the pull request. `sha` | `string` | The SHA of the commit in the pull request.
`node_id` | `string` | The [Global Node ID](/v4/guides/using-global-node-ids) of the event. `node_id` | `string` | The [Global Node ID](/graphql/guides/using-global-node-ids) of the event.
`url` | `string` | The REST API URL to retrieve the commit. `url` | `string` | The REST API URL to retrieve the commit.
`html_url` | `string` | The HTML URL of the commit. `html_url` | `string` | The HTML URL of the commit.
`author` | `object` | The person who authored the commit. `author` | `object` | The person who authored the commit.
@@ -163,7 +163,7 @@ Name | Type | Description
`tree` | `object` | The Git tree of the commit. `tree` | `object` | The Git tree of the commit.
`message` | `string` | The commit message. `message` | `string` | The commit message.
`parents` | `array of objects` | A list of parent commits. `parents` | `array of objects` | A list of parent commits.
`verfication` | `object` | The result of verifying the commit's signature. For more information, see "[Signature verification object](/v3/git/commits/#signature-verification-object)." `verfication` | `object` | The result of verifying the commit's signature. For more information, see "[Signature verification object](/rest/reference/git#signature-verification-object)."
`event` | `string` | The event value is `"committed"`. `event` | `string` | The event value is `"committed"`.
### connected ### connected
@@ -587,7 +587,7 @@ The pull request was reviewed.
Name | Type | Description Name | Type | Description
-----|------|-------------- -----|------|--------------
`id` | `integer` | The unique identifier of the event. `id` | `integer` | The unique identifier of the event.
`node_id` | `string` | The [Global Node ID](/v4/guides/using-global-node-ids) of the event. `node_id` | `string` | The [Global Node ID](/graphql/guides/using-global-node-ids) of the event.
`user` | `object` | The person who commented on the issue. `user` | `object` | The person who commented on the issue.
`body` | `string` | The review summary text. `body` | `string` | The review summary text.
`commit_id` | `string` | The SHA of the latest commit in the pull request at the time of the review. `commit_id` | `string` | The SHA of the latest commit in the pull request at the time of the review.

26
content/developers/webhooks-and-events/webhook-events-and-payloads.md
View File

@@ -33,7 +33,7 @@ Key | Type | Description
{% data reusables.webhooks.org_desc %} {% data reusables.webhooks.org_desc %}
{% data reusables.webhooks.app_desc %} For more information, see "[Building {% data variables.product.prodname_github_app %}](/apps/building-github-apps/)." {% data reusables.webhooks.app_desc %} For more information, see "[Building {% data variables.product.prodname_github_app %}](/apps/building-github-apps/)."
The unique properties for a webhook event are the same properties you'll find in the `payload` property when using the [Events API](/v3/activity/events/). One exception is the [`push` event](#push). The unique properties of the `push` event webhook payload and the `payload` property in the Events API differ. The webhook payload contains more detailed information. The unique properties for a webhook event are the same properties you'll find in the `payload` property when using the [Events API](/rest/reference/activity#events). One exception is the [`push` event](#push). The unique properties of the `push` event webhook payload and the `payload` property in the Events API differ. The webhook payload contains more detailed information.
{% tip %} {% tip %}
@@ -51,8 +51,8 @@ Header | Description
`X-GitHub-Delivery`| A [GUID](http://en.wikipedia.org/wiki/Globally_unique_identifier) to identify the delivery.{% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %} `X-GitHub-Delivery`| A [GUID](http://en.wikipedia.org/wiki/Globally_unique_identifier) to identify the delivery.{% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %}
`X-GitHub-Enterprise-Version` | The version of the {% data variables.product.prodname_ghe_server %} instance that sent the HTTP POST payload. `X-GitHub-Enterprise-Version` | The version of the {% data variables.product.prodname_ghe_server %} instance that sent the HTTP POST payload.
`X-GitHub-Enterprise-Host` | The hostname of the {% data variables.product.prodname_ghe_server %} instance that sent the HTTP POST payload.{% endif %}{% if currentVersion != "github-ae@latest" %} `X-GitHub-Enterprise-Host` | The hostname of the {% data variables.product.prodname_ghe_server %} instance that sent the HTTP POST payload.{% endif %}{% if currentVersion != "github-ae@latest" %}
`X-Hub-Signature`| This header is sent if the webhook is configured with a [`secret`](/v3/repos/hooks/#create-hook-config-params). This is the HMAC hex digest of the request body, and is generated using the SHA-1 hash function and the `secret` as the HMAC `key`.{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} `X-Hub-Signature` is provided for compatibility with existing integrations, and we recommend that you use the more secure `X-Hub-Signature-256` instead.{% endif %}{% endif %}{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" or currentVersion == "github-ae@latest" %} `X-Hub-Signature`| This header is sent if the webhook is configured with a [`secret`](/rest/reference/repos#create-hook-config-params). This is the HMAC hex digest of the request body, and is generated using the SHA-1 hash function and the `secret` as the HMAC `key`.{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} `X-Hub-Signature` is provided for compatibility with existing integrations, and we recommend that you use the more secure `X-Hub-Signature-256` instead.{% endif %}{% endif %}{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" or currentVersion == "github-ae@latest" %}
`X-Hub-Signature-256`| This header is sent if the webhook is configured with a [`secret`](/v3/repos/hooks/#create-hook-config-params). This is the HMAC hex digest of the request body, and is generated using the SHA-256 hash function and the `secret` as the HMAC `key`.{% endif %} `X-Hub-Signature-256`| This header is sent if the webhook is configured with a [`secret`](/rest/reference/repos#create-hook-config-params). This is the HMAC hex digest of the request body, and is generated using the SHA-256 hash function and the `secret` as the HMAC `key`.{% endif %}
Also, the `User-Agent` for the requests will have the prefix `GitHub-Hookshot/`. Also, the `User-Agent` for the requests will have the prefix `GitHub-Hookshot/`.
@@ -195,7 +195,7 @@ Also, the `User-Agent` for the requests will have the prefix `GitHub-Hookshot/`.
{% data reusables.webhooks.content_reference_short_desc %} {% data reusables.webhooks.content_reference_short_desc %}
Webhook events are triggered based on the specificity of the domain you register. For example, if you register a subdomain (`https://subdomain.example.com`) then only URLs for the subdomain trigger this event. If you register a domain (`https://example.com`) then URLs for domain and all subdomains trigger this event. See "[Create a content attachment](/v3/apps/installations/#create-a-content-attachment)" to create a new content attachment. Webhook events are triggered based on the specificity of the domain you register. For example, if you register a subdomain (`https://subdomain.example.com`) then only URLs for the subdomain trigger this event. If you register a domain (`https://example.com`) then URLs for domain and all subdomains trigger this event. See "[Create a content attachment](/rest/reference/apps#create-a-content-attachment)" to create a new content attachment.
Only {% data variables.product.prodname_github_app %}s can receive this event. {% data variables.product.prodname_github_app %}s must have the `content_references` `write` permission to subscribe to this event. Only {% data variables.product.prodname_github_app %}s can receive this event. {% data variables.product.prodname_github_app %}s must have the `content_references` `write` permission to subscribe to this event.
@@ -715,7 +715,7 @@ Key | Type | Description
### package ### package
Activity related to {% data variables.product.prodname_registry %}. {% data reusables.webhooks.action_type_desc %} For more information, see the "[blocking organization users](/v3/orgs/blocking/)" REST API. For more information, see "[Managing packages with {% data variables.product.prodname_registry %}](/github/managing-packages-with-github-packages)" to learn more about {% data variables.product.prodname_registry %}. Activity related to {% data variables.product.prodname_registry %}. {% data reusables.webhooks.action_type_desc %} For more information, see the "[blocking organization users](/rest/reference/orgs#blocking)" REST API. For more information, see "[Managing packages with {% data variables.product.prodname_registry %}](/github/managing-packages-with-github-packages)" to learn more about {% data variables.product.prodname_registry %}.
#### Availability #### Availability
@@ -775,7 +775,7 @@ Key | Type | Description
----|------|------------ ----|------|------------
`zen` | `string` | Random string of GitHub zen. `zen` | `string` | Random string of GitHub zen.
`hook_id` | `integer` | The ID of the webhook that triggered the ping. `hook_id` | `integer` | The ID of the webhook that triggered the ping.
`hook` | `object` | The [webhook configuration](/v3/repos/hooks/#get-a-repository-webhook). `hook` | `object` | The [webhook configuration](/rest/reference/repos#get-a-repository-webhook).
`hook[app_id]` | `integer` | When you register a new {% data variables.product.prodname_github_app %}, {% data variables.product.product_name %} sends a ping event to the **webhook URL** you specified during registration. The event contains the `app_id`, which is required for [authenticating](/apps/building-integrations/setting-up-and-registering-github-apps/about-authentication-options-for-github-apps/) an app. `hook[app_id]` | `integer` | When you register a new {% data variables.product.prodname_github_app %}, {% data variables.product.product_name %} sends a ping event to the **webhook URL** you specified during registration. The event contains the `app_id`, which is required for [authenticating](/apps/building-integrations/setting-up-and-registering-github-apps/about-authentication-options-for-github-apps/) an app.
{% data reusables.webhooks.repo_desc %} {% data reusables.webhooks.repo_desc %}
{% data reusables.webhooks.org_desc %} {% data reusables.webhooks.org_desc %}
@@ -970,10 +970,10 @@ Deliveries for `review_requested` and `review_request_removed` events will have
Key | Type | Description Key | Type | Description
----|------|------------- ----|------|-------------
`ref`|`string` | The full [`git ref`](/v3/git/refs/) that was pushed. Example: `refs/heads/main`. `ref`|`string` | The full [`git ref`](/rest/reference/git#refs) that was pushed. Example: `refs/heads/main`.
`before`|`string` | The SHA of the most recent commit on `ref` before the push. `before`|`string` | The SHA of the most recent commit on `ref` before the push.
`after`|`string` | The SHA of the most recent commit on `ref` after the push. `after`|`string` | The SHA of the most recent commit on `ref` after the push.
`commits`|`array` | An array of commit objects describing the pushed commits. (The array includes a maximum of 20 commits. If necessary, you can use the [Commits API](/v3/repos/commits/) to fetch additional commits. This limit is applied to timeline events only and isn't applied to webhook deliveries.) `commits`|`array` | An array of commit objects describing the pushed commits. (The array includes a maximum of 20 commits. If necessary, you can use the [Commits API](/rest/reference/repos#commits) to fetch additional commits. This limit is applied to timeline events only and isn't applied to webhook deliveries.)
`commits[][id]`|`string` | The SHA of the commit. `commits[][id]`|`string` | The SHA of the commit.
`commits[][timestamp]`|`string` | The ISO 8601 timestamp of the commit. `commits[][timestamp]`|`string` | The ISO 8601 timestamp of the commit.
`commits[][message]`|`string` | The commit message. `commits[][message]`|`string` | The commit message.
@@ -1021,7 +1021,7 @@ Key | Type | Description
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.20" or currentVersion == "github-ae@latest" %} {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.20" or currentVersion == "github-ae@latest" %}
### repository_dispatch ### repository_dispatch
This event occurs when a {% data variables.product.prodname_github_app %} sends a `POST` request to the "[Create a repository dispatch event](/v3/repos/#create-a-repository-dispatch-event)" endpoint. This event occurs when a {% data variables.product.prodname_github_app %} sends a `POST` request to the "[Create a repository dispatch event](/rest/reference/repos#create-a-repository-dispatch-event)" endpoint.
#### Availability #### Availability
@@ -1046,7 +1046,7 @@ This event occurs when a {% data variables.product.prodname_github_app %} sends
Key | Type | Description Key | Type | Description
----|------|------------- ----|------|-------------
`action` |`string` | The action that was performed. This can be one of:<ul><li>`created` - A repository is created.</li><li>`deleted` - A repository is deleted. This event type is only available to [organization hooks](/rest/reference/orgs#webhooks/)</li><li>`archived` - A repository is archived.</li><li>`unarchived` - A repository is unarchived.</li>{% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %}<li>`anonymous_access_enabled` - A repository is [enabled for anonymous Git access](/v3/previews/#anonymous-git-access-to-repositories), `anonymous_access_disabled` - A repository is [disabled for anonymous Git access](/v3/previews/#anonymous-git-access-to-repositories)</li>{% endif %}<li>`edited` - A repository's information is edited.</li><li>`renamed` - A repository is renamed.</li><li>`transferred` - A repository is transferred.</li><li>`publicized` - A repository is made public.</li><li> `privatized` - A repository is made private.</li></ul> `action` |`string` | The action that was performed. This can be one of:<ul><li>`created` - A repository is created.</li><li>`deleted` - A repository is deleted. This event type is only available to [organization hooks](/rest/reference/orgs#webhooks/)</li><li>`archived` - A repository is archived.</li><li>`unarchived` - A repository is unarchived.</li>{% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %}<li>`anonymous_access_enabled` - A repository is [enabled for anonymous Git access](/rest/overview/api-previews#anonymous-git-access-to-repositories), `anonymous_access_disabled` - A repository is [disabled for anonymous Git access](/rest/overview/api-previews#anonymous-git-access-to-repositories)</li>{% endif %}<li>`edited` - A repository's information is edited.</li><li>`renamed` - A repository is renamed.</li><li>`transferred` - A repository is transferred.</li><li>`publicized` - A repository is made public.</li><li> `privatized` - A repository is made private.</li></ul>
{% data reusables.webhooks.repo_desc %} {% data reusables.webhooks.repo_desc %}
{% data reusables.webhooks.org_desc %} {% data reusables.webhooks.org_desc %}
{% data reusables.webhooks.app_desc %} {% data reusables.webhooks.app_desc %}
@@ -1059,7 +1059,7 @@ Key | Type | Description
{% if currentVersion == "free-pro-team@latest"%} {% if currentVersion == "free-pro-team@latest"%}
### repository_import ### repository_import
{% data reusables.webhooks.repository_import_short_desc %} To receive this event for a personal repository, you must create an empty repository prior to the import. This event can be triggered using either the [GitHub Importer](/articles/importing-a-repository-with-github-importer/) or the [Source imports API](/v3/migrations/source_imports/). {% data reusables.webhooks.repository_import_short_desc %} To receive this event for a personal repository, you must create an empty repository prior to the import. This event can be triggered using either the [GitHub Importer](/articles/importing-a-repository-with-github-importer/) or the [Source imports API](/rest/reference/migrations#source-imports).
#### Availability #### Availability
@@ -1238,7 +1238,7 @@ Key | Type | Description
Key | Type | Description Key | Type | Description
----|------|------------- ----|------|-------------
`team`|`object` | The [team](/v3/teams/) that was modified. **Note:** Older events may not include this in the payload. `team`|`object` | The [team](/rest/reference/teams) that was modified. **Note:** Older events may not include this in the payload.
{% data reusables.webhooks.repo_desc %} {% data reusables.webhooks.repo_desc %}
{% data reusables.webhooks.org_desc %} {% data reusables.webhooks.org_desc %}
{% data reusables.webhooks.app_desc %} {% data reusables.webhooks.app_desc %}
@@ -1267,7 +1267,7 @@ When a user is `created` or `deleted`.
{% data reusables.webhooks.watch_short_desc %} {% data reusables.webhooks.watch_short_desc %}
The event’s actor is the [user](/v3/users/) who starred a repository, and the event’s repository is the [repository](/v3/repos/) that was starred. The event’s actor is the [user](/rest/reference/users) who starred a repository, and the event’s repository is the [repository](/rest/reference/repos) that was starred.
#### Availability #### Availability

2
content/github/administering-a-repository/about-releases.md
View File

@@ -35,7 +35,7 @@ If a release fixes a security vulnerability, you should publish a security advis
You can view the **Dependents** tab of the dependency graph to see which repositories and packages depend on code in your repository, and may therefore be affected by a new release. For more information, see "[About the dependency graph](/github/visualizing-repository-data-with-graphs/about-the-dependency-graph)." You can view the **Dependents** tab of the dependency graph to see which repositories and packages depend on code in your repository, and may therefore be affected by a new release. For more information, see "[About the dependency graph](/github/visualizing-repository-data-with-graphs/about-the-dependency-graph)."
{% endif %} {% endif %}
You can also use the Releases API to gather information, such as the number of times people download a release asset. For more information, see "[Releases](/v3/repos/releases/)." You can also use the Releases API to gather information, such as the number of times people download a release asset. For more information, see "[Releases](/rest/reference/repos#releases)."
{% if currentVersion == "free-pro-team@latest" %} {% if currentVersion == "free-pro-team@latest" %}
### Storage and bandwidth quotas ### Storage and bandwidth quotas

4
content/github/administering-a-repository/about-required-status-checks.md
View File

@@ -36,7 +36,7 @@ You can set up either loose or strict status checks, depending on whether you wa
### Troubleshooting required status checks ### Troubleshooting required status checks
If you have a check and a status with the same name and you select that name as a required status check, both the check and the status are required. For more information, see "[Checks](/v3/checks/)." If you have a check and a status with the same name and you select that name as a required status check, both the check and the status are required. For more information, see "[Checks](/rest/reference/checks)."
Once you've set up required status checks, your branch must be up to date with the base branch before merging. This ensures that your branch has been tested with the latest code from the base branch. If your branch is out of date, you'll need to merge the base branch into your branch. Once you've set up required status checks, your branch must be up to date with the base branch before merging. This ensures that your branch has been tested with the latest code from the base branch. If your branch is out of date, you'll need to merge the base branch into your branch.
@@ -62,7 +62,7 @@ remote: error: Required status check "ci-build" is failing
{% if currentVersion == "free-pro-team@latest" or currentVersion == "github-ae@latest" or currentVersion ver_gt "enterprise-server@2.20" %} {% if currentVersion == "free-pro-team@latest" or currentVersion == "github-ae@latest" or currentVersion ver_gt "enterprise-server@2.20" %}
Sometimes, the results of the status checks for the test merge commit and head commit will conflict. If the test merge commit has a status, it must pass. Otherwise, the status of the head commit must pass before you can merge the branch. For more information about test merge commits, see "[Pull Requests](/v3/pulls/#response-1)." Sometimes, the results of the status checks for the test merge commit and head commit will conflict. If the test merge commit has a status, it must pass. Otherwise, the status of the head commit must pass before you can merge the branch. For more information about test merge commits, see "[Pull Requests](/rest/reference/pulls#response-1)."
![Branch with conflicting merge commits](/assets/images/help/repository/req-status-check-conflicting-merge-commits.png) ![Branch with conflicting merge commits](/assets/images/help/repository/req-status-check-conflicting-merge-commits.png)
{% endif %} {% endif %}

4
content/github/administering-a-repository/about-secret-scanning.md
View File

@@ -20,7 +20,7 @@ Service providers can partner with {% data variables.product.company_short %} to
{% data variables.product.prodname_secret_scanning_caps %} is automatically enabled on public repositories, where it scans code for secrets, to check for known secret formats. When a match of your secret format is found in a public repository, {% data variables.product.company_short %} doesn't publicly disclose the information as an alert, but instead sends a payload to an HTTP endpoint of your choice. For an overview of how secret scanning works on public repositories, see "[Secret scanning](/developers/overview/secret-scanning)." {% data variables.product.prodname_secret_scanning_caps %} is automatically enabled on public repositories, where it scans code for secrets, to check for known secret formats. When a match of your secret format is found in a public repository, {% data variables.product.company_short %} doesn't publicly disclose the information as an alert, but instead sends a payload to an HTTP endpoint of your choice. For an overview of how secret scanning works on public repositories, see "[Secret scanning](/developers/overview/secret-scanning)."
When you push to a public repository, {% data variables.product.product_name %} scans the content of the commits for secrets. If you switch a private repository to public, {% data variables.product.product_name %} scans the entire repository for secrets. When you push to a public repository, {% data variables.product.product_name %} scans the content of the commits for secrets. If you switch a private repository to public, {% data variables.product.product_name %} scans the entire repository for secrets.
When {% data variables.product.prodname_secret_scanning %} detects a set of credentials, we notify the service provider who issued the secret. The service provider validates the credential and then decides whether they should revoke the secret, issue a new secret, or reach out to you directly, which will depend on the associated risks to you or the service provider. When {% data variables.product.prodname_secret_scanning %} detects a set of credentials, we notify the service provider who issued the secret. The service provider validates the credential and then decides whether they should revoke the secret, issue a new secret, or reach out to you directly, which will depend on the associated risks to you or the service provider.
@@ -36,6 +36,7 @@ When {% data variables.product.prodname_secret_scanning %} detects a set of cred
- Databricks - Databricks
- Datadog - Datadog
- Discord - Discord
- Doppler
- Dropbox - Dropbox
- Dynatrace - Dynatrace
- Finicity - Finicity
@@ -90,6 +91,7 @@ Repository administrators and organization owners can grant users and team acces
- CloudBees CodeShip - CloudBees CodeShip
- Databricks - Databricks
- Discord - Discord
- Doppler
- Dropbox - Dropbox
- Dynatrace - Dynatrace
- Finicity - Finicity

4
content/github/administering-a-repository/configuration-options-for-dependency-updates.md
View File

@@ -302,8 +302,8 @@ updates:
- dependency-name: "express" - dependency-name: "express"
# For Express, ignore all updates for version 4 and 5 # For Express, ignore all updates for version 4 and 5
versions: ["4.x", "5.x"] versions: ["4.x", "5.x"]
# For Loadash, ignore all updates # For Lodash, ignore all updates
- dependency-name: "loadash" - dependency-name: "lodash"
``` ```
{% note %} {% note %}

28
content/github/administering-a-repository/index.md
View File

@@ -12,36 +12,24 @@ versions:
### Table of Contents ### Table of Contents
{% topic_link_in_list /managing-repository-settings %} {% topic_link_in_list /managing-repository-settings %}
{% link_in_list /setting-repository-visibility %}{% if currentVersion == "free-pro-team@latest" %} {% link_in_list /setting-repository-visibility %}
{% link_in_list /managing-teams-and-people-with-access-to-your-repository %}{% endif %} {% link_in_list /managing-teams-and-people-with-access-to-your-repository %}
{% link_in_list /classifying-your-repository-with-topics %} {% link_in_list /classifying-your-repository-with-topics %}
{% link_in_list /customizing-how-changed-files-appear-on-github %} {% link_in_list /customizing-how-changed-files-appear-on-github %}
{% link_in_list /about-email-notifications-for-pushes-to-your-repository %} {% link_in_list /about-email-notifications-for-pushes-to-your-repository %}
<!-- if currentVersion == "free-pro-team@latest" -->
{% link_in_list /displaying-a-sponsor-button-in-your-repository %} {% link_in_list /displaying-a-sponsor-button-in-your-repository %}
<!-- endif -->
<!-- if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.17" -->
{% link_in_list /customizing-your-repositorys-social-media-preview %} {% link_in_list /customizing-your-repositorys-social-media-preview %}
<!-- endif -->
<!-- if currentVersion == "free-pro-team@latest" -->
{% link_in_list /viewing-deployment-activity-for-your-repository %} {% link_in_list /viewing-deployment-activity-for-your-repository %}
<!-- endif -->
{% link_in_list /managing-the-forking-policy-for-your-repository %} {% link_in_list /managing-the-forking-policy-for-your-repository %}
<!-- if enterpriseServerVersions contains currentVersion -->
{% link_in_list /configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-repository %} {% link_in_list /configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-repository %}
{% link_in_list /disabling-or-limiting-github-actions-for-a-repository %} {% link_in_list /disabling-or-limiting-github-actions-for-a-repository %}
{% link_in_list /managing-git-lfs-objects-in-archives-of-your-repository %} {% link_in_list /managing-git-lfs-objects-in-archives-of-your-repository %}
{% link_in_list /enabling-anonymous-git-read-access-for-a-repository %} {% link_in_list /enabling-anonymous-git-read-access-for-a-repository %}
<!-- endif -->
<!-- if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.18" -->
{% link_in_list /configuring-autolinks-to-reference-external-resources %} {% link_in_list /configuring-autolinks-to-reference-external-resources %}
<!-- endif -->
{% link_in_list /renaming-a-repository %} {% link_in_list /renaming-a-repository %}
{% link_in_list /transferring-a-repository %} {% link_in_list /transferring-a-repository %}
{% link_in_list /deleting-a-repository %} {% link_in_list /deleting-a-repository %}
<!-- if currentVersion == "free-pro-team@latest" -->
{% link_in_list /restoring-a-deleted-repository %} {% link_in_list /restoring-a-deleted-repository %}
<!-- endif -->
{% topic_link_in_list /managing-branches-in-your-repository %} {% topic_link_in_list /managing-branches-in-your-repository %}
{% link_in_list /viewing-branches-in-your-repository %} {% link_in_list /viewing-branches-in-your-repository %}
{% link_in_list /changing-the-default-branch %} {% link_in_list /changing-the-default-branch %}
@@ -50,9 +38,7 @@ versions:
{% link_in_list /about-merge-methods-on-github %} {% link_in_list /about-merge-methods-on-github %}
{% link_in_list /configuring-commit-squashing-for-pull-requests %} {% link_in_list /configuring-commit-squashing-for-pull-requests %}
{% link_in_list /configuring-commit-rebasing-for-pull-requests %} {% link_in_list /configuring-commit-rebasing-for-pull-requests %}
<!-- if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.18" -->
{% link_in_list /managing-the-automatic-deletion-of-branches %} {% link_in_list /managing-the-automatic-deletion-of-branches %}
<!-- endif -->
{% topic_link_in_list /defining-the-mergeability-of-pull-requests %} {% topic_link_in_list /defining-the-mergeability-of-pull-requests %}
{% link_in_list /about-protected-branches %} {% link_in_list /about-protected-branches %}
{% link_in_list /configuring-protected-branches %} {% link_in_list /configuring-protected-branches %}
@@ -65,31 +51,22 @@ versions:
{% link_in_list /enabling-required-reviews-for-pull-requests %} {% link_in_list /enabling-required-reviews-for-pull-requests %}
{% link_in_list /about-required-commit-signing %} {% link_in_list /about-required-commit-signing %}
{% link_in_list /enabling-required-commit-signing %} {% link_in_list /enabling-required-commit-signing %}
<!-- if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.19" -->
{% link_in_list /requiring-a-linear-commit-history %} {% link_in_list /requiring-a-linear-commit-history %}
{% link_in_list /enabling-force-pushes-to-a-protected-branch %} {% link_in_list /enabling-force-pushes-to-a-protected-branch %}
{% link_in_list /enabling-deletion-of-a-protected-branch %} {% link_in_list /enabling-deletion-of-a-protected-branch %}
<!-- endif -->
{% topic_link_in_list /releasing-projects-on-github %} {% topic_link_in_list /releasing-projects-on-github %}
{% link_in_list /about-releases %} {% link_in_list /about-releases %}
{% link_in_list /managing-releases-in-a-repository %} {% link_in_list /managing-releases-in-a-repository %}
{% link_in_list /viewing-your-repositorys-releases-and-tags %} {% link_in_list /viewing-your-repositorys-releases-and-tags %}
{% link_in_list /linking-to-releases %} {% link_in_list /linking-to-releases %}
<!-- if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.20" -->
{% link_in_list /comparing-releases %} {% link_in_list /comparing-releases %}
<!-- endif -->
<!-- if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.15" -->
{% link_in_list /automation-for-release-forms-with-query-parameters %} {% link_in_list /automation-for-release-forms-with-query-parameters %}
<!-- endif -->
<!-- if currentVersion == "free-pro-team@latest" -->
{% topic_link_in_list /securing-your-repository %} {% topic_link_in_list /securing-your-repository %}
{% link_in_list /about-securing-your-repository %} {% link_in_list /about-securing-your-repository %}
{% link_in_list /about-secret-scanning %} {% link_in_list /about-secret-scanning %}
{% link_in_list /configuring-secret-scanning-for-private-repositories %} {% link_in_list /configuring-secret-scanning-for-private-repositories %}
{% link_in_list /managing-alerts-from-secret-scanning %} {% link_in_list /managing-alerts-from-secret-scanning %}
{% link_in_list /managing-security-and-analysis-settings-for-your-repository %} {% link_in_list /managing-security-and-analysis-settings-for-your-repository %}
<!-- endif -->
<!-- if currentVersion == "free-pro-team@latest" -->
{% topic_link_in_list /keeping-your-dependencies-updated-automatically %} {% topic_link_in_list /keeping-your-dependencies-updated-automatically %}
{% link_in_list /about-dependabot-version-updates %} {% link_in_list /about-dependabot-version-updates %}
{% link_in_list /enabling-and-disabling-version-updates %} {% link_in_list /enabling-and-disabling-version-updates %}
@@ -98,4 +75,3 @@ versions:
{% link_in_list /customizing-dependency-updates %} {% link_in_list /customizing-dependency-updates %}
{% link_in_list /configuration-options-for-dependency-updates %} {% link_in_list /configuration-options-for-dependency-updates %}
{% link_in_list /keeping-your-actions-up-to-date-with-dependabot %} {% link_in_list /keeping-your-actions-up-to-date-with-dependabot %}
<!-- endif -->

5
content/github/administering-a-repository/managing-releases-in-a-repository.md
View File

@@ -15,11 +15,14 @@ versions:
github-ae: '*' github-ae: '*'
--- ---
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" or currentVersion ver_gt "github-ae@latest" %}
### About release management ### About release management
{% if currentVersion == "free-pro-team@latest" %}
You can also publish an action from a specific release in {% data variables.product.prodname_marketplace %}. For more information, see "<a href="/actions/creating-actions/publishing-actions-in-github-marketplace" class="dotcom-only">Publishing an action in the {% data variables.product.prodname_marketplace %}</a>." You can also publish an action from a specific release in {% data variables.product.prodname_marketplace %}. For more information, see "<a href="/actions/creating-actions/publishing-actions-in-github-marketplace" class="dotcom-only">Publishing an action in the {% data variables.product.prodname_marketplace %}</a>."
{% endif %}
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" or currentVersion == "github-ae@latest" %}
You can choose whether {% data variables.large_files.product_name_long %} ({% data variables.large_files.product_name_short %}) objects are included in the ZIP files and tarballs that {% data variables.product.product_name %} creates for each release. For more information, see "[Managing {% data variables.large_files.product_name_short %} objects in archives of your repository](/github/administering-a-repository/managing-git-lfs-objects-in-archives-of-your-repository)." You can choose whether {% data variables.large_files.product_name_long %} ({% data variables.large_files.product_name_short %}) objects are included in the ZIP files and tarballs that {% data variables.product.product_name %} creates for each release. For more information, see "[Managing {% data variables.large_files.product_name_short %} objects in archives of your repository](/github/administering-a-repository/managing-git-lfs-objects-in-archives-of-your-repository)."
{% endif %} {% endif %}

2
content/github/authenticating-to-github/about-githubs-ip-addresses.md
View File

@@ -11,7 +11,7 @@ redirect_from:
versions: versions:
free-pro-team: '*' free-pro-team: '*'
--- ---
You can retrieve a list of {% data variables.product.prodname_dotcom %}'s IP addresses from the [meta](https://api.github.com/meta) API endpoint. For more information, see "[Meta](/v3/meta/)." You can retrieve a list of {% data variables.product.prodname_dotcom %}'s IP addresses from the [meta](https://api.github.com/meta) API endpoint. For more information, see "[Meta](/rest/reference/meta)."
These ranges are in [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation). You can use an online conversion tool such as this [CIDR / VLSM Supernet Calculator](http://www.subnet-calculator.com/cidr.php) to convert from CIDR notation to IP address ranges. These ranges are in [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation). You can use an online conversion tool such as this [CIDR / VLSM Supernet Calculator](http://www.subnet-calculator.com/cidr.php) to convert from CIDR notation to IP address ranges.

24
content/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account.md
View File

@@ -19,13 +19,13 @@ After adding a new SSH key to your {% data variables.product.product_name %} acc
{% mac %} {% mac %}
1. Copy the SSH key to your clipboard. 1. Copy the SSH public key to your clipboard.
If your SSH key file has a different name than the example code, modify the filename to match your current setup. When copying your key, don't add any newlines or whitespace. If your SSH public key file has a different name than the example code, modify the filename to match your current setup. When copying your key, don't add any newlines or whitespace.
```shell ```shell
$ pbcopy &lt; ~/.ssh/id_rsa.pub $ pbcopy &lt; ~/.ssh/id_ed25519.pub
# Copies the contents of the id_rsa.pub file to your clipboard # Copies the contents of the id_ed25519.pub file to your clipboard
``` ```
{% tip %} {% tip %}
@@ -49,13 +49,13 @@ After adding a new SSH key to your {% data variables.product.product_name %} acc
{% windows %} {% windows %}
1. Copy the SSH key to your clipboard. 1. Copy the SSH public key to your clipboard.
If your SSH key file has a different name than the example code, modify the filename to match your current setup. When copying your key, don't add any newlines or whitespace. If your SSH public key file has a different name than the example code, modify the filename to match your current setup. When copying your key, don't add any newlines or whitespace.
```shell ```shell
$ clip &lt; ~/.ssh/id_rsa.pub $ clip &lt; ~/.ssh/id_ed25519.pub
# Copies the contents of the id_rsa.pub file to your clipboard # Copies the contents of the id_ed25519.pub file to your clipboard
``` ```
{% tip %} {% tip %}
@@ -80,16 +80,16 @@ After adding a new SSH key to your {% data variables.product.product_name %} acc
{% linux %} {% linux %}
1. Copy the SSH key to your clipboard. 1. Copy the SSH public key to your clipboard.
If your SSH key file has a different name than the example code, modify the filename to match your current setup. When copying your key, don't add any newlines or whitespace. If your SSH public key file has a different name than the example code, modify the filename to match your current setup. When copying your key, don't add any newlines or whitespace.
```shell ```shell
$ sudo apt-get install xclip $ sudo apt-get install xclip
# Downloads and installs xclip. If you don't have `apt-get`, you might need to use another installer (like `yum`) # Downloads and installs xclip. If you don't have `apt-get`, you might need to use another installer (like `yum`)
$ xclip -selection clipboard &lt; ~/.ssh/id_rsa.pub $ xclip -selection clipboard &lt; ~/.ssh/id_ed25519.pub
# Copies the contents of the id_rsa.pub file to your clipboard # Copies the contents of the id_ed25519.pub file to your clipboard
``` ```
{% tip %} {% tip %}

2
content/github/authenticating-to-github/creating-a-personal-access-token.md
View File

@@ -12,7 +12,7 @@ versions:
github-ae: '*' github-ae: '*'
--- ---
Personal access tokens (PATs) are an alternative to using passwords for authentication to {% data variables.product.product_name %} when using the [GitHub API](/v3/auth/#via-oauth-and-personal-access-tokens) or the [command line](#using-a-token-on-the-command-line). Personal access tokens (PATs) are an alternative to using passwords for authentication to {% data variables.product.product_name %} when using the [GitHub API](/rest/overview/other-authentication-methods#via-oauth-and-personal-access-tokens) or the [command line](#using-a-token-on-the-command-line).
{% if currentVersion == "free-pro-team@latest" %}If you want to use a PAT to access resources owned by an organization that uses SAML SSO, you must authorize the PAT. For more information, see "[About authentication with SAML single sign-on](/articles/about-authentication-with-saml-single-sign-on)" and "[Authorizing a personal access token for use with SAML single sign-on](/articles/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on)."{% endif %} {% if currentVersion == "free-pro-team@latest" %}If you want to use a PAT to access resources owned by an organization that uses SAML SSO, you must authorize the PAT. For more information, see "[About authentication with SAML single sign-on](/articles/about-authentication-with-saml-single-sign-on)" and "[Authorizing a personal access token for use with SAML single sign-on](/articles/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on)."{% endif %}

2
content/github/authenticating-to-github/creating-a-strong-password.md
View File

@@ -9,7 +9,7 @@ versions:
enterprise-server: '*' enterprise-server: '*'
--- ---
You must choose or generate a password for your {% data variables.product.product_name %} account that is: You must choose or generate a password for your {% data variables.product.product_name %} account that is at least:
- Eight characters long, if it includes a number and a lowercase letter, or - Eight characters long, if it includes a number and a lowercase letter, or
- 16 characters long with any combination of characters - 16 characters long with any combination of characters

12
content/github/authenticating-to-github/index.md
View File

@@ -35,11 +35,9 @@ versions:
{% link_in_list /reviewing-your-authorized-applications-oauth %} {% link_in_list /reviewing-your-authorized-applications-oauth %}
{% link_in_list /reviewing-your-security-log %} {% link_in_list /reviewing-your-security-log %}
{% link_in_list /removing-sensitive-data-from-a-repository %} {% link_in_list /removing-sensitive-data-from-a-repository %}
<!-- if currentVersion == "free-pro-team@latest" -->
{% link_in_list /about-anonymized-image-urls %} {% link_in_list /about-anonymized-image-urls %}
{% link_in_list /about-githubs-ip-addresses %} {% link_in_list /about-githubs-ip-addresses %}
{% link_in_list /githubs-ssh-key-fingerprints %} {% link_in_list /githubs-ssh-key-fingerprints %}
<!-- endif -->
{% link_in_list /sudo-mode %} {% link_in_list /sudo-mode %}
{% link_in_list /preventing-unauthorized-access %} {% link_in_list /preventing-unauthorized-access %}
{% topic_link_in_list /securing-your-account-with-two-factor-authentication-2fa %} {% topic_link_in_list /securing-your-account-with-two-factor-authentication-2fa %}
@@ -48,18 +46,14 @@ versions:
{% link_in_list /configuring-two-factor-authentication-recovery-methods %} {% link_in_list /configuring-two-factor-authentication-recovery-methods %}
{% link_in_list /accessing-github-using-two-factor-authentication %} {% link_in_list /accessing-github-using-two-factor-authentication %}
{% link_in_list /recovering-your-account-if-you-lose-your-2fa-credentials %} {% link_in_list /recovering-your-account-if-you-lose-your-2fa-credentials %}
<!-- if currentVersion == "free-pro-team@latest" -->
{% link_in_list /changing-two-factor-authentication-delivery-methods-for-your-mobile-device %} {% link_in_list /changing-two-factor-authentication-delivery-methods-for-your-mobile-device %}
{% link_in_list /countries-where-sms-authentication-is-supported %} {% link_in_list /countries-where-sms-authentication-is-supported %}
<!-- endif -->
{% link_in_list /disabling-two-factor-authentication-for-your-personal-account %} {% link_in_list /disabling-two-factor-authentication-for-your-personal-account %}
<!-- if currentVersion == "free-pro-team@latest" -->
{% topic_link_in_list /authenticating-with-saml-single-sign-on %} {% topic_link_in_list /authenticating-with-saml-single-sign-on %}
{% link_in_list /about-authentication-with-saml-single-sign-on %} {% link_in_list /about-authentication-with-saml-single-sign-on %}
{% link_in_list /authorizing-an-ssh-key-for-use-with-saml-single-sign-on %} {% link_in_list /authorizing-an-ssh-key-for-use-with-saml-single-sign-on %}
{% link_in_list /authorizing-a-personal-access-token-for-use-with-saml-single-sign-on %} {% link_in_list /authorizing-a-personal-access-token-for-use-with-saml-single-sign-on %}
{% link_in_list /viewing-and-managing-your-active-saml-sessions %} {% link_in_list /viewing-and-managing-your-active-saml-sessions %}
<!-- endif -->
{% topic_link_in_list /connecting-to-github-with-ssh %} {% topic_link_in_list /connecting-to-github-with-ssh %}
{% link_in_list /about-ssh %} {% link_in_list /about-ssh %}
{% link_in_list /checking-for-existing-ssh-keys %} {% link_in_list /checking-for-existing-ssh-keys %}
@@ -68,13 +62,9 @@ versions:
{% link_in_list /testing-your-ssh-connection %} {% link_in_list /testing-your-ssh-connection %}
{% link_in_list /working-with-ssh-key-passphrases %} {% link_in_list /working-with-ssh-key-passphrases %}
{% topic_link_in_list /troubleshooting-ssh %} {% topic_link_in_list /troubleshooting-ssh %}
<!-- if currentVersion == "free-pro-team@latest" -->
{% link_in_list /using-ssh-over-the-https-port %} {% link_in_list /using-ssh-over-the-https-port %}
<!-- endif -->
{% link_in_list /recovering-your-ssh-key-passphrase %} {% link_in_list /recovering-your-ssh-key-passphrase %}
<!-- if currentVersion == "free-pro-team@latest" -->
{% link_in_list /deleted-or-missing-ssh-keys %} {% link_in_list /deleted-or-missing-ssh-keys %}
<!-- endif -->
{% link_in_list /error-permission-denied-publickey %} {% link_in_list /error-permission-denied-publickey %}
{% link_in_list /error-bad-file-number %} {% link_in_list /error-bad-file-number %}
{% link_in_list /error-key-already-in-use %} {% link_in_list /error-key-already-in-use %}
@@ -82,9 +72,7 @@ versions:
{% link_in_list /error-permission-to-userrepo-denied-to-userother-repo %} {% link_in_list /error-permission-to-userrepo-denied-to-userother-repo %}
{% link_in_list /error-agent-admitted-failure-to-sign %} {% link_in_list /error-agent-admitted-failure-to-sign %}
{% link_in_list /error-ssh-add-illegal-option----k %} {% link_in_list /error-ssh-add-illegal-option----k %}
<!-- if currentVersion == "free-pro-team@latest" -->
{% link_in_list /error-ssl-certificate-problem-verify-that-the-ca-cert-is-ok %} {% link_in_list /error-ssl-certificate-problem-verify-that-the-ca-cert-is-ok %}
<!-- endif -->
{% link_in_list /error-were-doing-an-ssh-key-audit %} {% link_in_list /error-were-doing-an-ssh-key-audit %}
{% topic_link_in_list /managing-commit-signature-verification %} {% topic_link_in_list /managing-commit-signature-verification %}
{% link_in_list /about-commit-signature-verification %} {% link_in_list /about-commit-signature-verification %}

10
content/github/building-a-strong-community/index.md
View File

@@ -13,21 +13,15 @@ versions:
### Table of Contents ### Table of Contents
{% topic_link_in_list /setting-up-your-project-for-healthy-contributions %} {% topic_link_in_list /setting-up-your-project-for-healthy-contributions %}
<!-- if currentVersion == "free-pro-team@latest" -->
{% link_in_list /about-community-management-and-moderation %} {% link_in_list /about-community-management-and-moderation %}
{% link_in_list /about-community-profiles-for-public-repositories %} {% link_in_list /about-community-profiles-for-public-repositories %}
{% link_in_list /accessing-a-projects-community-profile %} {% link_in_list /accessing-a-projects-community-profile %}
{% link_in_list /adding-a-code-of-conduct-to-your-project %} {% link_in_list /adding-a-code-of-conduct-to-your-project %}
<!-- endif -->
{% link_in_list /setting-guidelines-for-repository-contributors %} {% link_in_list /setting-guidelines-for-repository-contributors %}
{% link_in_list /adding-a-license-to-a-repository %} {% link_in_list /adding-a-license-to-a-repository %}
{% link_in_list /adding-support-resources-to-your-project %} {% link_in_list /adding-support-resources-to-your-project %}
<!-- if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.16" -->
{% link_in_list /creating-a-default-community-health-file %} {% link_in_list /creating-a-default-community-health-file %}
<!-- endif -->
<!-- if currentVersion == "free-pro-team@latest" -->
{% link_in_list /encouraging-helpful-contributions-to-your-project-with-labels %} {% link_in_list /encouraging-helpful-contributions-to-your-project-with-labels %}
<!-- endif -->
{% topic_link_in_list /using-templates-to-encourage-useful-issues-and-pull-requests %} {% topic_link_in_list /using-templates-to-encourage-useful-issues-and-pull-requests %}
{% link_in_list /about-issue-and-pull-request-templates %} {% link_in_list /about-issue-and-pull-request-templates %}
{% link_in_list /configuring-issue-templates-for-your-repository %} {% link_in_list /configuring-issue-templates-for-your-repository %}
@@ -42,7 +36,6 @@ versions:
{% link_in_list /tracking-changes-in-a-comment %} {% link_in_list /tracking-changes-in-a-comment %}
{% link_in_list /managing-how-contributors-report-abuse-in-your-organizations-repository %} {% link_in_list /managing-how-contributors-report-abuse-in-your-organizations-repository %}
{% link_in_list /managing-reported-content-in-your-organizations-repository %} {% link_in_list /managing-reported-content-in-your-organizations-repository %}
<!-- if currentVersion == "free-pro-team@latest" -->
{% topic_link_in_list /maintaining-your-safety-on-github %} {% topic_link_in_list /maintaining-your-safety-on-github %}
{% link_in_list /blocking-a-user-from-your-personal-account %} {% link_in_list /blocking-a-user-from-your-personal-account %}
{% link_in_list /viewing-users-youve-blocked-from-your-personal-account %} {% link_in_list /viewing-users-youve-blocked-from-your-personal-account %}
@@ -51,7 +44,6 @@ versions:
{% link_in_list /viewing-users-who-are-blocked-from-your-organization %} {% link_in_list /viewing-users-who-are-blocked-from-your-organization %}
{% link_in_list /unblocking-a-user-from-your-organization %} {% link_in_list /unblocking-a-user-from-your-organization %}
{% link_in_list /reporting-abuse-or-spam %} {% link_in_list /reporting-abuse-or-spam %}
<!-- endif -->
{% topic_link_in_list /documenting-your-project-with-wikis %} {% topic_link_in_list /documenting-your-project-with-wikis %}
{% link_in_list /about-wikis %} {% link_in_list /about-wikis %}
{% link_in_list /adding-or-editing-wiki-pages %} {% link_in_list /adding-or-editing-wiki-pages %}
@@ -60,10 +52,8 @@ versions:
{% link_in_list /viewing-a-wikis-history-of-changes %} {% link_in_list /viewing-a-wikis-history-of-changes %}
{% link_in_list /changing-access-permissions-for-wikis %} {% link_in_list /changing-access-permissions-for-wikis %}
{% link_in_list /disabling-wikis %} {% link_in_list /disabling-wikis %}
<!-- if currentVersion == "free-pro-team@latest" -->
{% topic_link_in_list /collaborating-with-your-team %} {% topic_link_in_list /collaborating-with-your-team %}
{% link_in_list /about-team-discussions %} {% link_in_list /about-team-discussions %}
{% link_in_list /creating-a-team-discussion %} {% link_in_list /creating-a-team-discussion %}
{% link_in_list /editing-or-deleting-a-team-discussion %} {% link_in_list /editing-or-deleting-a-team-discussion %}
{% link_in_list /pinning-a-team-discussion %} {% link_in_list /pinning-a-team-discussion %}
<!-- endif -->

4
content/github/collaborating-with-issues-and-pull-requests/about-branches.md
View File

@@ -23,7 +23,7 @@ You must have write access to a repository to create a branch, open a pull reque
### About the default branch ### About the default branch
{% data reusables.branches.new-repo-default-branch %} The default branch is the branch that {% data variables.product.prodname_dotcom %} displays when anyone visits your repository. The default branch is also the initial branch that Git checks out locally out when someone clones the repository. {% data reusables.branches.default-branch-automatically-base-branch %} {% data reusables.branches.new-repo-default-branch %} The default branch is the branch that {% data variables.product.prodname_dotcom %} displays when anyone visits your repository. The default branch is also the initial branch that Git checks out locally when someone clones the repository. {% data reusables.branches.default-branch-automatically-base-branch %}
By default, {% data variables.product.product_name %} names the default branch {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" or currentVersion == "github-ae@latest" %}`main`{% else %}`master`{% endif %} in any new repository. By default, {% data variables.product.product_name %} names the default branch {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" or currentVersion == "github-ae@latest" %}`main`{% else %}`master`{% endif %} in any new repository.
@@ -75,7 +75,7 @@ When a branch is protected:
- If required pull request reviews are enabled on the branch, you won't be able to merge changes into the branch until all requirements in the pull request review policy have been met. For more information, see "[Merging a pull request](/articles/merging-a-pull-request)." - If required pull request reviews are enabled on the branch, you won't be able to merge changes into the branch until all requirements in the pull request review policy have been met. For more information, see "[Merging a pull request](/articles/merging-a-pull-request)."
- If required review from a code owner is enabled on a branch, and a pull request modifies code that has an owner, a code owner must approve the pull request before it can be merged. For more information, see "[About code owners](/articles/about-code-owners)." - If required review from a code owner is enabled on a branch, and a pull request modifies code that has an owner, a code owner must approve the pull request before it can be merged. For more information, see "[About code owners](/articles/about-code-owners)."
- If required commit signing is enabled on a branch, you won't be able to push any commits to the branch that are not signed and verified. For more information, see "[About commit signature verification](/articles/about-commit-signature-verification)" and "[About required commit signing](/articles/about-required-commit-signing)."{% if currentVersion == "free-pro-team@latest" or currentVersion == "github-ae@latest" or currentVersion ver_gt "enterprise-server@2.21" %} - If required commit signing is enabled on a branch, you won't be able to push any commits to the branch that are not signed and verified. For more information, see "[About commit signature verification](/articles/about-commit-signature-verification)" and "[About required commit signing](/articles/about-required-commit-signing)."{% if currentVersion == "free-pro-team@latest" or currentVersion == "github-ae@latest" or currentVersion ver_gt "enterprise-server@2.21" %}
- If you use {% data variables.product.prodname_dotcom %} 's conflict editor to fix conflicts for a pull request that you created from a protected branch, {% data variables.product.prodname_dotcom %} helps you to create an alternative branch for the pull request, so that your resolution of the conflicts can be merged. For more information, see "[Resolving a merge conflict on {% data variables.product.prodname_dotcom %}](/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github)."{% endif %} - If you use {% data variables.product.prodname_dotcom %}'s conflict editor to fix conflicts for a pull request that you created from a protected branch, {% data variables.product.prodname_dotcom %} helps you to create an alternative branch for the pull request, so that your resolution of the conflicts can be merged. For more information, see "[Resolving a merge conflict on {% data variables.product.prodname_dotcom %}](/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github)."{% endif %}
### Further reading ### Further reading

2
content/github/collaborating-with-issues-and-pull-requests/about-status-checks.md
View File

@@ -29,7 +29,7 @@ There are two types of status checks on {% data variables.product.product_name %
_Checks_ are different from _statuses_ in that they provide line annotations, more detailed messaging, and are only available for use with {% data variables.product.prodname_github_app %}s. _Checks_ are different from _statuses_ in that they provide line annotations, more detailed messaging, and are only available for use with {% data variables.product.prodname_github_app %}s.
Organization owners and users with push access to a repository can create checks and statuses with {% data variables.product.product_name %}'s API. For more information, see "[Checks](/v3/checks/)" and "[Statuses](/v3/repos/statuses/)." Organization owners and users with push access to a repository can create checks and statuses with {% data variables.product.product_name %}'s API. For more information, see "[Checks](/rest/reference/checks)" and "[Statuses](/rest/reference/repos#statuses)."
### Checks ### Checks

6
content/github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository.md
View File

@@ -25,7 +25,11 @@ versions:
{% data reusables.pull_requests.automatically-delete-branches %} {% data reusables.pull_requests.automatically-delete-branches %}
If the branch you want to delete is the repository's default branch, you must choose a new default branch before deleting the branch. For more information, see "[Changing the default branch](/github/administering-a-repository/changing-the-default-branch)." {% note %}
**Note:** If the branch you want to delete is the repository's default branch, you must choose a new default branch before deleting the branch. For more information, see "[Changing the default branch](/github/administering-a-repository/changing-the-default-branch)."
{% endnote %}
If the branch you want to delete is associated with an open pull request, you must merge or close the pull request before deleting the branch. For more information, see "[Merging a pull request](/github/collaborating-with-issues-and-pull-requests/merging-a-pull-request)" or "[Closing a pull request](/github/collaborating-with-issues-and-pull-requests/closing-a-pull-request)." If the branch you want to delete is associated with an open pull request, you must merge or close the pull request before deleting the branch. For more information, see "[Merging a pull request](/github/collaborating-with-issues-and-pull-requests/merging-a-pull-request)" or "[Closing a pull request](/github/collaborating-with-issues-and-pull-requests/closing-a-pull-request)."

8
content/github/collaborating-with-issues-and-pull-requests/index.md
View File

@@ -29,9 +29,7 @@ versions:
{% link_in_list /what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility %} {% link_in_list /what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility %}
{% topic_link_in_list /collaborating-on-repositories-with-code-quality-features %} {% topic_link_in_list /collaborating-on-repositories-with-code-quality-features %}
{% link_in_list /about-status-checks %} {% link_in_list /about-status-checks %}
<!-- if enterpriseServerVersions contains currentVersion -->
{% link_in_list /working-with-pre-receive-hooks %} {% link_in_list /working-with-pre-receive-hooks %}
<!-- endif -->
{% topic_link_in_list /proposing-changes-to-your-work-with-pull-requests %} {% topic_link_in_list /proposing-changes-to-your-work-with-pull-requests %}
{% link_in_list /about-branches %} {% link_in_list /about-branches %}
{% link_in_list /creating-and-deleting-branches-within-your-repository %} {% link_in_list /creating-and-deleting-branches-within-your-repository %}
@@ -39,9 +37,7 @@ versions:
{% link_in_list /about-comparing-branches-in-pull-requests %} {% link_in_list /about-comparing-branches-in-pull-requests %}
{% link_in_list /creating-a-pull-request %} {% link_in_list /creating-a-pull-request %}
{% link_in_list /creating-a-pull-request-from-a-fork %} {% link_in_list /creating-a-pull-request-from-a-fork %}
<!-- if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.16" -->
{% link_in_list /changing-the-stage-of-a-pull-request %} {% link_in_list /changing-the-stage-of-a-pull-request %}
<!-- endif -->
{% link_in_list /requesting-a-pull-request-review %} {% link_in_list /requesting-a-pull-request-review %}
{% link_in_list /changing-the-base-branch-of-a-pull-request %} {% link_in_list /changing-the-base-branch-of-a-pull-request %}
{% link_in_list /committing-changes-to-a-pull-request-branch-created-from-a-fork %} {% link_in_list /committing-changes-to-a-pull-request-branch-created-from-a-fork %}
@@ -52,15 +48,11 @@ versions:
{% topic_link_in_list /reviewing-changes-in-pull-requests %} {% topic_link_in_list /reviewing-changes-in-pull-requests %}
{% link_in_list /about-pull-request-reviews %} {% link_in_list /about-pull-request-reviews %}
{% link_in_list /reviewing-proposed-changes-in-a-pull-request %} {% link_in_list /reviewing-proposed-changes-in-a-pull-request %}
<!-- if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.15" -->
{% link_in_list /filtering-files-in-a-pull-request %} {% link_in_list /filtering-files-in-a-pull-request %}
<!-- endif -->
{% link_in_list /finding-changed-methods-and-functions-in-a-pull-request %} {% link_in_list /finding-changed-methods-and-functions-in-a-pull-request %}
{% link_in_list /commenting-on-a-pull-request %} {% link_in_list /commenting-on-a-pull-request %}
{% link_in_list /viewing-a-pull-request-review %} {% link_in_list /viewing-a-pull-request-review %}
<!-- if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.16" -->
{% link_in_list /incorporating-feedback-in-your-pull-request %} {% link_in_list /incorporating-feedback-in-your-pull-request %}
<!-- endif -->
{% link_in_list /approving-a-pull-request-with-required-reviews %} {% link_in_list /approving-a-pull-request-with-required-reviews %}
{% link_in_list /dismissing-a-pull-request-review %} {% link_in_list /dismissing-a-pull-request-review %}
{% link_in_list /checking-out-pull-requests-locally %} {% link_in_list /checking-out-pull-requests-locally %}

2
content/github/committing-changes-to-your-project/index.md
View File

@@ -16,9 +16,7 @@ versions:
{% topic_link_in_list /creating-and-editing-commits %} {% topic_link_in_list /creating-and-editing-commits %}
{% link_in_list /about-commits %} {% link_in_list /about-commits %}
{% link_in_list /creating-a-commit-with-multiple-authors %} {% link_in_list /creating-a-commit-with-multiple-authors %}
<!-- if currentVersion == "free-pro-team@latest" -->
{% link_in_list /creating-a-commit-on-behalf-of-an-organization %} {% link_in_list /creating-a-commit-on-behalf-of-an-organization %}
<!-- endif -->
{% link_in_list /changing-a-commit-message %} {% link_in_list /changing-a-commit-message %}
{% topic_link_in_list /viewing-and-comparing-commits %} {% topic_link_in_list /viewing-and-comparing-commits %}
{% link_in_list /commit-branch-and-tag-labels %} {% link_in_list /commit-branch-and-tag-labels %}

8
content/github/creating-cloning-and-archiving-repositories/backing-up-a-repository.md
View File

@@ -10,7 +10,7 @@ versions:
--- ---
{% if currentVersion == "free-pro-team@latest" %} {% if currentVersion == "free-pro-team@latest" %}
To download an archive of your repository, you can use the API for user or organization migrations. For more information, see "[Migrations](/v3/migrations/)." To download an archive of your repository, you can use the API for user or organization migrations. For more information, see "[Migrations](/rest/reference/migrations)."
{% else %} {% else %}
You can download and back up your repositories manually: You can download and back up your repositories manually:
@@ -20,15 +20,15 @@ You can download and back up your repositories manually:
When you clone a repository or wiki, only Git data, such as project files and commit history, is downloaded. You can use our API to export other elements of your {% data variables.product.product_name %} repository to your local machine: When you clone a repository or wiki, only Git data, such as project files and commit history, is downloaded. You can use our API to export other elements of your {% data variables.product.product_name %} repository to your local machine:
- [Issues](/v3/issues/#list-issues-for-a-repository) - [Issues](/rest/reference/issues#list-issues-for-a-repository)
- [Pull requests](/v3/pulls/#list-pull-requests) - [Pull requests](/rest/reference/pulls#list-pull-requests)
- [Forks](/rest/reference/repos#list-forks) - [Forks](/rest/reference/repos#list-forks)
- [Comments](/rest/reference/issues#list-issue-comments-for-a-repository) - [Comments](/rest/reference/issues#list-issue-comments-for-a-repository)
- [Milestones](/rest/reference/issues#list-milestones) - [Milestones](/rest/reference/issues#list-milestones)
- [Labels](/rest/reference/issues#list-labels-for-a-repository) - [Labels](/rest/reference/issues#list-labels-for-a-repository)
- [Watchers](/rest/reference/activity#list-watchers) - [Watchers](/rest/reference/activity#list-watchers)
- [Stargazers](/rest/reference/activity#list-stargazers) - [Stargazers](/rest/reference/activity#list-stargazers)
- [Projects](/v3/projects/#list-repository-projects) - [Projects](/rest/reference/projects#list-repository-projects)
{% endif %} {% endif %}
Once you have {% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %}a local version of all the content you want to back up, you can create a zip archive and {% else %}downloaded your archive, you can {% endif %}copy it to an external hard drive and/or upload it to a cloud-based backup service such as [Google Drive](https://www.google.com/drive/) or [Dropbox](https://www.dropbox.com/). Once you have {% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %}a local version of all the content you want to back up, you can create a zip archive and {% else %}downloaded your archive, you can {% endif %}copy it to an external hard drive and/or upload it to a cloud-based backup service such as [Google Drive](https://www.google.com/drive/) or [Dropbox](https://www.dropbox.com/).

6
content/github/creating-cloning-and-archiving-repositories/index.md
View File

@@ -18,16 +18,12 @@ versions:
{% link_in_list /about-repositories %} {% link_in_list /about-repositories %}
{% link_in_list /about-repository-visibility %} {% link_in_list /about-repository-visibility %}
{% link_in_list /creating-a-new-repository %} {% link_in_list /creating-a-new-repository %}
<!-- if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.17" -->
{% link_in_list /creating-a-repository-from-a-template %} {% link_in_list /creating-a-repository-from-a-template %}
<!-- endif -->
{% link_in_list /about-readmes %} {% link_in_list /about-readmes %}
{% link_in_list /about-code-owners %} {% link_in_list /about-code-owners %}
{% link_in_list /about-repository-languages %} {% link_in_list /about-repository-languages %}
{% link_in_list /licensing-a-repository %} {% link_in_list /licensing-a-repository %}
<!-- if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.17" -->
{% link_in_list /creating-a-template-repository %} {% link_in_list /creating-a-template-repository %}
<!-- endif -->
{% link_in_list /creating-an-issues-only-repository %} {% link_in_list /creating-an-issues-only-repository %}
{% link_in_list /limits-for-viewing-content-and-diffs-in-a-repository %} {% link_in_list /limits-for-viewing-content-and-diffs-in-a-repository %}
{% link_in_list /duplicating-a-repository %} {% link_in_list /duplicating-a-repository %}
@@ -39,8 +35,6 @@ versions:
{% topic_link_in_list /archiving-a-github-repository %} {% topic_link_in_list /archiving-a-github-repository %}
{% link_in_list /about-archiving-repositories %} {% link_in_list /about-archiving-repositories %}
{% link_in_list /archiving-repositories %} {% link_in_list /archiving-repositories %}
<!-- if currentVersion == "free-pro-team@latest" -->
{% link_in_list /about-archiving-content-and-data-on-github %} {% link_in_list /about-archiving-content-and-data-on-github %}
{% link_in_list /referencing-and-citing-content %} {% link_in_list /referencing-and-citing-content %}
<!-- endif -->
{% link_in_list /backing-up-a-repository %} {% link_in_list /backing-up-a-repository %}

2
content/github/creating-cloning-and-archiving-repositories/licensing-a-repository.md
View File

@@ -74,7 +74,7 @@ When you search by a family license, your results will include all licenses in t
### Detecting a license ### Detecting a license
[The open source Ruby gem Licensee](https://github.com/benbalter/licensee) compares the repository's *LICENSE* file to a short list of known licenses. Licensee also provides the [Licenses API](/v3/licenses/) and [gives us insight into how repositories on {% data variables.product.product_name %} are licensed](https://github.com/blog/1964-open-source-license-usage-on-github-com). If your repository is using a license that isn't listed on the [Choose a License website](http://choosealicense.com/appendix/), you can [request including the license](https://github.com/github/choosealicense.com/blob/gh-pages/CONTRIBUTING.md#adding-a-license). [The open source Ruby gem Licensee](https://github.com/benbalter/licensee) compares the repository's *LICENSE* file to a short list of known licenses. Licensee also provides the [Licenses API](/rest/reference/licenses) and [gives us insight into how repositories on {% data variables.product.product_name %} are licensed](https://github.com/blog/1964-open-source-license-usage-on-github-com). If your repository is using a license that isn't listed on the [Choose a License website](http://choosealicense.com/appendix/), you can [request including the license](https://github.com/github/choosealicense.com/blob/gh-pages/CONTRIBUTING.md#adding-a-license).
If your repository is using a license that is listed on the Choose a License website and it's not displaying clearly at the top of the repository page, it may contain multiple licenses or other complexity. To have your license detected, simplify your *LICENSE* file and note the complexity somewhere else, such as your repository's *README* file. If your repository is using a license that is listed on the Choose a License website and it's not displaying clearly at the top of the repository page, it may contain multiple licenses or other complexity. To have your license detected, simplify your *LICENSE* file and note the complexity somewhere else, such as your repository's *README* file.

2
content/github/extending-github/git-automation-with-oauth-tokens.md
View File

@@ -43,4 +43,4 @@ To avoid these prompts, you can use Git password caching. For information, see "
### Further reading ### Further reading
- "[Authorizing OAuth Apps](/v3/oauth/)" - "[Authorizing OAuth Apps](/developers/apps/authorizing-oauth-apps)"

2
content/github/finding-security-vulnerabilities-and-errors-in-your-code/about-code-scanning.md
View File

@@ -21,7 +21,7 @@ You can use {% data variables.product.prodname_code_scanning %} to find, triage,
If {% data variables.product.prodname_code_scanning %} finds a potential vulnerability or error in your code, {% data variables.product.prodname_dotcom %} displays an alert in the repository. After you fix the code that triggered the alert, {% data variables.product.prodname_dotcom %} closes the alert. For more information, see "[Managing {% data variables.product.prodname_code_scanning %} alerts for your repository](/github/finding-security-vulnerabilities-and-errors-in-your-code/managing-code-scanning-alerts-for-your-repository)." If {% data variables.product.prodname_code_scanning %} finds a potential vulnerability or error in your code, {% data variables.product.prodname_dotcom %} displays an alert in the repository. After you fix the code that triggered the alert, {% data variables.product.prodname_dotcom %} closes the alert. For more information, see "[Managing {% data variables.product.prodname_code_scanning %} alerts for your repository](/github/finding-security-vulnerabilities-and-errors-in-your-code/managing-code-scanning-alerts-for-your-repository)."
To monitor results from {% data variables.product.prodname_code_scanning %} across your repositories or your organization, you can use the {% data variables.product.prodname_code_scanning %} API. To monitor results from {% data variables.product.prodname_code_scanning %} across your repositories or your organization, you can use the {% data variables.product.prodname_code_scanning %} API.
For more information about API endpoints, see "[{% data variables.product.prodname_code_scanning_capc %}](/v3/code-scanning)." For more information about API endpoints, see "[{% data variables.product.prodname_code_scanning_capc %}](/rest/reference/code-scanning)."
To get started with {% data variables.product.prodname_code_scanning %}, see "[Enabling {% data variables.product.prodname_code_scanning %} for a repository](/github/finding-security-vulnerabilities-and-errors-in-your-code/enabling-code-scanning-for-a-repository)." To get started with {% data variables.product.prodname_code_scanning %}, see "[Enabling {% data variables.product.prodname_code_scanning %} for a repository](/github/finding-security-vulnerabilities-and-errors-in-your-code/enabling-code-scanning-for-a-repository)."

36
content/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning.md
View File

@@ -52,6 +52,32 @@ The default {% data variables.product.prodname_codeql_workflow %} uses the `pull
For more information about the `pull_request` event, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestbranchestags)." For more information about the `pull_request` event, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestbranchestags)."
#### Avoiding unnecessary scans of pull requests
You might want to avoid a code scan being triggered on specific pull requests targeted against the default branch, irrespective of which files have been changed. You can configure this by specifying `on:pull_request:paths-ignore` or `on:pull_request:paths` in the {% data variables.product.prodname_code_scanning %} workflow. For example, if the only changes in a pull request are to files with the file extensions `.md` or `.txt` you can use the following `paths-ignore` array.
``` yaml
on:
push:
branches: [main, protected]
pull_request:
branches: [main]
paths-ignore:
- '**/*.md'
- '**/*.txt'
```
{% note %}
**Notes**
* `on:pull_request:paths-ignore` and `on:pull_request:paths` set conditions that determine whether the actions in the workflow will run on a pull request. They don't determine what files will be analyzed when the actions _are_ run. When a pull request contains any files that are not matched by `on:pull_request:paths-ignore` or `on:pull_request:paths`, the workflow runs the actions and scans all of the files changed in the pull request, including those matched by `on:pull_request:paths-ignore` or `on:pull_request:paths`, unless the files have been excluded. For information on how to exclude files from analysis, see "[Specifying directories to scan](#specifying-directories-to-scan)."
* For {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} workflow files, don't use the `paths-ignore` or `paths` keywords with the `on:push` event as this is likely to cause missing analyses. For accurate results, {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} needs to be able to compare new changes with the analysis of the previous commit.
{% endnote %}
For more information about using `on:pull_request:paths-ignore` and `on:pull_request:paths` to determine when a workflow will run for a pull request, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestpaths)."
#### Scanning on a schedule #### Scanning on a schedule
If you use the default {% data variables.product.prodname_codeql_workflow %}, the workflow will scan the code in your repository once a week, in addition to the scans triggered by events. To adjust this schedule, edit the `cron` value in the workflow. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#onschedule)." If you use the default {% data variables.product.prodname_codeql_workflow %}, the workflow will scan the code in your repository once a week, in addition to the scans triggered by events. To adjust this schedule, edit the `cron` value in the workflow. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#onschedule)."
@@ -162,7 +188,7 @@ jobs:
fi fi
# Set the `CODEQL-PYTHON` environment variable to the Python executable # Set the `CODEQL-PYTHON` environment variable to the Python executable
# that includes the dependencies # that includes the dependencies
echo "::set-env name=CODEQL_PYTHON::$(which python)" echo "CODEQL_PYTHON=$(which python)" >> $GITHUB_ENV
- name: Initialize CodeQL - name: Initialize CodeQL
uses: github/codeql-action/init@v1 uses: github/codeql-action/init@v1
with: with:
@@ -235,13 +261,13 @@ If you only want to run custom queries, you can disable the default security que
#### Specifying directories to scan #### Specifying directories to scan
For the interpreted languages that {% data variables.product.prodname_codeql %} supports (Python and JavaScript/TypeScript), you can restrict {% data variables.product.prodname_code_scanning %} to files in specific directories by adding a `paths` array to the configuration file. You can exclude the files in specific directories from scans by adding a `paths-ignore` array. For the interpreted languages that {% data variables.product.prodname_codeql %} supports (Python and JavaScript/TypeScript), you can restrict {% data variables.product.prodname_code_scanning %} to files in specific directories by adding a `paths` array to the configuration file. You can exclude the files in specific directories from analysis by adding a `paths-ignore` array.
``` yaml ``` yaml
paths: paths:
- src - src
paths-ignore: paths-ignore:
- node_modules - src/node_modules
- '**/*.test.js' - '**/*.test.js'
``` ```
@@ -254,7 +280,7 @@ paths-ignore:
{% endnote %} {% endnote %}
For C/C++, C#, and Java, if you want to limit {% data variables.product.prodname_code_scanning %} to specific directories in your project, you must specify appropriate build steps in the workflow. The commands you need to use to exclude a directory from the build will depend on your build system. For more information, see "[Configuring the {% data variables.product.prodname_codeql %} workflow for compiled languages](/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-the-codeql-workflow-for-compiled-languages#adding-build-steps-for-a-compiled-language)." For compiled languages, if you want to limit {% data variables.product.prodname_code_scanning %} to specific directories in your project, you must specify appropriate build steps in the workflow. The commands you need to use to exclude a directory from the build will depend on your build system. For more information, see "[Configuring the {% data variables.product.prodname_codeql %} workflow for compiled languages](/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-the-codeql-workflow-for-compiled-languages#adding-build-steps-for-a-compiled-language)."
You can quickly analyze small portions of a monorepo when you modify code in specific directories. You'll need to both exclude directories in your build steps and use the `paths-ignore` and `paths` keywords for [`on.<push|pull_request>`](/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestpaths) in your workflow. You can quickly analyze small portions of a monorepo when you modify code in specific directories. You'll need to both exclude directories in your build steps and use the `paths-ignore` and `paths` keywords for [`on.<push|pull_request>`](/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestpaths) in your workflow.

Some files were not shown because too many files have changed in this diff Show More